API Reference
Documents
Upload, list, update, and delete files in a workspace document library. Large files use a chunked upload flow. Partner responses omit internal storage paths and download URLs.
Last updated 2026-10-06
Overview
The Documents API lets your integration store files in a workspace document library. Upload a file directly with multipart form data, or use the chunked upload flow for larger files. Every document is identified by a UUID returned as `id`.
Partner JSON responses omit sensitive storage fields including `password`, numeric foreign keys, `azureBlobPath`, and `fileUrl`. Use `fileName`, nested related objects (vendor, customer, person, project), and the document `id` for display. Download URLs are not returned — add a separate controlled flow if partners need file bytes.
Every document can carry a document type (such as Contract or Bank Statement, listed under a type group) and the period it covers. List the types a workspace can use with GET /partners/document-types, filter the document list by type, and set a document's name, type and period yourself with PUT /partners/documents/{uuid}. COUNT also classifies documents with AI; a type or period your integration sets is never overwritten by it.
Key concepts
Multipart upload
POST /partners/documents accepts multipart form data with a `file` field and optional text fields (`folderPath`, `vendorUuid`, `customerUuid`, `personUuid`, `projectUuid`). HMAC signing uses sha256(JSON.stringify({})) for the body hash because multer runs after signature verification.
Chunked upload
For large files, call initiate → upload chunks → complete. Track progress with the progress endpoint using the returned uploadProgressId.
UUID-only list filters
List filters use comma-separated UUID query params: `vendorUuids`, `customerUuids`, `personUuids`, `projectUuids`, `documentTypeUuids`, `documentTypeGroupUuids`. Numeric ID query params are stripped by middleware.
Document types
Types are listed under type groups. A workspace sees COUNT's built-in types for its country plus any custom types it created in COUNT; a built-in type has the same UUID in every workspace. GET /partners/document-types returns the full list. Custom types are created in the COUNT app, not through the Partner API.
AI classification and person-set values
COUNT's classifier may set a document's type and period, marked `ai` in `documentTypeSource` and `periodSource`. A value set through PUT /partners/documents/{uuid} is marked `person`, and the classifier never overwrites it. Clearing a value also counts as a person's choice.
Rate limits
Documents have separate read/write and upload/chunk rate limit tiers per client and workspace. Responses may include X-RateLimit-* and Retry-After headers.
The document object
Fields returned on document records. Related entities expose UUID `id` values only.
Attributes
iduuidDocument identifier (UUID). Use in path parameters.
fileNamestringFile name, with its extension. Rename the file with `newFileName` on PUT /partners/documents/{uuid}.
originalFileNamestringThe name the file was uploaded with. It stays the same after a rename. Null on some older files.
isPasswordProtectedbooleanWhether the file is password protected.
isPrivatebooleanWhether the document is private to the accounting firm.
vendorobjectLinked vendor with UUID `id`, or null.
customerobjectLinked customer with UUID `id`, or null.
personobjectLinked person with UUID `id`, or null.
projectobjectLinked project with UUID `id`, or null.
documentTypeobjectThe document type, or null when the document has none yet.
iduuidDocument type UUID. Pass it as `documentTypeUuid` or in `documentTypeUuids`.
codestringStable code for the type, e.g. `contract`. Codes of COUNT types never change.
namestringDisplay name.
documentTypeGroupobjectThe group the type is listed under.
iduuidDocument type group UUID.
codestringStable group code.
namestringDisplay name.
documentTypeSourceenumWho set the type: `ai` for COUNT's classifier, `person` for a user or a partner integration. Null when no type has been set.
One of: ai, person
periodStartDatedateFirst day of the period the document covers (YYYY-MM-DD), or null.
periodEndDatedateLast day of the period the document covers (YYYY-MM-DD), or null.
periodSourceenumWho set the period, with the same values as `documentTypeSource`. Null when no period has been set.
One of: ai, person
uploadedByobjectThe user who uploaded the file: UUID `id`, `firstName` and `lastName`.
createdAtdatetimeISO 8601 creation timestamp.
updatedAtdatetimeISO 8601 last update timestamp.
{
"id": "d9e0f1a2-b3c4-5678-def0-890123456789",
"fileName": "contract-acme-2026.pdf",
"originalFileName": "contract-acme-2026.pdf",
"isPasswordProtected": false,
"isPrivate": false,
"vendor": null,
"customer": {
"id": "dfa3219e-6af8-4c53-997a-037534f63a35",
"customer": "Acme Corporation"
},
"person": null,
"project": null,
"documentType": {
"id": "b96cbac4-95f8-46cd-b0d7-a9ab92299ce0",
"code": "contract",
"name": "Contract",
"documentTypeGroup": {
"id": "a11040f7-ecda-43ee-917d-21c83ef278c0",
"code": "legal_and_corporate",
"name": "Legal and Corporate"
}
},
"documentTypeSource": "ai",
"periodStartDate": "2026-03-01",
"periodEndDate": "2027-02-28",
"periodSource": "ai",
"uploadedBy": {
"id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d9e",
"firstName": "Jane",
"lastName": "Smith"
},
"createdAt": "2026-03-01T09:00:00.000Z",
"updatedAt": "2026-03-01T09:00:00.000Z"
}Protected paths
Deletion is blocked for documents under Period Close system roots and the Bank Statements/ folder.Signed payroll and tax forms
An update that sets a type or period on a document in the signed-documents folder (signed payroll and tax forms) needs a token for the workspace owner or payroll admin, the same rule as in the COUNT app. Other tokens get 404 Document not found.Password routes not exposed
Document password validate/set endpoints exist on the internal JWT /documents API only — they are not available under /partners/documents.Three ways to send a file
JSON `attachments` entries take a public `url` (COUNT downloads and keeps a copy) or the file inline as `contentBase64` (up to 10 MB). The `/upload` routes take `multipart/form-data`. All three are held to the same per-file cap and file types, at most 10 files a request, and every file is virus-scanned before anything is saved. To read a file back without following a link, call the attachment's `/content` route, which returns it base64-encoded.File links are signed per response
Any `documentUrl`, `receiptUrl`, `pdfUrl` or `bankStatementUrl` on COUNT storage comes back as a short-lived signed link, minted only after COUNT proves the file belongs to this workspace. Use it straight away and call again for a fresh one; do not store it. A file COUNT cannot prove is the workspace's comes back as `null`. A link you attached to an outside file is returned exactly as you sent it.Related
Recent changes
Every attachment in COUNT through the API and MCP
Attachments can now be listed, added, read back and removed through the Partner API on bills, invoices, recurring invoice templates, transaction receipts, manual journal entries, tasks, expense receipts, Documents and reconciliation bank statements. Each record type gains an `attachments` (or `receipts` / `bank-statement`) route that takes JSON entries, either `{ url }` (COUNT downloads and keeps its own copy) or `{ fileName, contentBase64, contentType? }`, plus an `/upload` route for multipart files. Files are capped per route (5 MB for invoices, templates, transaction receipts and Documents, 10 MB for expense receipts, 20 MB for bills, journal entries and tasks, 25 MB for bank statements), at most 10 per request, virus-scanned, and saved together or not at all. A new `/content` route on each returns one file base64-encoded (up to 10 MB), and GET /partners/documents/{uuid}/download-links returns signed view and download links. Breaking: `documentUrl`, `receiptUrl`, `pdfUrl` and `bankStatementUrl` in responses are now short-lived signed links, and `null` when COUNT cannot prove the file is the workspace's. POST /partners/invoices/{uuid}/attachments now stores a copy of each file and answers 201 with `data.attachments` instead of 200 with `data.invoice`. Invoice upload responses no longer include internal ids (`invoiceId`, `defaultInvoiceAttachmentId`, `recurringInvoiceTemplateId`, `uploadedBy`). Bill create and update accept inline content in `attachments`, and an empty list adds nothing. Attachment adds and content reads are limited to 40 a minute per client and workspace. The MCP catalog adds 35 tools, including a Documents category, and content tools deliver the file as an embedded resource rather than as text.
Response examples checked against the live API
Every Practice Manager route was called with a firm API key and the reference corrected where it disagreed. Tasks: the due date field is deadlineDate on create and update (deadline is ignored), firm-only tasks are never returned whatever visibility you pass, and creating a task with type INTERNAL_TASK leaves it unreachable through the API, so the examples now use type custom; the task object lists the fields the API returns. Response examples now match the API for the documents list (documents and pagination) and get (data.document), the projects, tasks, time entries and customers lists, and the trial balance, profit and loss, balance sheet and aged receivables and payables reports. Documents no longer list folderPath, mimeType or fileSize, which were never returned. Firm tasks: a malformed clientWorkspaceUuids filter returns 404, and customId is numbered per client workspace. The Idempotency-Key error applies to writes only.
Rename documents through the update route
PUT /partners/documents/{uuid} documents newFileName, which renames a file within its folder; a name with any of \ / : * ? " < > | $, or longer than 255 characters, is refused with 400. The reference no longer lists folderPath on that route, which the backend never read.
Document types and periods
Documents now carry a document type, listed under a type group, and the period they cover. GET /partners/document-types lists the types a workspace can use: COUNT's built-in types for its country plus its own custom types. Document responses gain documentType (with its documentTypeGroup), documentTypeSource, periodStartDate, periodEndDate and periodSource. The document list filters by documentTypeUuids and documentTypeGroupUuids. PUT /partners/documents/{uuid} sets or clears a document's type (documentTypeUuid) and period (periodStartDate and periodEndDate); a value set this way is marked person and is never overwritten by COUNT's AI classifier.
Budgets API and documentation parity
Added the Budgets API reference (14 endpoints), invoice send-history, and account sub-types list. Introduced an automated parity check (`npm run check:parity`) that compares documented routes against count-dev. Normalized customer path parameters to `{uuid}` and fixed the documents chunk-upload progress path.
Webhooks and Documents reference
Added full API reference groups for Webhooks and Documents, including chunked upload and signature verification guidance.
Endpoints
/partners/documentsReturns a paginated list of documents with optional UUID filters.
/partners/documents/{uuid}Returns a single document by UUID.
/partners/documentsUploads a file via multipart form data.
/partners/documents/{uuid}Renames a document, sets its type and period, and links it to a vendor, customer, person or project.
/partners/document-typesReturns the document types this workspace can use, grouped by type group.
/partners/documents/{uuid}Deletes the document blob and database row.
/partners/documents/chunk-upload/initiateStarts a chunked upload session for a large file.
/partners/documents/chunk-upload/chunkUploads a single chunk of a multipart upload.
/partners/documents/chunk-upload/completeFinalizes a chunked upload and creates the document record.
/partners/documents/chunk-upload/progress/{uploadProgressId}Returns progress for an in-flight chunked upload.
/partners/documents/{uuid}/contentReturns a Documents library file, base64-encoded.
/partners/documents/{uuid}/download-linksReturns signed links to view and to download a document.
