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

iduuid

Document identifier (UUID). Use in path parameters.

fileNamestring

File name, with its extension. Rename the file with `newFileName` on PUT /firm-partners/workspace/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 /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.

Endpoints