Documents

1 endpoint, each with examples that open in the console prefilled.

POST/api/v1/documentscontacts:writeTry in console

Upload a document for a contact

Upload one private PDF for one contact, then send it with document: { id } on a template with a DOCUMENT header.

Body parameters

filerequired	file
contact_idrequired	string
kind	string

Send multipart/form-data, not JSON: the PDF as the file part, the contact's id as contact_id, and optionally kind (a label such as invoice; statement when left out). The file's name is the filename the recipient sees.
PDF only, up to 4 MB (a request body is capped at 4.5 MB). The bytes decide what the file is, whatever its Content-Type says: a file without a PDF header and an end-of-file marker is refused with details.reason: "not_a_pdf", a larger one with file_too_large. Nothing is stored when it is refused.
The file is private: it has no URL. Send it with POST /api/v1/messages and document: { id }; it is fetched with a link that lasts an hour, at send time only. It counts toward your plan's storage, and it is kept for 90 days, like the dashboard's uploads: after that it is deleted, and a send by its id answers 404 not_found, document_not_found. Upload it again to send it later.
A document is only ever sent to the contact it was uploaded for. A contact this workspace does not hold answers 404 not_found; one outside a business-restricted key's businesses answers 403 forbidden.

curl -X POST "https://app.blueticked.com/api/v1/documents" \
  -H "Authorization: Bearer $BLUETICKED_API_KEY" \
  -F "file=@statement.pdf;type=application/pdf" \
  -F "contact_id=ff506e53-e2f0-4d92-884a-dab77d628bad" \
  -F "kind=statement"

Response

{
  "document": {
    "id": "50f954af-1cbb-4d02-b68f-bb80e7874c03",
    "contact_id": "ff506e53-e2f0-4d92-884a-dab77d628bad",
    "kind": "statement",
    "filename": "Statement September 2026.pdf",
    "size_bytes": 48213,
    "created_at": "2026-10-15T08:00:00.000Z"
  },
  "request_id": "req_b2e3d610e10f1b07468721ee98f0e1d2"
}