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

iduuid

Document identifier (UUID). Use in path parameters.

fileNamestring

File name, with its extension. Rename the file with `newFileName` on PUT /partners/documents/{uuid}.

originalFileNamestring

The name the file was uploaded with. It stays the same after a rename. Null on some older files.

isPasswordProtectedboolean

Whether the file is password protected.

isPrivateboolean

Whether the document is private to the accounting firm.

vendorobject

Linked vendor with UUID `id`, or null.

customerobject

Linked customer with UUID `id`, or null.

personobject

Linked person with UUID `id`, or null.

projectobject

Linked project with UUID `id`, or null.

documentTypeobject

The document type, or null when the document has none yet.

iduuid

Document type UUID. Pass it as `documentTypeUuid` or in `documentTypeUuids`.

codestring

Stable code for the type, e.g. `contract`. Codes of COUNT types never change.

namestring

Display name.

documentTypeGroupobject

The group the type is listed under.

iduuid

Document type group UUID.

codestring

Stable group code.

namestring

Display name.

documentTypeSourceenum

Who 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

periodStartDatedate

First day of the period the document covers (YYYY-MM-DD), or null.

periodEndDatedate

Last day of the period the document covers (YYYY-MM-DD), or null.

periodSourceenum

Who set the period, with the same values as `documentTypeSource`. Null when no period has been set.

One of: ai, person

uploadedByobject

The user who uploaded the file: UUID `id`, `firstName` and `lastName`.

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example
{
  "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.

Recent changes

2026-11-18Breaking

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.

2026-10-23

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.

2026-10-08

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.

2026-10-06

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.

2026-06-29

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.

2026-06-05

Webhooks and Documents reference

Added full API reference groups for Webhooks and Documents, including chunked upload and signature verification guidance.

Endpoints