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

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 type or period yourself. 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}/document-type or /period 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

Original file name.

folderPathstring

Folder path within the workspace library.

mimeTypestring

MIME type of the uploaded file.

fileSizeinteger

File size in bytes.

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

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example

{
  "id": "d9e0f1a2-b3c4-5678-def0-890123456789",
  "fileName": "contract-acme-2026.pdf",
  "folderPath": "Contracts",
  "mimeType": "application/pdf",
  "fileSize": 245760,
  "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",
  "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

Setting 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.

Recent changes

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}/document-type and PUT /partners/documents/{uuid}/period set or clear a document's type and period; 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.