Documents reference
Create, list, send, cancel, remind, replace recipients and fields, download files, and mint embed links.
All documentation
Ten endpoints covering the whole life of a document. For a worked example rather than a reference, read send a document from a file.
The document object
{
"id": "doc_7a1b...",
"status": "in_progress",
"title": "NDA - Acme Inc",
"mode": "LIVE",
"recipients": [
{ "id": "rcp_3d9e...", "name": "Sam Rivera",
"email": "sam@example.com", "role": "Client", "status": "sent" }
],
"created_at": "2026-09-01T10:00:00.000Z"
}| Field | Type | Notes |
|---|---|---|
draft | document | Created but not sent. |
in_progress | document | Out for signature. |
completed | document | Everyone signed; PDF sealed. |
declined | document | A recipient refused. |
cancelled | document | Withdrawn by the sender. |
expired | document | Passed its expiry unsigned. |
waiting | recipient | Their turn has not come yet. |
sent | recipient | Asked, not yet opened. |
viewed | recipient | Opened it. |
signed | recipient | Done. |
reassigned | recipient | Forwarded to someone else. |
role is populated only on documents created from a template.
/v1/documents| Field | Type | Notes |
|---|---|---|
status | string | Filter by one of the document statuses above. |
limit | integer | 1 to 100. Defaults to 20. |
cursor | string | Pass next_cursor from the previous page. |
curl "https://api.documentesign.com/v1/documents?status=in_progress&limit=20" \
-H "Authorization: Bearer $ESIGN_API_KEY"{ "data": [ /* documents */ ], "has_more": true, "next_cursor": "doc_5f2a..." }Only documents in your key's mode are ever returned.
/v1/documentsReturns 201 with the document. Full body reference is on the sending guide; the short version is files and recipients are required, fields and routing are optional, and send defaults to false.
/v1/documents/{id}Returns the document object. Wrong mode returns 404.
/v1/documents/{id}/sendNo body. The document must be a draft, otherwise 409 document_not_draft. Every signer must have at least one signature field.
/v1/documents/{id}/cancelNo body. Requires an in-progress document. Writes an audit event and emits document.cancelled.
/v1/documents/{id}/remind| Field | Type | Notes |
|---|---|---|
recipient_id | string | Remind one person. Omit to remind everyone still outstanding. |
{ "reminded": 2 }If nobody was eligible, you get 409 no_recipients_to_remind rather than a zero.
/v1/documents/{id}/recipientsA full replacement, not a patch - anything you leave out is removed. 1 to 10 recipients.
REQUESTED, WAITING) rather than the lowercase public ones. Read the document back with GET /documents/{id} if you need the normalised shape./v1/documents/{id}/fieldsAlso a full replacement, up to 500 fields. Rows are recreated, so field ids are not stable across calls - do not store them.
{ "fields": [ { "id": "fld_...", "type": "SIGNATURE", "page": 1,
"recipient_id": "rcp_3d9e...", "field_key": null,
"fill_mode": "SIGNER_FILLED" } ] }/v1/documents/{id}/files/{variant}| Field | Type | Notes |
|---|---|---|
signed | path | The sealed PDF. Available once the document completes. |
certificate | path | The audit certificate: who signed, when, from where. |
original | path | The merged source document before signatures. |
{ "url": "https://...", "expires_in": 600 }The URL lasts ten minutes. Mint it when you need it rather than storing it. A variant that does not exist yet returns 404 - signed_not_available, certificate_not_available or original_not_available.
/v1/documents/{id}/recipients/{recipientId}/embed-linkMints a short-lived signing URL for one recipient. See embedded signing for the full flow, the browser events and the origin allowlist.
| Field | Type | Notes |
|---|---|---|
expires_in | integer | 60 to 3600 seconds. Defaults to 900. |
redirect_url | string | Must start with https://. |