Envelope Documents

Documents are the PDF files attached to an envelope. An envelope can contain one or more documents, each with its own set of fields placed on its pages.

---

Properties

Property	Type	Description
id	string	Unique identifier for the document. Required when placing fields.
name	string	Display name shown to recipients during signing.
order	number	Display order when multiple documents are present. Zero-based.
pages	array	One entry per PDF page. The array length gives the total page count.
context	object	Arbitrary metadata attached to this document.
status	string	Completion status of this document. See below.

Document status

Status	Description
completed	All required fields on this document have been submitted.
declined	A recipient declined to sign this document.
voided	The parent envelope was voided.

---

Uploading documents

Documents are uploaded individually via a multipart/form-data request after the envelope is created.

POST /api/v1/key/envelopes/{envelopeId}/documents
Content-Type: multipart/form-data

Field	Type	Required	Constraints
document	file	✅	PDF only. Maximum size: 48 MB.
name	string	—	Max 140 characters. Defaults to the uploaded filename.
order	number	—	Display position. Starts at 0.
context	object	—	Arbitrary metadata.

info

Each upload is a separate request. To add three documents to an envelope, make three POST requests to this endpoint.

---

Working with pages

The pages array returned after upload contains one entry per page in the PDF. Use the array length to determine valid page indexes when placing fields.

{
  "document": {
    "id": "doc_02jy...",
    "name": "Service Agreement.pdf",
    "order": 0,
    "pages": [{}, {}, {}],
    "context": {}
  }
}

In this example, pages.length === 3 means valid page indexes are 0, 1, and 2.

---

Updating and removing documents

Documents can be renamed or removed while the envelope is in draft status.

Rename a document

PATCH /api/v1/key/envelopes/{envelopeId}/documents/{documentId}
Content-Type: application/json

{ "name": "Updated Agreement.pdf" }

Remove a document

DELETE /api/v1/key/envelopes/{envelopeId}/documents/{documentId}

caution

Removing a document also removes all fields placed on that document.