---
title: "Documents 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/reference/documents"
source: "https://developers.getcount.com/reference/documents"
---
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 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

`id` uuid

Document identifier (UUID). Use in path parameters.

`fileName` string

Original file name.

`folderPath` string

Folder path within the workspace library.

`mimeType` string

MIME type of the uploaded file.

`fileSize` integer

File size in bytes.

`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`

`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",
  "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.

## Related

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

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

## Endpoints

[GET List documents `/partners/documents` Returns a paginated list of documents with optional UUID filters.](https://developers.getcount.com/reference/documents/list-documents) [GET Retrieve document `/partners/documents/{uuid}` Returns a single document by UUID.](https://developers.getcount.com/reference/documents/get-document) [POST Upload document `/partners/documents` Uploads a file via multipart form data.](https://developers.getcount.com/reference/documents/upload-document) [PUT Update document `/partners/documents/{uuid}` Updates document metadata and link fields.](https://developers.getcount.com/reference/documents/update-document) [GET List document types `/partners/document-types` Returns the document types this workspace can use, grouped by type group.](https://developers.getcount.com/reference/documents/list-document-types) [PUT Set document type `/partners/documents/{uuid}/document-type` Sets or clears a document's type.](https://developers.getcount.com/reference/documents/set-document-type) [PUT Set document period `/partners/documents/{uuid}/period` Sets or clears the period a document covers.](https://developers.getcount.com/reference/documents/set-document-period) [DELETE Delete document `/partners/documents/{uuid}` Deletes the document blob and database row.](https://developers.getcount.com/reference/documents/delete-document) [POST Initiate chunked upload `/partners/documents/chunk-upload/initiate` Starts a chunked upload session for a large file.](https://developers.getcount.com/reference/documents/chunk-upload-initiate) [POST Upload chunk `/partners/documents/chunk-upload/chunk` Uploads a single chunk of a multipart upload.](https://developers.getcount.com/reference/documents/chunk-upload-chunk) [POST Complete chunked upload `/partners/documents/chunk-upload/complete` Finalizes a chunked upload and creates the document record.](https://developers.getcount.com/reference/documents/chunk-upload-complete) [GET Get upload progress `/partners/documents/chunk-upload/progress/{uploadProgressId}` Returns progress for an in-flight chunked upload.](https://developers.getcount.com/reference/documents/chunk-upload-progress)