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
| Field | Type | Description |
|---|---|---|
fileName | string | Required. The file's name, e.g. payroll-2025.pdf. |
kind | enum | One of PAYROLL_REGISTER, TAX_941, TAX_RETURN, PL_STATEMENT, BREAKDOWN, GENERAL_LEDGER, CERT_OF_INSURANCE, OTHER. An unrecognized value is stored as OTHER. |
sizeBytes | integer | Optional. The byte size; the true size is re-read from storage on finalize. |
contentType | string | Optional. 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.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
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.
| redactionStatus | Meaning |
|---|---|
PENDING | De-identification in progress. downloadUrl is null — not yet readable. |
REDACTED | De-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
fileNamecomes back with a.pdfextension andcontentTypeisapplication/pdf— e.g. an uploadedpayroll-2025.csvreads back aspayroll-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
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), markedstapled: truewith astapledFromarray of the sourcedocumentIds 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
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
| Status | Meaning |
|---|---|
401 | The x-api-key header is missing or not recognized. |
404 | The audit, or the document, doesn't fall within the calling key's scope. |
409 | Finalize was called before the file bytes were uploaded. |
415 | The fileName is an unsupported type (not PDF / Excel / CSV / Word / zip / image). Convert to PDF and register again. |
500 | An unexpected error on AuditCake's side. Safe to retry. |