Document Upload
Uploads one or more documents to Storage so they can be used in the signature flow. The request must be multipart/form-data; there is no raw-body or JSON alternative. Accepted extensions are .docx and .pdf, validated by filename extension — any other extension fails the request with INVALID_TEMPLATE_FORMAT, an error code this operation shares with documents-template-upload. Maximum file size is 20 MB in Production and 10 MB in Staging. A file over that limit is rejected by the web server before the operation runs, so it surfaces as a 500 rather than a validation error.
Each uploaded file is assigned a storage id, returned in form-data order when several files are sent in one request. That id is used when creating an envelope or a signature template, and nowhere else — a document uploaded here is not a document-generation template, which is what documents-template-upload provides.
An uploaded document is held in Storage for 24 hours. Creating an envelope from it within that window stores its content with the envelope, so the envelope keeps working after the Storage copy expires. A document not used within 24 hours is deleted and its id stops resolving; upload it again if you still need it.
A .docx document is converted to PDF when an envelope is created from it, because signing operates on PDF only. The converted PDF is the document recipients see and sign.
JWT token to authenticate the request.
In: header
API key, sent as a request header.
In: header
Request Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/signatures/document/upload" \ -F file="[ \"Master Services Agreement.docx\" ]"{ "result": { "data": { "files": [ { "id": "b6a5f346-6b60-4c1a-9d55-782651280abc", "fileName": "Sales Agreement DOCX.docx" } ] }, "statusCode": 201, "message": "Created" }, "origin": "POST https://api.doctavian.com/v1/signatures/document/upload", "dateTime": "2025-11-05T11:02:07.000Z", "operationId": "6734a3935704307c5df77ed503cb6fd4", "userId": "1d62de57-15a0-4692-ac2e-8afa960e4f81"}{ "error": { "statusCode": 400, "message": "The file 'terms.txt' has an unsupported format. Allowed: .docx,.pdf", "innerErrors": [ { "code": "INVALID_TEMPLATE_FORMAT", "message": "The file 'terms.txt' has an unsupported format. Allowed: .docx,.pdf", "userMessage": "This document format isn't supported. Upload a .docx or .pdf file." } ] }, "origin": "POST https://api.doctavian.com/v1/signatures/document/upload", "dateTime": "2025-10-31T08:19:03.000Z", "operationId": "f53ef09d526419b9eabd0068b2bdbd66", "userId": "49e294f8-981b-48c1-9d75-baa870f77cbe"}{ "error": { "statusCode": 401, "message": "The request could not be authenticated.", "innerErrors": [ { "code": "UNAUTHORIZED", "message": "The request could not be authenticated.", "userMessage": "Your session has expired or is invalid. Please sign in again." } ] }, "origin": "POST https://api.doctavian.com/v1/signatures/document/upload", "dateTime": "2026-07-14T09:32:15.000Z", "operationId": "3a4b5c6d7e8f90112233445566778899", "userId": "ae633ada-1e5d-44b4-9f9a-5ec5ce51724a"}{ "error": { "statusCode": 500, "message": "Failed to persist the uploaded file to storage.", "innerErrors": [ { "code": "FILE_UPLOAD_FAILED", "message": "Failed to persist the uploaded file to storage.", "userMessage": "Something went wrong while uploading. Please try again or contact support." } ] }, "origin": "POST https://api.doctavian.com/v1/signatures/document/upload", "dateTime": "2026-07-14T09:32:15.000Z", "operationId": "3a4b5c6d7e8f90112233445566778899", "userId": "49cdbf2b-1b96-4f8c-badd-9c4beb3918a2"}