AuditCakeDevelopersBook a walkthrough

Add & read documents

Attach supporting documents to an audit — payroll registers, tax forms, P&L statements — and read back the documents on file. Documents belong to an audit, so every route lives under it.

Adding a document is three steps

A document upload is a three-step flow so the file bytes go straight to storage and never through the API: (1) register the document and get a short-lived upload URL, (2) upload the bytes to that URL, then (3) finalize to confirm the upload and attach it to the audit. :id is the auditCode AuditCake returned, or the caller's own carrierControlId.

Step 1 — register the document

POSThttps://auditcake.com/api/v1/audits/:id/documents
FieldTypeDescription
fileNamestringRequired. The file's name, e.g. payroll-2025.pdf.
kindenumOne of PAYROLL_REGISTER, TAX_941, TAX_RETURN, PL_STATEMENT, BREAKDOWN, GENERAL_LEDGER, CERT_OF_INSURANCE, OTHER. An unrecognized value is stored as OTHER.
sizeBytesintegerOptional. The byte size; the true size is re-read from storage on finalize.
contentTypestringOptional. The MIME type, e.g. application/pdf.
curl -X POST https://auditcake.com/api/v1/audits/K7M4PQ/documents \
  -H "x-api-key: ack_live_<carrier-api-key>" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "PAYROLL_REGISTER", "fileName": "payroll-2025.pdf", "contentType": "application/pdf" }'

The response carries the upload URL and the document id:

{
  "documentId": "doc_K7M4PQ_9f2a1c",
  "uploadUrl": "https://storage.googleapis.com/...&X-Goog-Signature=...",
  "storagePath": "documentsV2/K7M4PQ/doc_K7M4PQ_9f2a1c.pdf",
  "kind": "PAYROLL_REGISTER"
}

Step 2 — upload the bytes

PUT the file to the uploadUrl. It is a signed URL valid for 15 minutes; send the same Content-Type that was declared in Step 1. No API key is needed on this request — the URL is the credential.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @payroll-2025.pdf
Accepted formats: PDF, Excel (.xlsx/.xlsm/.xls/.ods), CSV, Word (.docx), a .zip of any of those, and images (.jpg/.png/.heic) — the same set the AuditCake UI accepts. Non-PDF uploads are converted to PDF during processing (see below); a Word file keeps its text, tables and pictures but not its page layout, and a zip becomes one document with a page or more per file inside. Any other format — including the older.doc — is rejected at Step 1 with a415; convert it to PDF and register again.

Step 3 — finalize

POSThttps://auditcake.com/api/v1/audits/:id/documents/:documentId/finalize

Confirms the bytes landed and attaches the document to the audit. Returns the document — see the shape below. Calling finalize before the bytes are uploaded returns 409. The freshly-finalized document comes back with redactionStatus: "PENDING" and a null downloadUrl — it is not yet readable. See Documents are de-identified below.

curl -X POST \
  https://auditcake.com/api/v1/audits/K7M4PQ/documents/doc_K7M4PQ_9f2a1c/finalize \
  -H "x-api-key: ack_live_<carrier-api-key>"

Documents are de-identified before you can read them

Every uploaded document is automatically de-identified before its bytes are servable. Until that finishes, the document carries redactionStatus: "PENDING" and its downloadUrl is null; once it completes the status flips to "REDACTED" and a signed downloadUrl appears. There is no webhook — after finalize, poll GET .../documents/:documentId until redactionStatus is "REDACTED", then fetch the bytes. Redaction usually completes within seconds.

redactionStatusMeaning
PENDINGDe-identification in progress. downloadUrl is null — not yet readable.
REDACTEDDe-identification complete. downloadUrl is present and the bytes are servable.

The bytes you download are the de-identified copy: high-sensitivity personal identifiers — Social Security numbers, dates of birth, bank-routing & card numbers, and contact details (email, phone, street address) — are blacked out. Employee names and payroll/wage figures are intentionally preserved, so the document still supports the audit. The original, un-redacted file is never served through the API.

Two consequences of de-identification worth noting:

  • The de-identified document is always a PDF. Whatever you upload (CSV, Excel, an image) is rendered to an image-only PDF, so on read the fileName comes back with a .pdf extension and contentType is application/pdf — e.g. an uploaded payroll-2025.csv reads back as payroll-2025.pdf.
  • Large or high-resolution files are compressed. Pages are downsampled and re-compressed during de-identification, so the returned PDF may be smaller and lower-resolution than the original. Text remains legible; the document stays usable for the audit.

List an audit's documents

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

Returns the finalized documents on the audit. A REDACTED document carries a download URL; one still PENDING redaction has downloadUrl: null.

The list contains two kinds of entry, both de-identified:

  • The individual files you (or the insured) provided — each with stapled: false.
  • A stapled merge package per document type — one combined PDF assembling all the redacted files of that kind (e.g. every payroll file merged into one), marked stapled: true with a stapledFrom array of the source documentIds it merges. It is built only from the already-redacted files, so it is de-identified too. Use it when you want one file for the whole category instead of fetching each source separately.
curl https://auditcake.com/api/v1/audits/K7M4PQ/documents \
  -H "x-api-key: ack_live_<carrier-api-key>"
{
  "documents": [
    {
      "documentId": "doc_K7M4PQ_9f2a1c",
      "auditCode": "K7M4PQ",
      "kind": "PAYROLL_REGISTER",
      "fileName": "payroll-2025.pdf",
      "sizeBytes": 68213,
      "contentType": "application/pdf",
      "uploadedAt": "2026-02-04",
      "enrichmentStatus": "UPLOADED",
      "redactionStatus": "REDACTED",
      "stapled": false,
      "stapledFrom": null,
      "downloadUrl": "https://storage.googleapis.com/...&X-Goog-Signature=..."
    },
    {
      "documentId": "doc_K7M4PQ_stapled_payroll",
      "auditCode": "K7M4PQ",
      "kind": "PAYROLL_REGISTER",
      "fileName": "payroll-package.pdf",
      "sizeBytes": 71044,
      "contentType": "application/pdf",
      "uploadedAt": "2026-02-04",
      "enrichmentStatus": null,
      "redactionStatus": "REDACTED",
      "stapled": true,
      "stapledFrom": ["doc_K7M4PQ_9f2a1c"],
      "downloadUrl": "https://storage.googleapis.com/...&X-Goog-Signature=..."
    }
  ]
}

Get one document

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

Returns the single document. Once redactionStatus is "REDACTED" it carries a freshly-signed downloadUrl (valid for one hour) for fetching the file bytes; while still "PENDING" the downloadUrl is null. This is the endpoint to poll after finalize.

Error responses

StatusMeaning
401The x-api-key header is missing or not recognized.
404The audit, or the document, doesn't fall within the calling key's scope.
409Finalize was called before the file bytes were uploaded.
415The fileName is an unsupported type (not PDF / Excel / CSV / Word / zip / image). Convert to PDF and register again.
500An unexpected error on AuditCake's side. Safe to retry.
Back to getting started →