---
title: "Documents · Practice Manager API · COUNT Partner API"
description: "Upload, list, update, and delete files in a workspace document library. Large files use a chunked upload flow. Partner responses omit internal storage paths…"
canonical: "https://developers.getcount.com/practice-manager/reference/documents"
source: "https://developers.getcount.com/practice-manager/reference/documents"
---
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

`id` uuid

Document identifier (UUID). Use in path parameters.

`fileName` string

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

`originalFileName` string

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

`isPasswordProtected` boolean

Whether the file is password protected.

`isPrivate` boolean

Whether the document is private to the accounting firm.

`vendor` object

Linked vendor with UUID `id`, or null.

`customer` object

Linked customer with UUID `id`, or null.

`person` object

Linked person with UUID `id`, or null.

`project` object

Linked project with UUID `id`, or null.

`documentType` object

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

`id` uuid

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

`code` string

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

`name` string

Display name.

`documentTypeGroup` object

The group the type is listed under.

`id` uuid

Document type group UUID.

`code` string

Stable group code.

`name` string

Display name.

`documentTypeSource` enum

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`

`periodStartDate` date

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

`periodEndDate` date

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

`periodSource` enum

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

One of: `ai`, `person`

`uploadedBy` object

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

`createdAt` datetime

ISO 8601 creation timestamp.

`updatedAt` datetime

ISO 8601 last update timestamp.

Example

```json
{
  "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

- [Customers API](https://developers.getcount.com/practice-manager/reference/customers)
- [Projects API](https://developers.getcount.com/practice-manager/reference/projects)

## Endpoints

[GET List documents `/firm-partners/workspace/documents` Returns a paginated list of documents with optional UUID filters.](https://developers.getcount.com/practice-manager/reference/documents/list-documents) [GET Retrieve document `/firm-partners/workspace/documents/{uuid}` Returns a single document by UUID.](https://developers.getcount.com/practice-manager/reference/documents/get-document) [POST Upload document `/firm-partners/workspace/documents` Uploads a file via multipart form data.](https://developers.getcount.com/practice-manager/reference/documents/upload-document) [PUT Update document `/firm-partners/workspace/documents/{uuid}` Renames a document, sets its type and period, and links it to a vendor, customer, person or project.](https://developers.getcount.com/practice-manager/reference/documents/update-document) [GET List document types `/firm-partners/workspace/document-types` Returns the document types this workspace can use, grouped by type group.](https://developers.getcount.com/practice-manager/reference/documents/list-document-types) [DELETE Delete document `/firm-partners/workspace/documents/{uuid}` Deletes the document blob and database row.](https://developers.getcount.com/practice-manager/reference/documents/delete-document) [POST Initiate chunked upload `/firm-partners/workspace/documents/chunk-upload/initiate` Starts a chunked upload session for a large file.](https://developers.getcount.com/practice-manager/reference/documents/chunk-upload-initiate) [POST Upload chunk `/firm-partners/workspace/documents/chunk-upload/chunk` Uploads a single chunk of a multipart upload.](https://developers.getcount.com/practice-manager/reference/documents/chunk-upload-chunk) [POST Complete chunked upload `/firm-partners/workspace/documents/chunk-upload/complete` Finalizes a chunked upload and creates the document record.](https://developers.getcount.com/practice-manager/reference/documents/chunk-upload-complete) [GET Get upload progress `/firm-partners/workspace/documents/chunk-upload/progress/{uploadProgressId}` Returns progress for an in-flight chunked upload.](https://developers.getcount.com/practice-manager/reference/documents/chunk-upload-progress) [GET Get document content `/firm-partners/workspace/documents/{uuid}/content` Returns a Documents library file, base64-encoded.](https://developers.getcount.com/practice-manager/reference/documents/get-document-content) [GET Get document download links `/firm-partners/workspace/documents/{uuid}/download-links` Returns signed links to view and to download a document.](https://developers.getcount.com/practice-manager/reference/documents/get-document-download-links)
