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-06-10

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.

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`. Numeric ID query params are stripped by middleware.

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.

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

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