---
title: "File a new document"
method: POST
path: "/api/v1/rest/documents"
tags: ["Documents"]
---

# File a new document

`POST /api/v1/rest/documents`

## Request

- Base URL: `https://api.custodo.ai`
- URL: `https://api.custodo.ai/api/v1/rest/documents`
- Auth: HTTP bearer

Adds a document to the archive and starts processing it (conversion, then type recognition and field extraction, then indexing). Omit `type_id` and the type is recognised from the document itself — that is the normal way to file something you were not told the type of. Returns immediately with a document id and `status: "pending"` — processing takes seconds to minutes, so poll documents_get to see it become `ready`, and read `type` then rather than now. Accepts the file as base64, up to 8 MB decoded; for anything larger POST the raw bytes to `/api/v1/documents` instead, which takes up to 256 MB and needs the same scope. The file type is decided by the BYTES, not by the name you give it.

## Headers

- `X-Tenant-Id` string, uuid

## Request body

- object
  - `filename` string, required: With its extension, e.g. `fattura-123.pdf`.
  - `content_base64` string, required: The file’s bytes, base64-encoded.
  - `title` string: Defaults to the filename.
  - `type_id` string, uuid: A type id from documents_list_types. Omit to have the type recognised automatically from the document; pass one only when the user stated it.
  - `party_ids` string[]: Anagrafiche to associate explicitly; requires anagrafiche:write.
  - `direction` 'in_entrata' | 'in_uscita': Required with a `type_id` whose type needs one (`needs_direction` in documents_list_types): `in_entrata` for a document the company received, `in_uscita` for one it issued. Refused for any other type, and without a `type_id`.

## Response `200`

Done. `data` is the tool’s own answer.

- RestResult
  - `ok` true, required
  - `data` unknown, required

## Other responses

- `400`: The arguments did not validate: `error.message` names the field, what it expects and what arrived.
- `401`: No API key, or one that is malformed, unknown, revoked or expired.
- `403`: The call never ran: the module is off for this organisation, the credential lacks the permission or the module, the tier does not cover it, or the tool is destructive and the key was not minted for that.
- `409`: The record is in a state that does not allow it — under legal hold, already sent, already closed. `error.code` says which.
- `422`: The tool ran and refused, in a sentence of its own (`TOOL_REFUSED`): the message says what to change. Retrying the same call will not help.
- `429`: The API key has spent its minute, or its day. Every request a key makes counts. See `Retry-After`.

---

[API](https://skmtc.dev/custodo/apis/custodo-integrazioni.md) · [All operations](https://skmtc.dev/custodo/apis/custodo-integrazioni/llms.txt) · [OpenAPI document](https://skmtc.dev/custodo/apis/custodo-integrazioni/revisions/16d336d3ec2a?raw)