File a new document, as raw bytes
The large-file counterpart of documents_upload. Same result, same pipeline, same documents:write scope — but the body is the file rather than base64 in JSON, so it takes up to 256 MB instead of 8 MB. Prefer the tool for small files and anything an assistant calls; prefer this for a bulk import or a scan.
Omit documentTypeId and pass autoType=true to have the type recognised from the document itself.
Pass versionSameName=true to file a file whose name is already in the archive as that document’s next version: the answer is then that document, still 201, with versioned: true. Pass suffixSameName=true to keep both instead: the file becomes a new document named with the first free _2, _3… (201, renamed: true).
Request
- Base URL: https://api.custodo.ai
- URL: https://api.custodo.ai/api/v1/documents
- Auth: HTTP bearer
Query parameters
With its extension. The file type is decided by the BYTES, not by this.
A hint only, for a client that can only send application/octet-stream.
A type id from documents_list_types. Omit to type automatically.
Recognise the type from the document. Mutually exclusive with documentTypeId — sending both is a 400, not a precedence rule.
Defaults to filename.
Only for a type that requires one; sending it otherwise is a 400.
Anagrafiche to link the new document to, comma-separated (at most 20). Needs anagrafiche:write on top of documents:write.
For an import: the folders the file sat in, relative to the folder being imported and without the file name (Archivio/Fornitori/Rossi Srl). It is handed to type recognition as a hint, and the conversion is queued behind uploads made one file at a time. A .. segment, more than 32 levels or more than 1,024 characters is a 400.
When a document whose current file has exactly these bytes is already in the archive, answer with it (200, duplicate: true) instead of filing a second copy — so a re-run of an interrupted import files nothing twice.
When a document whose current file has this exact filename — and the same originPath, or none on both — is already in the archive, file the bytes as its next version (201, versioned: true) instead of as a second document. The document keeps its id, type, title and direction; the chosen partyIds are linked to it. A document you may only read, an attachment kept out of the archive, or a filed mail message is never versioned: a new document is filed instead. Checked after skipDuplicates. Not combinable with Idempotency-Key (a 400).
When the upload is about to file a NEW document under a filename that a document you can see already has — in the same originPath, or with none on both — file it under the first free name of the series <name>_2.<ext>, <name>_3.<ext>… instead (201, renamed: true; the current version carries the new name, and so does the title unless you pass title). The number goes before the extension, and before the inner one of a signed .p7m. With versionSameName=true too, a file that can become a version still does; this applies only when it cannot. Combinable with Idempotency-Key.
Headers
The organisation to act in. An API key is bound to exactly one, so this is optional for a key and must match the one it was minted for.
A key of your own, scoped to your credential. Repeating a request with the same key and the same bytes returns the document the first attempt filed, with 200 instead of 201, rather than filing a second copy — which is what you want on a retry after a timeout. The same key with DIFFERENT bytes is a 409.
Response
Nothing was filed by this request: an Idempotency-Key replay (this exact file was already filed under that key), or — with skipDuplicates=true — the document whose current file already has these exact bytes, returned with duplicate: true.
Changes
No recorded changes to this operation across all 1 revision of this API.