AuditCakeDevelopersBook a walkthrough

Create an audit

Submit an audit to AuditCake. It is created as production work and enters the audit lifecycle immediately.

POSThttps://auditcake.com/api/v1/audits

Send a JSON body with the Content-Type: application/json and x-api-key headers. AuditCake maps the payload into its model, assigns an audit code, and returns it.

Request body

Top level

FieldRequiredTypeDescription
auditTypeRequiredenumOne of ANNUAL, CANCELLATION, INTERIM, MULTI_YEAR, NEW_ACCOUNT, PRE_AUDIT, REOPEN_CLOSEOUT, REOPEN_DISPUTE, RUSH.
serviceTypeRequiredenumHow the audit is conducted: PHYSICAL, PHONE, VIRTUAL, VOLUNTARY, or SURVEY.
sourcesRequiredobjectIdentifiers for this audit, set by the caller. See below.
policyRequiredobjectThe policy being audited. See below.
insuredRequiredobjectThe audited business. See below.
auditWindowOptionalobjectThe audit period and key dates. Every field is optional and computed when omitted — see below.
locationOptionalobjectThe insured's location and address. Use this for a single-location audit. For a multi-location policy, send locations instead.
locationsOptionalarrayThe risk locations on the policy, when an audit covers more than one. Each entry has a number and an address; tag each class code to its location with classCodes[].location. See below.
agencyOptionalobjectThe agency of record — name, optional agencyCode, and an optional agent contact. See below.
workingContactOptionalobjectWho AuditCake should contact — name, email, phone, role. AuditCake normalizes these on intake: the name is parsed into parts, the email is typo-corrected, and the phone is converted to E.164 — the original values are always kept alongside.
recordsContactOptionalobjectThe party that holds the records, when it differs from the insured contact — name, contact, email, phone. See below.
classCodesOptionalarrayThe class codes on the policy with their estimated exposure. AuditCake resolves each code's coverage line and exposure base from its catalog. Send them whenever they are known. An order placed before the class codes are on the policy may omit them — the audit is created and held for review until they are added, rather than rejected. See below.

sources

FieldRequiredTypeDescription
carrierControlIdRequiredstringA stable, unique id for this audit. Used as the idempotency key — see below.
orderNumberOptionalstringThe order number, if any.
referenceNumberOptionalstringAny additional reference to carry on the audit.
accountNumberOptionalstringA stable account number for the insured. Helps AuditCake link audits across years.

agency

FieldRequiredTypeDescription
nameOptionalstringThe agency of record's name.
agencyCodeOptionalstringThe carrier's producer code for the agency, if any.
contactOptionalobjectThe agent of record — name, email, phone. Normalized on intake the same way as workingContact: the name is parsed into parts, the email is typo-corrected, and the phone is converted to E.164 — the original values are always kept alongside.

policy

FieldRequiredTypeDescription
numberRequiredstringThe policy number.
termStartRequireddatePolicy term start, YYYY-MM-DD.
termEndRequireddatePolicy term end, YYYY-MM-DD.
estimatedPremiumOptionalamountThe estimated annual premium, e.g. "12500.00".

The policy's coverage lines are not sent directly — AuditCake derives them from the submitted class codes.

insured, location, classCodes

FieldRequiredTypeDescription
insured.legalNameRequiredstringThe insured's legal business name.
insured.dbaNameOptionalstringDoing-business-as name.
insured.feinOptionalstringFederal Employer Identification Number.
location.addressOptionalobjectline1, line2, city, state, zip. Single-location audits only — omit when sending locations.
locations[].numberRequired*stringYour location number for this risk location, e.g. "001". Required for each entry when locations is present; must be unique. classCodes[].location references it.
locations[].addressOptionalobjectThe location's address — line1, line2, city, state, zip.
locations[].nicknameOptionalstringA human label for the location, e.g. "Main warehouse".
classCodes[].codeRequiredstringThe class code as it appears on the policy. AuditCake looks it up in its class-code catalog to resolve the coverage line and exposure base.
classCodes[].locationOptionalstringThe risk location this code is rated at — must match one of locations[].number. Required to disambiguate when an audit covers multiple locations; omit for a single-location audit.
classCodes[].estimatedExposureOptionalamountEstimated exposure for the row, e.g. "500000.00".
classCodes[].lineOptionalenumCoverage line — only needed for a code AuditCake's catalog doesn't carry. One of GL, LL, WC, AUTO, PROPERTY.
classCodes[].basisOptionalenumExposure base — only needed alongside line for an uncatalogued code. One of GROSS_SALES, PAYROLL, AREA, TOTAL_COST, ADMISSIONS, GALLONS, UNITS.

