Envelopes API
Upload files, build a draft envelope, add recipients and fields, preview it, send it, and correct it after sending.
An envelope holds one or more documents and the people who act on them. Its status is draft, sent, completed, voided, declined or expired. All paths below start with /api/v1. POST /envelopes makes an envelope from templates or from a file. Templates themselves can be created, changed and deleted through /templates; see the API reference. A new envelope is answered at once with preparation_status: "preparing", and its documents and fields are built in the background; see Preparation.
Every envelope response, from GET, a list or any action, and every envelope.* webhook, has the same fields, including its recipients (in signing order), the templates it was made from, signing_order, preparation_status, finalization_status and revision (the number corrections check in expected_revision). expand[]=fields and expand[]=documents add those lists.
The envelope's source is kiosk or share_link when a person started it from a template's kiosk or share link, and bulk_send when a bulk send sent it; then bulk_send holds the bulk send's ID (bks_…). Both are null for envelopes sent one by one, from the app or the API. Webhook envelope objects include the same fields.
A completed envelope whose template sets Valid for (the template's valid_for_months) has validity_ends_at: completed_at plus that many months. It follows the template's current setting, so changing the template moves it, for envelopes already completed too. It's null until the envelope is completed, and when the template sets none.
Upload a file
POST /files (ability files:write) takes a multipart file (a PDF; an Office file: doc, docx, odt, rtf, txt, xls, xlsx, ods, ppt, pptx, odp; or an image: jpg, jpeg, png, gif, webp, heic, heif, tif, tiff, bmp) or a public HTTPS url to a PDF. Office files and images are converted to PDF; each image becomes one Letter page. Optional: password for a protected PDF, use_text_tags (default true) to turn text tags into fields, and form_fields. A fillable PDF's own form fields are found and set up (import, the default); flatten uses it as a plain PDF instead. The old import_form_fields flag is refused with a 422; use form_fields. See Fillable PDF forms. An AI agent with a file on its own computer uses the MCP tool create_upload_link instead of a public URL; see Uploading a local file.
curl -X POST https://esignstack.app/api/v1/files \
-H "Authorization: Bearer $ESIGNSTACK_KEY" \
-H "Idempotency-Key: order-456-file" \
-F file=@agreement.pdfFiles you do not use are deleted after 7 days.
The upload is stored and answered with 201 and status: "processing". The file is then checked and converted in the background and becomes ready or failed (with failure: {code, message}). A ready file also has the sha256 of what you uploaded. Check it with GET /files/{file} (ability files:read) or wait for the file.ready or file.failed event. POST /envelopes takes a file that is still processing; POST /templates and PUT /envelopes/{envelope}/documents need it ready.
Create from templates
POST /envelopes with templates makes one envelope from one or more templates. Their documents appear in the order you list them, and the people you name fill the templates' roles. Use it for a packet that changes from case to case: send only the forms that apply, in one envelope the family signs in one sitting.
This arrangement conference needs the statement of goods and services, an embalming authorization and a cremation authorization. Each form has an "Authorizing agent" role for the family member; the statement also has a "Funeral director" role:
{
"templates": ["tpl_01J…goods", "tpl_01J…embalming", "tpl_01J…cremation"],
"name": "Arrangements for Sam Example",
"recipients": [
{ "name": "Pat Example", "email": "pat@example.com", "roles": ["Authorizing agent"] },
{ "name": "Dana Director", "email": "dana@example.com", "roles": ["Funeral director"], "routing_order": 2 }
],
"values": { "Decedent name": "Sam Example", "Date of death": "2026-10-20" },
"external_id": "case-1001",
"send": true
}- Roles. Each recipient lists the roles it fills in
roles. Roles with the same name in several templates (ignoring case) are one role, so Pat signs all three forms. One person can also fill roles with different names, such as["Authorizing agent", "Purchaser"]. - Every role with fields needs someone, unless the template always sends that role to the same person. Otherwise the request is refused with a
422that names the missing roles, and nothing is created. A role without fields (an approver, a "needs to acknowledge" or a "gets a copy" role) can be left out; the envelope then has no recipient for it. - A role must be the same type in every template that has it. A
signerin one and aviewerin another is refused (422,paramtemplates.1); rename one of them. - Values.
valuesfill fields by their label in every template that has the label. When two templates have a field with the same label, the later one is renamed with its template's name in front (Cremation authorization: Decedent name) so signers' answers stay separate, but one value still fills both. - Signing order.
routing_ordersets one recipient's step (1 to 99). Without it, templates with signing stages keep them: the first template's roles first, then each next template's after them. Templates without stages usesigning_order(parallelorsequential). - Settings from the templates. The envelope takes the first template's name (unless you send
name), filing rule, return URL and email. For email, the request wins, then the first template’s saved email template or its own subject and note, then the workspace default, then the standard email. Expiry and reminders use the request and workspace defaults. senddefaults tofalse: the envelope stays a draft untilPOST /envelopes/{envelope}/send. Withsend: truethe whole envelope is sent once it is prepared, and counts as one envelope toward your plan's API envelope limit. Wait forenvelope.sentbefore you open signing sessions; see Preparation.- The envelope's recipients are added when it is prepared, so the
201response doesn't list them yet.
Sender pre-fill is fixed. An editable signer field gets a starting value the signer can change or clear. A read-only signer field is fixed (validation.read_only: true). At creation, an omitted label inherits the template default; null or an empty string clears it. On draft update, an omitted label preserves its value; null or an empty string clears it. Unknown or ambiguous labels return 422 at values.{label}. Values must satisfy every targeted field’s rules; send ssn_last4 as a four-digit string, such as "0123".
- The recipient object is the one the recipients endpoints take, so
auth_method,host_email,embedded,allow_delegation,receive_completed_pdfandmetadatawork here too. A recipient'stypecomes from its roles: leave it out, or send the same type (a different one is refused).rolecomes from the roles too, anddocumentscan't be set until the envelope exists. - Copies. Someone not on the templates who only gets the completed documents is
{ "email": "…", "type": "cc" }, withoutroles. - Up to 10 templates, each listed once. Every template must be in the key's workspace and mode and not archived.
Each document in the envelope (GET /envelopes/{envelope}/documents, or expand[]=documents) has the template it came from and the template_version used, so you can file each signed form by its template. The envelope's own templates lists them all, in document order, and filter[template] finds an envelope by any of them. The envelope history records every template and version.
POST /templates/{template}/envelopes does the same for one template; send defaults to false there too.
Create a draft from a file
POST /envelopes with file creates a draft from an uploaded file, with its recipients:
{
"file": "file_01J…",
"name": "Acme service agreement",
"recipients": [
{ "name": "Pat Example", "email": "pat@example.com" },
{ "name": "Dana Director", "email": "dana@example.com", "routing_order": 2 },
{ "email": "records@example.com", "type": "cc" }
],
"external_id": "order-456",
"email_subject": "Please sign the Acme agreement",
"expires_in_days": 30
}- One step, all or nothing. The draft and its recipients are created together. If any recipient is refused (
422, withparamsuch asrecipients.1.email), nothing is created. The response lists the recipients with their IDs (rcp_…) at once; place their fields once the draft is prepared. - Text tags follow the list.
signer1goes to the first entry inrecipients,signer2to the second, and so on, counting every entry, including approvers and copies. A tag for accentry stays unassigned. signing_order(parallelorsequential) sets the signing steps from the list order; a recipient'srouting_orderwins.send: truesends it once it is prepared. Every signer then needs a field already, from text tags. If the send is refused, the envelope stays a draft withsend_errorandenvelope.send_failedfires; see Preparation.- Recipients can also be left out and added later, with the recipients endpoints.
expires_in_days is how long recipients get to sign, counted from when the envelope is sent, not from when the draft is made. A draft shows it as expires_in_days and its expires_at stays null until it is sent; expires_at_if_sent_now is the deadline it would get if you sent it now. Leave it out to use the workspace's signing window. Add folder (an envelope folder ID, fdr_…) to put the draft in a folder. The file can still be processing: the draft is prepared once the file is ready, and its preparation fails if the file fails.
reminderssets the envelope's reminder emails:enabled,initial_delay_days(1 to 30),frequency_days(1, 2, 3, 5, 7 or 14),max_count(1 to 20) andskip_weekends. Keys you leave out, or set tonull, use the workspace's defaults. Every envelope shows the settings it uses underreminders.message_template(amsgt_…ID from email templates) fills the invitation subject and note; anemail_subject(≤255) oremail_message(≤5000) sent alongside wins for that part. On create, sending any of the three sets the whole email: a part you don't send is empty, andnullmeans the standard one. Send none of them and the draft starts from the first template's email, then the workspace default, then the standard email. OnPATCH, a subject or note alone changes only that part. Variables such as{{recipient_name}}stay as written and are filled in for each recipient when the email goes out; an unknown one is a422naming the field. The note is quoted under the standard lines as a message from the sender. Envelopes showemail_subject,email_messageandmessage_template, the email template the draft's email is based on.
Both work on PATCH /envelopes/{envelope} and on envelopes from templates too. In a PATCH, only the reminders keys you send change. Change draft settings with PATCH /envelopes/{envelope}; on an envelope that's already sent, it returns 409 resource_conflict. Delete a draft with DELETE /envelopes/{envelope}, which answers {id, object: "envelope", deleted: true}. A sent envelope can't be deleted (409; void it instead). A deleted draft shows deleted: true (and archived: false), is in no list, and is purged after the workspace's deleted-draft retention period; until then POST …/restore brings it back. Deleting it again changes nothing. PATCH refuses folder, filing_rule, archived, deleted with a 422 that names the action to use. notification_policy changes only the kinds you send, as on the workspace. send_emails: false means eSignStack sends no emails for the envelope; your app brings people to sign with signing sessions.
Preparation
POST /envelopes (from templates or a file), POST /templates/{template}/envelopes and POST /envelopes/{envelope}/duplicate answer 201 at once. A queued job then builds the envelope's documents and fields, and for an envelope from templates, its recipients:
{
"id": "env_01J…",
"object": "envelope",
"status": "draft",
"preparation_status": "preparing",
"preparation_error": null,
"send_error": null,
"…": "…"
}preparation_statusispreparing, thenready(envelope.prepared) orfailed(envelope.preparation_failed).preparation_erroris{code, message, param}ornull. Itscodeispdf_password_requiredfor a protected file,preparation_stuckwhen preparation stopped without finishing, or the code of the error that stopped it, such as a file that can't be read.- Until it is ready, the envelope can be read (
GET), deleted, and retried; anything else, including fields, recipients, documents, pages, preview, send, duplicate, save as template, editor sessions and signing sessions, answers409 envelope_preparingwithparam: envelopeandRetry-After: 2. Once it has failed, the same requests answer409 envelope_preparation_failed. POST /envelopes/{envelope}/retry_preparation(abilityenvelopes:write) starts it again after you fix the cause, and answers200with the envelope,preparingagain. A ready envelope is returned unchanged; one still preparing is409 resource_conflict.- Input that can be checked at once, such as an unknown role or
valueslabel, a missing plan feature or an invalid recipient, is still refused with422,409or403, and nothing is created. Create requests don't answer503when PDF processing is briefly unavailable; the job retries by itself.
With send: true, the envelope is sent once it is prepared. envelope.prepared alone doesn't mean it was sent: wait for envelope.sent, or GET it until status is sent. If the send is refused, for example by an API envelope limit, the envelope stays a ready draft, send_error is {code, message, param} (with quota when an allowance refused it), and envelope.send_failed fires. Fix the cause and call POST /envelopes/{envelope}/send.
Webhooks can arrive more than once and out of order. De-duplicate on the event ID and GET the envelope for its current state.
Draft from a file:
POST /files. Waiting forfile.readyisn't needed forPOST /envelopes, only forPOST /templatesandPUT …/documents.POST /envelopeswithfileandrecipients.- Wait for
envelope.prepared, orGET /envelopes/{envelope}untilpreparation_statusisready. - Add fields with
POST /envelopes/{envelope}/fields. POST /envelopes/{envelope}/send.
Send in one call:
POST /envelopeswithtemplates,recipientsandsend: true.- Wait for
envelope.sent, orGETuntilstatusissent. Onenvelope.send_failed, readsend_error. - Create signing sessions for embedded signers.
Documents and pages
PUT /envelopes/{envelope}/documents replaces the draft's documents. Each document is built from pages of uploaded files (file) or of documents already in the envelope (document), with optional rotation (0, 90, 180 or 270):
{
"documents": [
{ "name": "Agreement", "pages": [{ "file": "file_01J…", "page": 1 }, { "file": "file_01J…", "page": 2 }] },
{ "name": "Pricing", "pages": [{ "file": "file_01J…", "page": 1 }], "visible_to": ["rcp_01J…"] }
]
}Fields move with their page. Fields on pages you drop are removed. GET /envelopes/{envelope}/pages lists every page in the order fields use.
form_fields says what a document does with a fillable PDF's own fields: import sets them up, flatten uses the PDF as a plain one. Leave it out to keep the document's current choice; a new document takes the choice of the file it comes from. Documents show it as form_fields.
visible_to limits who sees a document. It's a list of recipient IDs: null means everyone and [] means no one. A recipient's signing copy contains only the documents they can see, and you can't give a recipient a field on a document they can't see. You can also set a recipient's documents (a list of doc_… IDs) from the recipient endpoints.
Recipients
A draft's recipients are set when it is created and changed with:
| Endpoint | Does |
|---|---|
PUT /envelopes/{envelope}/recipients |
Replaces the whole list (see below). Returns the list. |
POST /envelopes/{envelope}/recipients |
Adds one recipient. |
PATCH …/recipients/{recipient} |
Changes one recipient. Only the keys you send change. |
DELETE …/recipients/{recipient} |
Removes one recipient, with their fields. |
All of them take the same recipient object, and work on drafts only: a sent envelope returns 409 resource_conflict; use corrections instead.
type |
Shown in the app as | What they do |
|---|---|---|
signer |
Signer | Completes their fields and signs |
approver |
Approver | Reviews the documents and clicks Approve or Reject |
viewer |
Needs to acknowledge | Reviews the documents and confirms they've read them |
cc |
Gets a copy | Gets the completed documents; takes no action |
An approval or acknowledgment is recorded in the envelope history and on the certificate. Nothing is added to the PDF. Only signers can have fields.
The recipient object:
nameandemail. A new recipient needs both; accmay go without a name, and anin_person_signerwithout an email (it's only for their copy).type: one of the above, orin_person_signer(see Signing in person). Defaults tosigner.routing_order(1 to 99): recipients with the same number act at the same time; higher numbers wait for lower ones.role: a label such asClient.private_message: an optional plain-text note for this recipient, up to 5,000 characters, with the same variables asemail_message. It appears as a separate paragraph under the envelope message in the same note in signing requests, resends and automatic reminders, or on its own when there is no envelope message. Other recipients never see it; workspace members can read it in the envelope. Set it while the envelope is a draft: omit it to keep the current value, or sendnullto clear it. Recipient responses include it. Templates have no role default for it. CC, in-person and embedded recipients accept it but aren't emailed it.auth_method:none,access_code(send the code inaccess_code),sms(withauth_phonein E.164 format) oremail_otp. Any method other thannoneneeds the Pro or Platform plan, andsmsneeds a live key. Leaveauth_methodout to keep the current one; a kept access code or phone stays unless you send a new one.receive_completed_pdf: whether the recipient is emailed the completed documents.allow_delegation: see Reassigning.embedded: see Signing in your app.host_email: anin_person_signer's host, a member of the workspace. Defaults to the sender.metadata: your own string keys and values, up to 20.documents: the documents (doc_…) the recipient sees;nullfor all of them. Not when creating an envelope, since its documents don't have IDs yet.roles: only withtemplates; see Create from templates.id: only inPUT …/recipients.
Replacing the list
PUT /envelopes/{envelope}/recipients takes the whole list, in order, and optional signing_order:
{
"recipients": [
{ "id": "rcp_01J…pat", "email": "pat.example@example.com" },
{ "name": "Sam Witness", "email": "sam@example.com", "type": "approver" }
]
}- An entry with
idupdates that recipient. What it leaves out stays as it is, including its fields. - An entry without
idis a new recipient. - Recipients you leave out are removed, with their fields. To keep someone, list their
id. - It all happens in one transaction: if any entry is refused, nothing changes. Errors name the entry, such as
recipients.1.email. - The response is the new list, as
GET …/recipientsreturns it.
Retries
POST /envelopes and POST …/recipients take an Idempotency-Key header: a retry with the same key and body returns the first response instead of creating a second envelope or recipient. For POST /envelopes that is the original 201, with the same ID and still preparing; use GET /envelopes/{envelope} to follow its progress, not a replay. PUT …/recipients is safe to repeat as it is: the same body leaves the same list. Entries without id are new recipients each time, so send the IDs from the first response once you have them.
Signing in your app
Set embedded: true on a recipient who signs inside your app, for example someone sitting with you, while others on the same envelope sign from their email. It works like DocuSign's clientUserId. eSignStack sends that recipient no invitation, reminder, next-signer or "document updated" email, and the app shows no resend or remind button for them. You open their signing page with a signing session, hosted or embedded.
An AI agent can get a hosted link for a signer who is with the user, for example at a front desk, with the MCP tool create_signing_link. The same rules apply: it must be their turn, and in-person signers sign in the app on their host's device.
Everything else stays the same. recipient.activated fires when it's their turn, so in a signing order you know when to open their session. Other webhooks fire as usual. Their completed copy and void or decline notices follow your notification settings, and email or SMS verification codes still go out, since the signer asks for them.
- An embedded recipient still needs an email address, like any signer.
- It defaults to
false. Set it when you add the recipient, on a draft, or with a correction before that recipient acts. Leaving it out of an update keeps the current value. ccandin_person_signerrecipients can't be embedded (422).- In
POST /envelopes, setembeddedon an entry inrecipients.
Fields
POST /envelopes/{envelope}/fields adds a field; PATCH and DELETE on …/fields/{field} change or remove one. A new field requires type, page and box. A PATCH keeps every attribute you leave out, including its type, document, page, box and recipient; an empty object leaves it unchanged. Adding a field for another signer does not change existing fields, so you do not need to send their placement again. You can change a manually placed field's type with PATCH while keeping its position.
{
"type": "signature",
"recipient": "rcp_01J…",
"document": "doc_01J…",
"page": 1,
"box": { "x": 72, "y": 640, "width": 180, "height": 40 },
"required": true
}box is in PDF points from the top-left corner of the page, the same box a field response has, so a field you read can be sent back as it is. page is counted within document; a negative number counts from the end. A response also has envelope_page, the page counted across all documents. type is one of signature, initials, date_signed, name, email, company, title, text, number, date, checkbox, checkbox_group, radio_group, dropdown, attachment or repeat_group. Every field needs a recipient, unless you set prefill: true and fill it yourself with value before sending. Other options: label, options (for choice fields), validation and tab_order. See Fields for what each type does.
Fillable PDF forms
An envelope made from a fillable PDF gets the form's own fields. Fields with a value are kept as filled; empty ones go to the first signer once you add one. To choose which fields recipients fill, list them and assign the ones you need. The rest stay as they are in the PDF.
To use a form as a plain PDF, upload it with form_fields: flatten, or set form_fields: flatten on its document with PUT /envelopes/{envelope}/documents. The form is printed as it looks, values and boxes included; none of its fields are left in the envelope, the signing copy or the signed PDF, and its form_policy becomes static_appearances. Set form_fields: import on a draft to get them back. Deleting one form field (DELETE /envelopes/{envelope}/fields/{field}) leaves it out of the signed PDF.
GET /envelopes/{envelope}/form_fields (ability envelopes:read) lists one entry per form field: name, label, type, page and box, value, required, read_only, and status (assigned, kept or unassigned) with its recipient. A field with several boxes, such as a radio button per choice, lists each in widgets. The response also has an acceptance_digest.
PUT /envelopes/{envelope}/form_fields (ability envelopes:write) replaces the choice:
{
"acceptance_digest": "9f2c…",
"fields": [
{ "name": "FullName", "recipient": "rcp_01J…", "required": true },
{ "name": "Email", "recipient": "rcp_01J…", "label": "Signer email" }
]
}- Every form field you leave out keeps its current value, and nobody fills it.
- Read-only form fields always stay as they are.
- Signature and initials fields can't stay empty. One you leave out keeps its recipient; if it has none, the request is refused.
- If the form changed since you listed it, the request is refused with
acceptance_digestas theparam. List it again.
When the list has requires_acceptance: true, the upload was a converted XFA form, and notices explain what changed. Sending needs the report accepted. Show the user the notices, then use the PUT request with the current acceptance_digest and the form fields recipients fill to accept it for your key.
Sending without acceptance is refused with a 422 whose message explains how to accept the report. A non-empty fields is refused when the envelope has no form fields.
Templates work the same way with GET and PUT /templates/{template}/form_fields (abilities templates:read and templates:write), using role instead of recipient.
Preview
POST /envelopes/{envelope}/preview (ability envelopes:write) renders the draft as it is now, watermarked "DRAFT — not for signature". Each field is drawn as a box at its position and size, tinted in its recipient's color and labeled with its type and recipient (for example "Sign · Bob"); optional fields have a dashed outline. It returns a url that works for 15 minutes. If the draft changes, request a new preview.
To show the preview inside your app, send parent_origin. It must exactly match one of the origins in Settings → Embedding. The response adds preview_session; put preview_session.url in an iframe. Open it within 10 minutes; the read-only session then lasts 15 minutes. The page posts messages to your page with their name in type, as the signing page does: esignstack:preview.ready, esignstack:preview.stale (the draft changed), esignstack:session.expired, esignstack:error and esignstack:resize. It has no signing or editing actions.
Send
POST /envelopes/{envelope}/send (ability envelopes:send) sends the draft once it is prepared. A live send counts toward your plan's API envelope limit.
After sending:
| Endpoint | Does |
|---|---|
POST …/remind |
Emails a reminder. Optional recipient for one person and message (≤5000, email variables allowed) to quote instead of both the envelope message and that recipient's private message. Nobody to remind is 409 resource_conflict; the same person again too soon is 409 reminder_too_soon with Retry-After. |
POST …/extend |
Adds days (1 to 365) to the expiry. notify_pending_signers is optional. |
POST …/void |
Voids the envelope. reason is optional (up to 1000 characters; a generic one is used without it). It goes in the audit log and in the "voided" email to everyone who was invited. |
POST …/duplicate |
Copies the envelope into a new draft, which is prepared like a new envelope. |
POST …/move |
Moves the envelope to folder, or out of its folder with null. Works for any status. |
GET …/artifacts |
The envelope's stored files (object: "artifact", art_…): the originals, the signing PDF, sealed_pdf, per_document_pdfs, the certificate and the evidence, each with filename, mime_type, size, sha256 and a download_url that works until download_url_expires_at (5 minutes; ability artifacts:read). A link is null until its file exists. Each entry in per_document_pdfs names its document and the template and template_version it came from; an original names the upload (file) it was kept from. |
GET …/audit_trail |
The audit trail as data: the same entries as the certificate (event, actor, ip, created), in any status. |
POST /envelope_downloads |
One ZIP with the signed PDFs of up to 50 completed envelopes, behind a 10-minute link (ability artifacts:read). |
POST …/retry_finalization |
Retries a completion that failed (envelope.finalization_failed) or is stuck: finalization_status shows stuck when it was queued or processing with no progress for 15 minutes. |
GET …/attachments |
Files signers uploaded; see Signer attachments. |
Who it was for
When your app acts for one of its users, pass actor on POST /envelopes (from templates or a file), POST /templates/{template}/envelopes, POST …/send, POST …/void, POST …/remind, POST …/extend, POST …/corrections. Editor and signing sessions take the same actor. A funeral home platform creating and sending a packet for the arranger at the desk sends:
{ "actor": { "name": "Jane Smith", "email": "jane@example.com", "external_id": "staff_42" } }name is required; email and external_id are optional, and other keys are refused. The envelope's history and the activity feed then show the entry as "Sent · Jane Smith (via Acme Arrangements)", using your platform's name, or the key's name for a workspace key. The same goes for created and voided, and the envelope page shows her as its sender. The audit log keeps all three values as your statement. It's a label only: she isn't added to the workspace and gets no email, and the completion certificate still names the API client. Without actor, entries show "API client" as before. The MCP tools create_envelope_draft, send_envelope, void_envelope, remind_recipient, extend_envelope and correct_envelope take the same actor.
Archived envelopes are left out of GET /envelopes; GET /envelopes?filter[archived]=true lists only them. They can still be read in full, with their recipients, fields, documents, pages, artifacts, attachments and audit trail, and duplicated; changing one is 409 resource_conflict until it's restored. Archived envelopes are kept until you restore them. Drafts can't be archived: delete them instead. To find envelopes, see Find envelopes.
Find envelopes
GET /envelopes lists the workspace's envelopes, newest first. A test key lists the sandbox's envelopes. Combine these filters:
| Filter | Finds |
|---|---|
filter[q] |
Envelopes whose name, or a recipient's name or email, contains the text (at least 2 characters, any case) |
filter[recipient_email] |
Envelopes with a recipient at exactly this email address (any case) |
filter[folder] |
Envelopes in this folder (fdr_…), not its subfolders |
filter[bulk_send] |
Envelopes sent by this bulk send (bks_…) |
filter[status], filter[external_id], filter[template] |
Envelopes with this status, your own reference or template |
filter[created][gte], filter[created][lte] (also gt, lt) |
Created on or after, or on or before, a date or time |
filter[sent][…] |
First sent within the bounds. Drafts never match. |
filter[completed][…] |
Completed within the bounds |
filter[metadata][key] |
Envelopes whose metadata key has this value |
Dates are ISO 8601 dates or date-times, or Unix times in seconds; nothing else is guessed at. A bare date means midnight UTC at its start. Each envelope shows sent_at and completed_at.
curl -G https://esignstack.app/api/v1/envelopes \
-H "Authorization: Bearer $ESIGNSTACK_KEY" \
--data-urlencode "filter[recipient_email]=pat@example.com" \
--data-urlencode "filter[sent][gte]=2026-01-01"Signer attachments
Signers can upload files to attachment fields, such as a photo ID. GET /envelopes/{envelope}/attachments (ability artifacts:read) lists the files they submitted, in field order: filename, mime_type, size, sha256, the recipient and field they belong to, and a download_url that works until download_url_expires_at (5 minutes). GET /envelopes/{envelope}/attachments/{attachment} returns one with a new link. The attachment id is the attachment field's value. A download is checked against the stored hash first.
Email templates (message templates)
Email templates (the API resource message_templates) are saved subjects and notes from the app’s Email templates page. GET /message_templates lists them (filter[q] searches names) and GET /message_templates/{id} returns one (ability envelopes:read). POST, PATCH and DELETE create, change and delete them (ability envelopes:write; personal keys and connections also need an owner or admin). is_default: true moves the workspace’s single default to it; false on that default clears it. Deleting the default makes new envelopes use the standard email. Document templates linked to a deleted email template fall back to the workspace default. A test key reads and changes the sandbox's own message templates. Use one on a draft with message_template.
Corrections
POST /envelopes/{envelope}/corrections (ability envelopes:send) changes an envelope that's out for signature:
recipients: change the name, email or authentication of recipients who haven't acted, byid. A new email, phone or authentication method stops their old link, and they get a new one if it's their turn. A name change keeps the link.add_recipients: add recipients to routing stages that haven't started.remove_recipients: remove recipients who haven't acted.documents: a replacement document list, in the same shape as the documents endpoint.fields: a complete replacement field list.noteandexpected_revision, which refuses the change with409 resource_conflict(param: expected_revision) if the envelope changed since you read it (the envelope'srevision).actor, as on send and void.
The response lists what changed: changed_recipients (each recipient with what changed), added_recipients and removed_recipients (each a recipient), documents_replaced, fields_replaced, and the new revision. An envelope that isn't out for signature is 409 resource_conflict.
A correction can turn embedded on or off for a recipient who hasn't acted. Either way their current link stops working: turned on, they sign only through signing sessions; turned off, eSignStack emails them a new link.
Send documents and fields in separate requests: correct documents first, then fields using the new doc_… IDs. Documents and fields can change only until any recipient has acted. After that the API returns 409 correction_requires_void; void the envelope and send a new one. Content changes keep signing links and signing sessions working: they open the new version, and an action from a page that still shows the old one is refused, so the page reloads with the new version. Everyone consents again, and everyone whose turn it is gets an email with their existing link. Earlier versions stay in the envelope history.
Reassigning
Set allow_delegation: true on a signer, approver or recipient who needs to acknowledge to let them pass their invitation to someone else before acting. It defaults to false, and leaving it out of an update keeps the current setting. Recipients who get a copy can't delegate.
Template roles have the same setting. Envelopes made from a template inherit it, and an explicit allow_delegation on a recipient in POST /templates/{template}/envelopes overrides it.
The recipient reassigns from the signing page (Reassign to someone else). Their link stops working, the new person gets an invitation, and the change is recorded in the envelope history. The new person still has to pass any required authentication.
Signing disclosure
Before signing, a signer sees the electronic signature disclosure: a title, a body and the label of the checkbox they tick. These are the same words as in Settings → Signing disclosure.
| Request | Ability | What it does |
|---|---|---|
GET /consent_disclosures/current |
envelopes:read |
The wording new envelopes are sent with, and its version |
GET /consent_disclosures |
envelopes:read |
Every version, newest first |
GET /consent_disclosures/{version} |
envelopes:read |
One version |
POST /consent_disclosures |
envelopes:write |
Publish a new version. Send any of title, body and agreement_label; fields you leave out stay as they are, and null goes back to the default. |
- Versions never change. Each envelope keeps the version it was sent with, so a new version only applies to envelopes sent after it.
- A test key reads and publishes the sandbox's wording. The sandbox starts with a copy of the live wording, and after that the two are separate.
- In
GET /envelopes/{id}/audit_trail, each consent entry has theconsent_disclosure_versionthe signer agreed to (nullon other entries).GET /consent_disclosures/{version}returns its wording. - Whether signers must agree is the workspace setting
require_esign_consent, changed withPATCH /workspace({"settings": {"require_esign_consent": false}}) or, for a platform,PATCH /workspaces/{workspace}. A test key changes the sandbox's setting, which is separate from the live one. Withfalse, signers get a link to the disclosure, and signing counts as agreeing. It applies to envelopes sent afterwards, and changes appear in the workspace activity log.
Test keys
Test keys use every endpoint on this page, including upload, create, send, correct and duplicate, in the workspace's sandbox. Live data isn't visible to them. Test envelopes don't count toward any limit, every page is marked as a test, and emails go only to verified members of the workspace. Sending with SMS verification returns 422. See Sandbox.
When completion_emails_delayed is true, eligible completion emails remain unsent at least 15 minutes after completion. Use POST /api/v1/envelopes/{id}/retry_finalization (or MCP retry_finalization) to retry only missing emails. The completed PDF and signatures are preserved. The app shows the same recovery to workspace owners and admins.
Send capacity
Live completions are timestamp sealed automatically using DigiCert, with Sectigo fallback. Sandbox envelopes never receive a production timestamp.
Sending checks the whole envelope before it is frozen, charged or emailed. The default limits are 20 documents and 750 source pages, and an estimated completed PDF of 32 MiB for live envelopes (timestamp sealed by default), or 48 MiB for sandbox envelopes. The 48 MiB limit also applies when sealing is globally disabled. The byte estimate uses the larger of the combined signing PDF and the total prepared document PDFs, plus 10 MiB per signer attachment field, including optional fields, and 2 MiB for the certificate and evidence. These reserves keep envelopes within the PDF worker's memory and processing budget without rendering a trial final PDF.
A send over a limit returns 422 in the standard error shape, with error.code: "envelope_too_large" and error.param: "document". Its message says which size exceeds which limit. Reduce the PDF size, remove documents or pages, or remove attachment fields, then send again. The web editor and MCP report the same message. With send: true on a create request, the refusal shows as the envelope's send_error and an envelope.send_failed event instead. Drafts created before a limit changed are checked when sent.
The limits are deployment configuration in config/esignstack.php; they are shared with the existing upload, page-builder and API document validation. Uploads remain limited to 25 MiB per file and 46 MiB per packet. Attachment reserves and timestamp sealing can make the send limit lower than the upload limit.