API reference

Documents

A document is one or more PDFs sent to people to sign or to receive a copy. It goes from draft to sent to completed, or ends as declined, voided or expired.

Endpoints · 13

POST Create a document from an upload
POST Create a document from a URL
POST Create a document from a template
GET Retrieve a document
GET List documents
PATCH Update a document
POST Send a document
POST Void a document
DELETE Discard a draft
GET Download the signed PDF
GET Download the certificate
GET Download the evidence pack
POST Place or release a legal hold

The object

Field	Type	Description
`id`	string	Unique ID, starting with doc_.
`object`	string	Always "document".
`status`	enum	draft, awaiting_approval, scheduled, sent, finalizing, completed, declined, voided or expired.
`title`	string	Shown to recipients and in the inbox. Defaults to the first file name.
`message`	string	Your message in the email to recipients.
`signing_order`	enum	sequential (one signing_order group after another) or parallel (everyone at once).
`files`	array	The PDFs, in order, each with id (file_…), name, content_type, size and page_count.
`page_count`	integer	Pages across all files.
`recipients`	array	Recipient objects. See Recipients.
`template_id`	string or null	The template this document was made from.
`folder_id`	string or null	The folder it is in.
`labels`	array of strings	Your labels, for filtering.
`expires_at`	timestamp or null	After this, nobody can sign and the status becomes expired.
`send_at`	timestamp or null	When a scheduled document will go out.
`sent_at`	timestamp or null	When it went out.
`completed_at`	timestamp or null	When the last signer signed.
`voided_at`	timestamp or null	When it was cancelled.
`void_reason`	string or null	The reason given when cancelling.
`sha256`	string or null	SHA-256 fingerprint of the sealed PDF, once completed. Check it with POST /verify.
`legal_hold`	boolean	true while a legal hold stops the record from being deleted by the retention policy.
`reminder_every_days`	integer or null	Automatic reminders every this many days, or null for none.
`owner_id`	string	The user who sent it (usr_…).
`workspace_id`	string	Its workspace (wsp_…).
`metadata`	object	Up to 20 key-value strings of your own. Keys up to 40 characters, values up to 500. Never shown to recipients.
`created_at, updated_at`	timestamp	ISO 8601 in UTC.

POST/documents

Create a document from an upload

Upload up to 20 PDFs (50 MB each) as multipart/form-data, with the other parameters as JSON in a part named data. Add recipients and fields, and send, in the same call. Files are checked for viruses.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.
`file`	file	required	A PDF. Repeat the part for more files; they are kept in order.
`data.title`	string	optional	Up to 200 characters.
`data.message`	string	optional	Up to 2,000 characters.
`data.message_locale`	enum	optional	en or fr: the language of emails and the signing page for recipients without their own locale.
`data.signing_order`	enum	optional	sequential (default) or parallel.
`data.recipients`	array	optional	Up to 50. Each has name, email, role (signer or cc, default signer), and optionally key (to refer to it from fields), signing_order, locale and access_code (a code you give the signer yourself, 4 to 40 characters).
`data.fields`	array	optional	Up to 500. Same parameters as Add fields; recipient can be a recipient key or email.
`data.expires_in_days`	integer	optional	1 to 365. Defaults to the workspace setting.
`data.reminder_every_days`	integer or null	optional	1 to 30, or null for no reminders. Defaults to the workspace setting.
`data.folder_id`	string	optional	A folder ID.
`data.labels`	array	optional	Up to 20 labels, 40 characters each.
`data.metadata`	object	optional	Your own key-value data.
`data.send`	boolean	optional	true sends right away. Default false (a draft).
`data.send_at`	timestamp	optional	Send later, at this time. Implies send.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@service-agreement.pdf;type=application/pdf" \
  -F 'data={
    "title": "Service agreement - Northwind",
    "message": "Please review and sign by Friday.",
    "recipients": [
      { "key": "client", "name": "Maya Chen", "email": "maya.chen@example.com" },
      { "name": "Jordan Okafor", "email": "jordan.okafor@example.com", "role": "cc" }
    ],
    "fields": [
      { "recipient": "client", "type": "signature", "page": 6, "x": 0.12, "y": 0.71, "width": 0.3, "height": 0.06 },
      { "recipient": "client", "type": "date_signed", "page": 6, "x": 0.55, "y": 0.73, "width": 0.2, "height": 0.04 }
    ],
    "labels": ["sales"],
    "metadata": { "crm_deal_id": "D-10442" },
    "send": true
  }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "sent",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

POST/documents

Create a document from a URL