auditWindow

The whole object is optional. AuditCake computes any omitted field: the period defaults to the policy term, orderedAt to the time of the request, and dueAt / stopContactAt from orderedAt and the carrier's service standards. Any supplied value always wins over the computed default.

An audit ordered before the period it audits has closed cannot be worked yet, so AuditCake parks it and starts it a few days before the period ends. startedAt reflects that later date rather than the order date, so the gap between startedAt and dueAt is the time actually available to complete the audit. The due date is unaffected — it is always measured from orderedAt.

FieldRequiredTypeDescription
periodStartOptionaldateStart of the period under audit. Defaults to the policy term start.
periodEndOptionaldateEnd of the period under audit. Defaults to the policy term end.
orderedAtOptionaldateWhen the audit was ordered. Defaults to the time of the request.
startedAtOptionaldateWhen AuditCake starts work. Defaults to orderedAt, or — when the audited period has not closed yet — to shortly before periodEnd, which is the earliest the audit can be worked.
dueAtOptionaldateWhen the audit is due. Defaults to orderedAt plus the carrier's standard audit duration.
stopContactAtOptionaldateWhen AuditCake stops reaching out to the insured. Defaults to dueAt minus the carrier's standard stop-contact window.

assignment — pointing the audit at a servicer

How an audit is routed depends on which integration mode the caller is using:

  • With a carrier key and no assignment block, the carrier services the audit itself (Mode 1).
  • With a carrier key and assignment.vendor set, the audit is handed off to that vendor (Mode 2). The value is the carrier-unique code AuditCake generated for the vendor, shown next to its name in Settings → Developer → Vendor codes.
  • With a vendor key, the assignment block is ignored — the key already identifies which carrier the audit belongs to and which vendor is servicing it (Mode 3).
FieldRequiredTypeDescription
vendorOptionalstringThe carrier-unique code AuditCake generated for the vendor that should service this audit (find it in Settings → Developer → Vendor codes). Only codes for vendors the carrier has registered are accepted; unrecognized codes return 400. Under a vendor-scoped key (Mode 3) this field is ignored — the key already identifies the vendor, so any value here is silently stripped.

On a clean call, the response includes assignedVendor — the carrier's alias for the assigned vendor (Modes 2 and 3), or null when the carrier services its own audits (Mode 1). AuditCake's internal vendor identifier is never on the wire.

Example request

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",
      "estimatedPremium": "12500.00"
    },
    "insured": {
      "legalName": "Pineview Bakery LLC",
      "fein": "55-5550199"
    },
    "location": {
      "address": {
        "line1": "12 Mill Road",
        "city": "Athens",
        "state": "GA",
        "zip": "30601"
      }
    },
    "agency": { "name": "Harbor Insurance Group" },
    "workingContact": {
      "name": "Alex Rivera",
      "email": "alex@example.com",
      "phone": "5550191234",
      "role": "INSURED"
    },
    "recordsContact": {
      "name": "Riverbend Bookkeeping",
      "contact": "Dana Fields",
      "email": "dana@example.com",
      "phone": "5550197788"
    },
    "auditWindow": {
      "periodStart": "2025-01-01",
      "periodEnd": "2026-01-01",
      "dueAt": "2026-03-15"
    },
    "classCodes": [
      { "code": "10220", "estimatedExposure": "500000.00" }
    ]
  }'

recordsContact

Many policies list two parties: the insured contact, and separately whoever keeps the books — an office manager, a bookkeeper, an accountant. For a premium audit the records holder is often the only party who can actually supply the figures, so send that party here when the policy names one. Fields are name (the firm or person on file), contact (the individual), email andphone. All optional; omit the object entirely if the policy names no separate records party.

