AuditCakeDevelopersBook a walkthrough

Carriers and vendors

AuditCake serves two kinds of clients — carriers that issue policies and own the audits, and vendors that service audits on behalf of carriers. The same API serves both; what differs is whose key authenticates the call and how the audit is routed.

One audit, one owner, one operator

Every audit has a single owner (the carrier — it always retains visibility) and a single operator (whoever does the work). The operator is either the carrier itself, or one of the vendors the carrier works with. Audits are never copied or duplicated when work is delegated: there is one canonical record shared between the carrier and the assigned vendor.

How accounts get set up

AuditCake creates every carrier and vendor account — there is no self-signup. When two parties want to work together, AuditCake registers the relationship on both sides: the carrier sees the vendor's alias in Settings → Developer, and the vendor sees the carriers it serves under its own Settings. AuditCake creates and removes relationships on request. Any carrier can work with any vendor, and any vendor can work with any carrier.

Integration modes

The same POST /audits endpoint serves all three modes. Two things vary across them:

  • Which kind of API key authenticates the call.
  • Whether an assignment block is included.

1. Carrier-direct

The carrier services its own audits — no vendor involved.

AuthThe carrier's API key.
BodyNo vendor assignment block.
ResultThe audit is owned by the carrier and not assigned to any vendor. The carrier is the operator.

2. Carrier-directed handoff

The carrier hands off each audit to a specific vendor it has registered with AuditCake.

AuthThe carrier's API key.
Body"assignment": { "vendor": "<the carrier's code for the vendor>" }
ResultThe audit is assigned to that vendor on create. The vendor becomes the operator; the carrier retains visibility.

The code is a carrier-unique alias AuditCake generates for each registered vendor, shown in the carrier's Settings → Developer → Vendor codes section next to the vendor's name. It is used verbatim in assignment.vendor. Unrecognized codes are rejected with 400. AuditCake's internal vendor identifier is never part of the API — the alias is the public handle.

3. Vendor-initiated

A vendor creates audits on behalf of a carrier they service.

AuthA vendor API key scoped to that vendor's relationship with that carrier. AuditCake issues one per (carrier, vendor) pair.
BodyAny assignment in the body is ignored — the key already identifies who is calling and which carrier the audit belongs to.
ResultThe audit is owned by the carrier (per the key's scope) and assigned to the vendor (per the key's identity). The vendor is the operator.

Vendor-scoped keys are issued by AuditCake at relationship setup. Each (carrier, vendor) pair has its own key, scoped to that single relationship and rotatable on its own.

Picking a mode

CallerGoalUse
A carrier servicing its own auditsrun them in-houseMode 1
A carrier with vendor partners on AuditCakepick the vendor per auditMode 2
A vendor with one or more carriers on AuditCakesubmit audits for a carrierMode 3

An integration that spans modes — say, self-service for some lines and vendor delegation for others — should use Mode 2 per audit. It is the most explicit and routes each audit exactly where it belongs.

Example: directed handoff (Mode 2)

A carrier sends an audit and names the vendor it should go to, using the alias from Settings → Developer → Vendor codes:

curl -X POST https://auditcake.com/api/v1/audits \
  -H "x-api-key: ack_live_<carrier-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "auditType": "ANNUAL",
    "serviceType": "PHYSICAL",
    "sources": { "carrierControlId": "CTRL-2026-00042" },
    "policy": {
      "number": "GL-555-0042",
      "termStart": "2025-01-01",
      "termEnd": "2026-01-01"
    },
    "insured": { "legalName": "Pineview Bakery LLC" },
    "classCodes": [{ "code": "10220" }],
    "assignment": { "vendor": "vco_AB12CD" }
  }'

The response carries the audit back with the assigned vendor on it; AuditCake's internal vendor id is never needed to confirm the routing.

Example: vendor-initiated (Mode 3)

A vendor submits an audit on behalf of a carrier they service, authenticating with the vendor-scoped key AuditCake issued for that relationship. No assignment block is needed — the key already identifies the carrier and the vendor:

curl -X POST https://auditcake.com/api/v1/audits \
  -H "x-api-key: ack_live_<carrier-vendor-pair-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "auditType": "ANNUAL",
    "serviceType": "PHYSICAL",
    "sources": { "carrierControlId": "VND-2026-00042" },
    "policy": {
      "number": "GL-555-0042",
      "termStart": "2025-01-01",
      "termEnd": "2026-01-01"
    },
    "insured": { "legalName": "Pineview Bakery LLC" },
    "classCodes": [{ "code": "10220" }]
  }'

The audit is owned by the carrier the key is scoped to and assigned to the vendor presenting the key. Any assignment field in the body is ignored.

A vendor working with multiple carriers receives a separate key for each — use the one matching the carrier the audit belongs to.

Next: Integrations →