Send JSON with file_url (or files) instead of uploading; we download each file over HTTPS. All the parameters above work at the top level of the JSON.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.
`file_url`	string	optional	A public HTTPS URL of a PDF. It must answer within 30 seconds.
`files`	array	optional	Up to 20 objects with file_url, kept in order.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://example.com/files/service-agreement.pdf",
    "title": "Service agreement - Northwind",
    "recipients": [ { "key": "client", "name": "Maya Chen", "email": "maya.chen@example.com" } ],
    "fields": [ { "recipient": "client", "type": "signature", "page": 6, "x": 0.12, "y": 0.71, "width": 0.3, "height": 0.06 } ]
  }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "draft",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": null,
  "send_at": null,
  "sent_at": null,
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

POST/documents

Create a document from a template

Pass template_id and a person for each template role. Files, fields, signing order and the message come from the template.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.
`template_id`	string	required	A template ID (tpl_…).
`recipients`	array	required	One per role: template_role, name, email and optionally locale.
`title`	string	optional	Defaults to the template name.
`message`	string	optional	Defaults to the template message.
`send`	boolean	optional	true sends right away.
`folder_id, labels, metadata, reminder_every_days, send_at`		optional	As above.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_2zg4mZaouqKLiMcVbpT4r5",
    "recipients": [ { "template_role": "Client", "name": "Maya Chen", "email": "maya.chen@example.com" } ],
    "send": true
  }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "sent",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

GET/documents/{id}

Retrieve a document

Returns the document with its files and recipients.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "sent",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

GET/documents

List documents

Newest first. Filters can be combined.

Parameter	Type		Description
`limit`	integer	optional	How many objects to return, 1 to 100. Default 20.
`starting_after`	string	optional	The next_cursor from the previous page. Leave it out for the first page.
`status`	string	optional	One status, or repeat the parameter for several.
`q`	string	optional	Search titles and recipient names and emails.
`recipient_email`	string	optional	Documents sent to this address.
`label`	string	optional	Documents with this label.
`folder_id`	string	optional	Documents in this folder.
`template_id`	string	optional	Documents made from this template.
`created_after, created_before`	timestamp	optional	Creation time range.
`metadata[key]`	string	optional	Documents whose metadata key equals this value.

Request

bash