AuditCake never overwrites the insured contact with it. There are three outcomes, and each is recorded on the audit's timeline so the decision is visible:

  • The insured contact has no email or phone — the records-location value is used, and the audit becomes reachable on that channel.
  • Both are present and differ — the records-location email is kept as an alternate. Messages continue to go to the insured contact's address; the alternate is flagged for review so the auditor can promote it, and is used automatically if the primary address later stops accepting mail.
  • The value can't be used — a malformed address or a placeholder phone number is ignored, with the reason recorded rather than discarded silently. Obvious typos are corrected first, so a domain like example.como is repaired rather than dropped.

Sending the same address in both workingContact andrecordsContact is harmless — it is recognized as one address and stored once.

Multiple locations

When a policy splits class codes across more than one risk location, send a locations array instead of the singular location, and tag each class code to its location with classCodes[].location (matching a locations[].number). Each location is reconciled on its own.

{
    "auditType": "ANNUAL",
    "serviceType": "PHYSICAL",
    "sources": { "carrierControlId": "CTRL-2026-00043" },
    "policy": { "number": "GL-555-0043", "termStart": "2025-01-01", "termEnd": "2026-01-01" },
    "insured": { "legalName": "Pineview Holdings LLC" },
    "locations": [
      { "number": "001", "address": { "line1": "12 Mill Road", "city": "Athens", "state": "GA", "zip": "30601" } },
      { "number": "002", "address": { "line1": "88 Depot Street", "city": "Athens", "state": "GA", "zip": "30605" } }
    ],
    "classCodes": [
      { "code": "91560", "estimatedExposure": "40000.00", "location": "001" },
      { "code": "97050", "estimatedExposure": "20000.00", "location": "001" },
      { "code": "91342", "estimatedExposure": "65000.00", "location": "002" }
    ]
  }

Response

On success the endpoint returns 201 Created with the new audit's identifiers and its readiness:

{
  "ok": true,
  "created": true,
  "auditId": "K7M4PQ",
  "auditCode": "K7M4PQ",
  "carrierId": "<carrier-id>",
  "assignedVendor": null,
  "lifecycleState": "READY",
  "needsData": false,
  "readiness": []
}

A new audit is created in ORDER and immediately gated: a clean, workable audit advances to READY; anything still needing attention stays in ORDER. readiness lists those findings as { code, severity, field, message }, and needsData is true when any finding is BLOCKING — the audit won't start work until it's resolved.

Unknown class codes are accepted, not rejected

If a class code isn't in AuditCake's catalog and no line/basis hint is supplied for it, the audit is still created — in ORDER with a BLOCKING UNRESOLVED_CLASS_CODE finding ("needs data"), never a 400. New codes are common; AuditCake captures them for an auditor to resolve. Supplying line + basis skips the hold (the audit goes straight to READY with a non-blocking UNCATALOGUED_CLASS_CODE warning instead).

{
  "ok": true,
  "created": true,
  "auditCode": "K7M4PQ",
  "lifecycleState": "ORDER",
  "needsData": true,
  "readiness": [
    {
      "code": "UNRESOLVED_CLASS_CODE",
      "severity": "BLOCKING",
      "field": "classLedger.cr_1",
      "message": "Class code 99999 isn't in the catalog — add it to your class plan, or supply line + basis for it."
    }
  ]
}

Idempotency

sources.carrierControlId is the idempotency key. A repeat POST with the same carrierControlId returns the audit AuditCake already created — 200 OK with "created": false — instead of making a duplicate. Safe to retry on a network failure.

Error responses

StatusMeaning
400The payload is invalid. The body's details array lists every problem.
401The x-api-key header is missing or not recognized.
403A carrierId in the body does not match the API key's carrier.
405The request used a method other than POST.
500An unexpected error on AuditCake's side. Safe to retry.

A 400 looks like this:

{
  "error": "Invalid audit payload",
  "details": [
    "`policy.termStart` is required and must be a date (YYYY-MM-DD)",
    "`classCodes[0].code` is required"
  ]
}
Next: Read & list audits →