Create an audit
Submit an audit to AuditCake. It is created as production work and enters the audit lifecycle immediately.
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
| Field | Required | Type | Description |
|---|---|---|---|
auditType | Required | enum | One of ANNUAL, CANCELLATION, INTERIM, MULTI_YEAR, NEW_ACCOUNT, PRE_AUDIT, REOPEN_CLOSEOUT, REOPEN_DISPUTE, RUSH. |
serviceType | Required | enum | How the audit is conducted: PHYSICAL, PHONE, VIRTUAL, VOLUNTARY, or SURVEY. |
sources | Required | object | Identifiers for this audit, set by the caller. See below. |
policy | Required | object | The policy being audited. See below. |
insured | Required | object | The audited business. See below. |
auditWindow | Optional | object | The audit period and key dates. Every field is optional and computed when omitted — see below. |
location | Optional | object | The insured's location and address. Use this for a single-location audit. For a multi-location policy, send locations instead. |
locations | Optional | array | The 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. |
agency | Optional | object | The agency of record — name, optional agencyCode, and an optional agent contact. See below. |
workingContact | Optional | object | Who 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. |
recordsContact | Optional | object | The party that holds the records, when it differs from the insured contact — name, contact, email, phone. See below. |
classCodes | Optional | array | The 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
| Field | Required | Type | Description |
|---|---|---|---|
carrierControlId | Required | string | A stable, unique id for this audit. Used as the idempotency key — see below. |
orderNumber | Optional | string | The order number, if any. |
referenceNumber | Optional | string | Any additional reference to carry on the audit. |
accountNumber | Optional | string | A stable account number for the insured. Helps AuditCake link audits across years. |
agency
| Field | Required | Type | Description |
|---|---|---|---|
name | Optional | string | The agency of record's name. |
agencyCode | Optional | string | The carrier's producer code for the agency, if any. |
contact | Optional | object | The 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
| Field | Required | Type | Description |
|---|---|---|---|
number | Required | string | The policy number. |
termStart | Required | date | Policy term start, YYYY-MM-DD. |
termEnd | Required | date | Policy term end, YYYY-MM-DD. |
estimatedPremium | Optional | amount | The 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
| Field | Required | Type | Description |
|---|---|---|---|
insured.legalName | Required | string | The insured's legal business name. |
insured.dbaName | Optional | string | Doing-business-as name. |
insured.fein | Optional | string | Federal Employer Identification Number. |
location.address | Optional | object | line1, line2, city, state, zip. Single-location audits only — omit when sending locations. |
locations[].number | Required* | string | Your 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[].address | Optional | object | The location's address — line1, line2, city, state, zip. |
locations[].nickname | Optional | string | A human label for the location, e.g. "Main warehouse". |
classCodes[].code | Required | string | The 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[].location | Optional | string | The 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[].estimatedExposure | Optional | amount | Estimated exposure for the row, e.g. "500000.00". |
classCodes[].line | Optional | enum | Coverage line — only needed for a code AuditCake's catalog doesn't carry. One of GL, LL, WC, AUTO, PROPERTY. |
classCodes[].basis | Optional | enum | Exposure 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.
| Field | Required | Type | Description |
|---|---|---|---|
periodStart | Optional | date | Start of the period under audit. Defaults to the policy term start. |
periodEnd | Optional | date | End of the period under audit. Defaults to the policy term end. |
orderedAt | Optional | date | When the audit was ordered. Defaults to the time of the request. |
startedAt | Optional | date | When 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. |
dueAt | Optional | date | When the audit is due. Defaults to orderedAt plus the carrier's standard audit duration. |
stopContactAt | Optional | date | When 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
assignmentblock, the carrier services the audit itself (Mode 1). - With a carrier key and
assignment.vendorset, 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
assignmentblock is ignored — the key already identifies which carrier the audit belongs to and which vendor is servicing it (Mode 3).
| Field | Required | Type | Description |
|---|---|---|---|
vendor | Optional | string | The 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.comois 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
| Status | Meaning |
|---|---|
400 | The payload is invalid. The body's details array lists every problem. |
401 | The x-api-key header is missing or not recognized. |
403 | A carrierId in the body does not match the API key's carrier. |
405 | The request used a method other than POST. |
500 | An 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"
]
}