curl "https://api.esorasign.com/v1/documents?status=sent&metadata[crm_deal_id]=D-10442" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{
  "object": "list",
  "data": [
    {
      "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
      "object": "document",
      "status": "sent",
      "title": "Service agreement - Northwind",
      "message": "Please review and sign by Friday.",
      "signing_order": "sequential",
      "files": [
        { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
      ],
      "page_count": 6,
      "recipients": [
        {
          "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
          "object": "recipient",
          "name": "Maya Chen",
          "email": "maya.chen@example.com",
          "role": "signer",
          "signing_order": 1,
          "locale": "en",
          "template_role": null,
          "access_code": false,
          "status": "sent",
          "sent_at": "2026-11-02T14:05:11.000Z",
          "viewed_at": null,
          "signed_at": null,
          "declined_at": null,
          "decline_reason": null
        },
        {
          "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
          "object": "recipient",
          "name": "Jordan Okafor",
          "email": "jordan.okafor@example.com",
          "role": "cc",
          "signing_order": 2,
          "locale": "en",
          "template_role": null,
          "access_code": false,
          "status": "pending",
          "sent_at": null,
          "viewed_at": null,
          "signed_at": null,
          "declined_at": null,
          "decline_reason": null
        }
      ],
      "template_id": null,
      "folder_id": null,
      "labels": ["sales"],
      "expires_at": "2026-12-02T14:05:11.000Z",
      "send_at": null,
      "sent_at": "2026-11-02T14:05:11.000Z",
      "completed_at": null,
      "voided_at": null,
      "void_reason": null,
      "sha256": null,
      "legal_hold": false,
      "reminder_every_days": 3,
      "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
      "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
      "metadata": { "crm_deal_id": "D-10442" },
      "created_at": "2026-11-02T14:04:58.000Z",
      "updated_at": "2026-11-02T14:05:11.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

PATCH/documents/{id}

Update a document

Title, message, signing order and expiry can change while it is a draft. Folder, labels and metadata can change at any time.

Parameter	Type		Description
`title`	string	optional	Drafts only.
`message`	string	optional	Drafts only.
`signing_order`	enum	optional	Drafts only.
`expires_in_days`	integer	optional	Drafts only. 1 to 365.
`folder_id`	string or null	optional	null takes it out of its folder.
`labels`	array	optional	Replaces the labels.
`metadata`	object	optional	Replaces the metadata.

Request

bash

curl -X PATCH "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["sales", "renewal"] }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "sent",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

POST/documents/{id}/send

Send a document

Sends a draft, or schedules it with send_at. It must have at least one signer, and every signer needs a signature field. If an approval rule matches, the status becomes awaiting_approval and it goes out once approved.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.
`send_at`	timestamp	optional	Send later, at this time.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/send" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "sent",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "sent",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": null,
  "void_reason": null,
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

POST/documents/{id}/void

Void a document

Cancels a document that is out for signature. Signing links stop working. Completed records can’t be voided.

Parameter	Type		Description
`Idempotency-Key`	header	required	A unique value for this action, 8 to 200 characters. See Idempotency.
`reason`	string	required	3 to 500 characters. Kept in the audit trail and returned as void_reason.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/void" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "The pricing changed. A new version is on its way." }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "voided",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "voided",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": null,
  "voided_at": "2026-11-02T16:20:00.000Z",
  "void_reason": "The pricing changed. A new version is on its way.",
  "sha256": null,
  "legal_hold": false,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}

DELETE/documents/{id}

Discard a draft

Only drafts can be discarded. Sent documents are records: void them instead.

Request

bash

curl -X DELETE "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

json

{ "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F", "object": "document", "deleted": true }

GET/documents/{id}/download

Download the signed PDF

The sealed PDF of a completed document (application/pdf). 409 not_completed until it is ready.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/download" \
  -H "Authorization: Bearer $ESORA_API_KEY" -o signed.pdf

Response

text

The PDF file.

GET/documents/{id}/certificate

Download the certificate

The Certificate of Completion (application/pdf): who signed, when, how they were verified, and the fingerprints.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/certificate" \
  -H "Authorization: Bearer $ESORA_API_KEY" -o certificate.pdf

Response

text

The PDF file.

GET/documents/{id}/evidence-pack

Download the evidence pack

The signed evidence manifest (application/json): every step, with times, addresses and fingerprints. It is kept even after the retention policy deletes the files.

Request

bash

curl "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/evidence-pack" \
  -H "Authorization: Bearer $ESORA_API_KEY"

Response

text

The manifest JSON file.

POST/documents/{id}/legal-hold

Place or release a legal hold

While held, the retention policy won’t delete the record.

Parameter	Type		Description
`hold`	boolean	required	true to hold, false to release.
`reason`	string	optional	Up to 500 characters.

Request

bash

curl -X POST "https://api.esorasign.com/v1/documents/doc_3y9Pf34qY6Nb3wWD25RQ4F/legal-hold" \
  -H "Authorization: Bearer $ESORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "hold": true, "reason": "Contract dispute, matter 2026-118" }'

Response

json

{
  "id": "doc_3y9Pf34qY6Nb3wWD25RQ4F",
  "object": "document",
  "status": "completed",
  "title": "Service agreement - Northwind",
  "message": "Please review and sign by Friday.",
  "signing_order": "sequential",
  "files": [
    { "id": "file_5aJXVuLkSIc47WQAmL9xVQ", "name": "Service agreement.pdf", "content_type": "application/pdf", "size": 184211, "page_count": 6 }
  ],
  "page_count": 6,
  "recipients": [
    {
      "id": "rcp_5ZR3qa7yEeeby3abP3E2Zs",
      "object": "recipient",
      "name": "Maya Chen",
      "email": "maya.chen@example.com",
      "role": "signer",
      "signing_order": 1,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "signed",
      "sent_at": "2026-11-02T14:05:11.000Z",
      "viewed_at": null,
      "signed_at": "2026-11-03T09:41:27.000Z",
      "declined_at": null,
      "decline_reason": null
    },
    {
      "id": "rcp_1IQ9Y7aJZqhB6baeCN6Zj4",
      "object": "recipient",
      "name": "Jordan Okafor",
      "email": "jordan.okafor@example.com",
      "role": "cc",
      "signing_order": 2,
      "locale": "en",
      "template_role": null,
      "access_code": false,
      "status": "pending",
      "sent_at": null,
      "viewed_at": null,
      "signed_at": null,
      "declined_at": null,
      "decline_reason": null
    }
  ],
  "template_id": null,
  "folder_id": null,
  "labels": ["sales"],
  "expires_at": "2026-12-02T14:05:11.000Z",
  "send_at": null,
  "sent_at": "2026-11-02T14:05:11.000Z",
  "completed_at": "2026-11-03T09:41:27.000Z",
  "voided_at": null,
  "void_reason": null,
  "sha256": "9f2c4e1b7a03d5f86c2e9b14a7d0f3c58e61b2a49d7c0e3f15a8b6d2c4e9f701",
  "legal_hold": true,
  "reminder_every_days": 3,
  "owner_id": "usr_4tDdO9eGzMcNU77sVTUUJ5",
  "workspace_id": "wsp_16lLlGUriAX1DyyXN9iYw1",
  "metadata": { "crm_deal_id": "D-10442" },
  "created_at": "2026-11-02T14:04:58.000Z",
  "updated_at": "2026-11-02T14:05:11.000Z"
}