AuditCakeDevelopersBook a walkthrough

Read & list audits

Pull the audits AuditCake holds for the calling key's scope — a single audit by id, or a paginated list — to see their current status and the data on file. A vendor-scoped key returns only audits assigned to that vendor, on that key's carrier.

List audits

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

Returns the audits the calling key has access to, newest first. The response is paginated with a cursor — read a page, then pass the returned nextCursor back to fetch the next one.

Query parameters

ParamTypeDescription
limitintegerPage size, 1–500. Defaults to 50.
cursorstringThe nextCursor from a previous page. Omit for the first page.
statusenumOptional. Return only audits in this lifecycle state, e.g. CONTACTING, SUBMITTED, CANCELLED, REJECTED.
curl "https://auditcake.com/api/v1/audits?limit=50" \
  -H "x-api-key: ack_live_<carrier-api-key>"

The response:

{
  "audits": [
    {
      "auditCode": "K7M4PQ",
      "status": "CONTACTING",
      "auditType": "ANNUAL",
      "serviceType": "PHYSICAL",
      "sources": { "carrierControlId": "CTRL-2026-00042", "orderNumber": "ORD-7781" },
      "insured": { "legalName": "Pineview Bakery LLC", "dbaName": null, "fein": "55-5550199" },
      "auditWindow": { "periodStart": "2025-01-01", "periodEnd": "2026-01-01", "dueAt": "2026-03-15" },
      "createdAt": "2026-02-02"
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJ0IjoxNz...="
}

List rows are a slim summary — they omit the policy join and the heavy working detail (the worksheets, salesBreakdown, and the full events timeline). Fetch a single audit (below) for the complete record.

Get one audit

GEThttps://auditcake.com/api/v1/audits/:id

:id can be either the auditCode AuditCake returned at create time, or the caller's own carrierControlId — whichever is on hand.

# by AuditCake's audit code
curl https://auditcake.com/api/v1/audits/K7M4PQ \
  -H "x-api-key: ack_live_<carrier-api-key>"

# or by the caller's own control id
curl https://auditcake.com/api/v1/audits/CTRL-2026-00042 \
  -H "x-api-key: ack_live_<carrier-api-key>"

The response mirrors the fields submitted at create time, plus AuditCake's assigned auditCode, the lifecycle status, and the computed audit window:

{
  "auditCode": "K7M4PQ",
  "status": "IN_REVIEW",
  "outcome": null,
  "auditType": "ANNUAL",
  "serviceType": "PHYSICAL",
  "sources": { "carrierControlId": "CTRL-2026-00042", "orderNumber": "ORD-7781" },
  "policy": {
    "number": "GL-555-0042",
    "termStart": "2025-01-01",
    "termEnd": "2026-01-01",
    "estimatedPremium": "12500.00",
    "lines": ["GL"]
  },
  "insured": { "legalName": "Pineview Bakery LLC", "dbaName": null, "fein": "55-5550199", "descriptionOfOperations": "Bowling alley with a bar" },
  "location": { "address": { "line1": "12 Mill Road", "city": "Athens", "state": "GA", "zip": "30601" } },
  "agency": {
    "name": "Harbor Insurance Group", "agencyCode": "HIG-0042", "role": "RETAIL",
    "contact": { "name": "Jordan Castellano", "email": "jordan@example.com", "phone": "+12485550162" },
    "alsoKnown": [{ "name": "Dana Fields", "email": "dana@example.com", "phone": null, "agencyName": "Fields Wholesale", "role": "WHOLESALE", "source": "PRIOR_AGENT", "suggested": true, "confidence": 0.7 }]
  },
  "workingContact": { "name": "Alex Rivera", "email": "alex@example.com", "phone": "+12485550147", "role": "INSURED" },
  "classCodes": [{
    "code": "10220", "description": "Bowling Lanes", "line": "GL", "basis": "GROSS_SALES", "location": null,
    "estimatedExposure": "500000.00",   // what the carrier submitted
    "declaredExposure": "541200.00",     // what the insured reported
    "auditedExposure": "538900.00",      // the verified/final figure (null until reviewed)
    "verificationStatus": "CONFIRMED"
  }],
  "worksheets": [{
    "location": null,
    "worksheet": {
      "columns": [{ "id": "col_wage", "label": "Wages", "kind": "WAGE" }, { "id": "col_ot", "label": "Overtime", "kind": "OVERTIME" }],
      "rows": [{ "person": { "name": "Marcus Bell", "title": "Lead Plumber", "typeOfWork": "Field", "isOfficer": false, "ownerPercent": null }, "values": { "col_wage": "95804.00", "col_ot": "8331.00" }, "employeeCount": 1, "isBalancingRow": false, "classRowId": "cr_1" }],
      "notes": null
    },
    "subcontractors": [{ "name": "Cypress Mechanical Co.", "hasCOI": "Yes", "labor": "41237.00", "material": "18804.00" }],
    "findings": []
  }],
  "salesBreakdown": null,
  "events": [
    { "id": "ev_17", "at": "2026-03-14T21:50:09.037Z", "kind": "STATE_CHANGED", "actor": "AuditCake", "actorRole": null, "title": "Final review complete", "summary": null, "metadata": { "from": "IN_REVIEW", "to": "FINAL_REVIEW_COMPLETE" } },
    { "id": "ev_04", "at": "2026-02-10T15:02:00.000Z", "kind": "EMAIL_SENT", "actor": "AuditCake", "title": "First outreach", "metadata": { "to": "alex@example.com", "subject": "...", "body": "...", "status": "delivered" } }
  ],
  "insuredComment": null,
  "auditWindow": { "periodStart": "2025-01-01", "periodEnd": "2026-01-01", "orderedAt": "2026-02-02", "startedAt": "2026-02-02", "dueAt": "2026-03-15", "stopContactAt": "2026-02-28" },
  "createdAt": "2026-02-02"
}

Audited results, worksheet & timeline

The single-audit response includes the audit's working detail — the same data the AuditCake app shows — populated as the audit progresses. Everything is null / empty until the audit reaches that stage; read status to know where it is (these fields are not gated to a completed audit).

FieldWhat it is
classCodes[].estimatedExposureThe figure the carrier submitted at create.
classCodes[].declaredExposureThe figure the insured reported (before final review).
classCodes[].auditedExposureThe verified / final figure. null until reviewed; verificationStatus says which stage the row is at.
worksheets[]The reconciliation detail per location: for payroll, a columns plan (Wages/Overtime) + one rows entry per worker (name, type of work, owner %, officer flag, per-column dollars) + subcontractors. Dollar strings.
salesBreakdownFor sales audits: the insured's categories (Food / Alcohol / per-class-code buckets, each with reported sales) and totals. null for payroll audits.
events[]The full activity timeline — one entry per email/text/call, portal view, edit, state change, review, and note, each with at, kind, actor, and a metadata envelope (message bodies, edit diffs, review findings, …).
agency.role / agency.alsoKnown[]The retail/wholesale rung, and the other producers known at the agency (unconfirmed enrichment hints — carry suggested / confidence).
insuredCommentThe insured's free-text "anything else" note, when provided.

Audit status

status tracks the audit through its lifecycle. It begins at ORDER and moves through contact and worksheet stages to SUBMITTED, review, and finally SENT_TO_CARRIER / INVOICED. A withdrawn audit shows CANCELLED; one the carrier or auditor rejects — for example a class code on a coverage line this carrier doesn't audit — shows REJECTED (also terminal). An audit deferred until the policy expires shows SNOOZED. When an audit closes out, outcome is PRODUCTIVE or NONPRODUCTIVE.

Error responses

StatusMeaning
401The x-api-key header is missing or not recognized.
404No audit with that id falls within the calling key's scope.
500An unexpected error on AuditCake's side. Safe to retry.
Next: Update an audit →