Practice Manager API
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 /firm-partners/workspace/document-types, filter the document list by type, and set a document's name, type and period yourself with PUT /firm-partners/workspace/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 /firm-partners/workspace/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 /firm-partners/workspace/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 /firm-partners/workspace/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 /firm-partners/workspace/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 /firm-partners/workspace/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
Endpoints
/firm-partners/workspace/documentsReturns a paginated list of documents with optional UUID filters.
/firm-partners/workspace/documents/{uuid}Returns a single document by UUID.
/firm-partners/workspace/documentsUploads a file via multipart form data.
/firm-partners/workspace/documents/{uuid}Renames a document, sets its type and period, and links it to a vendor, customer, person or project.
/firm-partners/workspace/document-typesReturns the document types this workspace can use, grouped by type group.
/firm-partners/workspace/documents/{uuid}Deletes the document blob and database row.
/firm-partners/workspace/documents/chunk-upload/initiateStarts a chunked upload session for a large file.
/firm-partners/workspace/documents/chunk-upload/chunkUploads a single chunk of a multipart upload.
/firm-partners/workspace/documents/chunk-upload/completeFinalizes a chunked upload and creates the document record.
/firm-partners/workspace/documents/chunk-upload/progress/{uploadProgressId}Returns progress for an in-flight chunked upload.
/firm-partners/workspace/documents/{uuid}/contentReturns a Documents library file, base64-encoded.
/firm-partners/workspace/documents/{uuid}/download-linksReturns signed links to view and to download a document.
