---
title: "Upload a document for a contact"
method: POST
path: "/api/v1/documents"
tags: ["contacts"]
---

# Upload a document for a contact

`POST /api/v1/documents`

## Request

- Base URL: `https://app.blueticked.com`
- URL: `https://app.blueticked.com/api/v1/documents`
- Auth: HTTP bearer

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

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.

## Response `201`

Success

- object
  - `document` object, required
    - `id` string, uuid, required
    - `contact_id` string, uuid, required
    - `kind` string, required
    - `filename` string, required
    - `size_bytes` number, required
    - `created_at` string, date-time, required
  - `request_id` string, required

## Other responses

- `400`: Validation failed
- `401`: Unauthorized: missing or invalid API key
- `402`: Insufficient wallet balance
- `403`: Forbidden: scope, plan limit, or suspension
- `404`: Not found
- `409`: Conflict (idempotency-key reuse or resource in use)
- `413`: Request body above the endpoint's size limit
- `422`: Understood but refused: the request is well-formed, the action is not permitted for this resource
- `429`: Rate limited
- `500`: Internal error
- `502`: An upstream provider refused or failed the request
- `503`: Channel or send queue unavailable

---

[API](https://skmtc.dev/blueticked/apis/blueticked-api.md) · [All operations](https://skmtc.dev/blueticked/apis/blueticked-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blueticked/apis/blueticked-api/revisions/07132284f4ff?raw)