REFERENCE

Files reference

Upload a PDF, DOCX, DOC, PNG or JPEG and get a file id to build a document from.

All documentation

One endpoint. Upload a file, get an id, then build a document around it with POST /documents.

POST/v1/files

Requires documents:write

This is the one endpoint that is not JSON. Send multipart/form-data with a single file part. There is no separate files scope - it shares documents:write.

bash

curl https://api.documentesign.com/v1/files \
  -H "Authorization: Bearer $ESIGN_API_KEY" \
  -F "file=@contract.pdf"

201 Created

{
  "id": "file_9f2c...",
  "name": "contract.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 48210,
  "created_at": "2026-09-01T10:00:00.000Z"
}

Accepted types

Field	Type	Notes
`application/pdf`	.pdf	Also parsed on upload.
`…wordprocessingml.document`	.docx	Converted to PDF when the document is built.
`application/msword`	.doc	Converted as above.
`image/png`	.png
`image/jpeg`	.jpg

The type is read from the bytes, not the header

Your declared Content-Type and the file extension are both ignored. The file is identified from its actual contents, so renaming something to .pdf will not get it accepted. Anything outside the list above returns 415 unsupported_file_type. WebP, HEIC and SVG are not accepted here.

Errors

Field	Type	Notes
`multipart_required`	415	The request was not multipart/form-data.
`file_missing`	400	No file part was present.
`file_empty`	400	The part had no bytes.
`file_too_large`	413	Over 25 MB.
`unsupported_file_type`	415	Detected type is not in the accepted list.
`password_protected_pdf`	400	Encrypted PDFs are refused. Remove the password before uploading - there is no way to supply one.
`corrupt_pdf`	400	The PDF could not be parsed.

Using the id

Pass file ids to POST /documents in the order you want them merged. A document takes up to ten. An id that does not exist, or belongs to another workspace, returns 400 unknown_file with the offending ids in file_ids.

See send a document from a file for the full path.

PreviousDocuments reference NextTemplates reference