Skip to content

Documents

Document

The document object is a PDF or DOCX file inside an envelope: its source URL, format, template data, places and fixed positions, plus size and page limits.

A document is a PDF or DOCX file within an envelope. Each envelope can contain between 1 and 10 documents. Recipients sign, approve, or prepare documents during their ceremony.

Documents are defined inside the documents array when creating an envelope. They are not created or updated independently.

A document belongs to an envelope.

Document formats

SignatureAPI supports two document formats. The format property is optional and defaults to pdf, so a PDF document can leave it out. Set format to docx for Word files.

PDF (format: "pdf") accepts standard PDF files. Place fields using placeholders embedded in the document text or fixed coordinates on a page.

DOCX (format: "docx") accepts Microsoft Word files. In addition to places, DOCX documents support template fields that merge dynamic data into the document before signing begins.

If you upload a DOCX file but omit format or set it to "pdf", the API returns a cannot-parse-document error. Always set format: "docx" for Word files.
DOCX files created with Google Docs or LibreOffice may not be compatible. If you get a cannot-parse-document error, open the file in Microsoft Word and re-save it. This resolves most compatibility issues.

Providing a file

Set the url property to an HTTPS URL for the file. SignatureAPI downloads the file when the envelope is created.

The URL must come from a supported host, such as Amazon S3, Google Cloud Storage, Azure Blob Storage or Cloudflare R2. You can also upload the file to SignatureAPI and use the URL it returns.

How to provide the document file

Item Use it whenHow
DOCX template with data The document is generated from your data for each envelope: names, dates or amounts Put {{key}} fields in a DOCX file, set format to docx and send the values in the document's data property. SignatureAPI merges them before signing begins.
Public URL The finished file is at a public URL, for example on Amazon S3, Azure Blob Storage or Cloudflare R2 Set the document's url to the file's URL; SignatureAPI downloads it when the envelope is created. For Amazon S3, pre-signed URLs are recommended.
Upload through the API The file is on your server, for this envelope only Send the bytes to POST /v1/uploads and use the url it returns as the document url. API uploads are deleted 24 hours after creation, and the maximum file size is 4.5 MB.
Permanent upload or the Library You reuse the same file across many envelopes Store the upload through the API, or upload the file to the Library in the Dashboard. Library files never expire and can be reused across envelopes.

Limits

These limits apply to every document, whether it comes from a supported host or an upload:

LimitValueError when exceeded
Documents per envelope1 to 10validation-error
File size10 MBcannot-download-document
Pages per document100too-many-pages
Places per document100too-many-places

A file sent through Create Upload has a lower size limit of 4.5 MB per request.

Places

Places are areas in a document where recipients interact or where information is displayed automatically. Input places include signatures, initials, text inputs, checkboxes, and dropdowns. Informational places include static text, completion dates, and recipient details.

Define places in the places array. Each place has a key and a type.

Place positioning

A place must be positioned in the document. There are two methods.

Placeholders: Embed [[place_key]] in the document text. The place appears at that location. This works for both PDF and DOCX documents.

Fixed positions: Specify the page, top, and left values in the fixed_positions array. Coordinates are measured in points (1 point = 1/72 inch) from the top-left corner of the page.

See Place Positioning for details and examples.

Attributes