# 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](#create-from-templates) or [from a file](#create-a-draft-from-a-file). Templates themselves can be created, changed and deleted through `/templates`; see the [API reference](/docs/api). A new envelope is answered at once with `preparation_status: "preparing"`, and its documents and fields are built in the background; see [Preparation](#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](/docs/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](/docs/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](#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](/docs/mcp#uploading-a-local-file).

```bash
curl -X POST https://esignstack.app/api/v1/files \
  -H "Authorization: Bearer $ESIGNSTACK_KEY" \
  -H "Idempotency-Key: order-456-file" \
  -F file=@agreement.pdf
```

Files 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:

```json
{
  "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 `422` that 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 `signer` in one and a `viewer` in another is refused (`422`, `param` `templates.1`); rename one of them.
- **Values.** `values` fill 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_order` sets 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 use `signing_order` (`parallel` or `sequential`).
- **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.
- `send` defaults to `false`: the envelope stays a draft until `POST /envelopes/{envelope}/send`. With `send: true` the whole envelope is sent once it is prepared, and counts as one envelope toward your plan's [API envelope limit](/docs/api-authentication#api-envelope-limits). Wait for `envelope.sent` before you open signing sessions; see [Preparation](#preparation).
- The envelope's recipients are added when it is prepared, so the `201` response 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](#recipients) endpoints take, so `auth_method`, `host_email`, `embedded`, `allow_delegation`, `receive_completed_pdf` and `metadata` work here too. A recipient's `type` comes from its roles: leave it out, or send the same type (a different one is refused). `role` comes from the roles too, and `documents` can't be set until the envelope exists.
- **Copies.** Someone not on the templates who only gets the completed documents is `{ "email": "…", "type": "cc" }`, without `roles`.
- 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:

```json
{
  "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`, with `param` such as `recipients.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.** `signer1` goes to the first entry in `recipients`, `signer2` to the second, and so on, counting every entry, including approvers and copies. A tag for a `cc` entry stays unassigned.
- `signing_order` (`parallel` or `sequential`) sets the signing steps from the list order; a recipient's `routing_order` wins.
- `send: true` sends 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 with `send_error` and `envelope.send_failed` fires; see [Preparation](#preparation).
- Recipients can also be left out and added later, with the [recipients](#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.

- `reminders` sets 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) and `skip_weekends`. Keys you leave out, or set to `null`, use the workspace's defaults. Every envelope shows the settings it uses under `reminders`.
- `message_template` (a `msgt_…` ID from [email templates](#email-templates-message-templates)) fills the invitation subject and note; an `email_subject` (≤255) or `email_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, and `null` means 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. On `PATCH`, 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 a `422` naming the field. The note is quoted under the standard lines as a message from the sender. Envelopes show `email_subject`, `email_message` and `message_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](/docs/embed-integration).

## 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:

```json
{
  "id": "env_01J…",
  "object": "envelope",
  "status": "draft",
  "preparation_status": "preparing",
  "preparation_error": null,
  "send_error": null,
  "…": "…"
}
```

- `preparation_status` is `preparing`, then `ready` (`envelope.prepared`) or `failed` (`envelope.preparation_failed`).
- `preparation_error` is `{code, message, param}` or `null`. Its `code` is `pdf_password_required` for a protected file, `preparation_stuck` when 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, answers `409 envelope_preparing` with `param: envelope` and `Retry-After: 2`. Once it has failed, the same requests answer `409 envelope_preparation_failed`.
- `POST /envelopes/{envelope}/retry_preparation` (ability `envelopes:write`) starts it again after you fix the cause, and answers `200` with the envelope, `preparing` again. A ready envelope is returned unchanged; one still preparing is `409 resource_conflict`.
- Input that can be checked at once, such as an unknown role or `values` label, a missing plan feature or an invalid recipient, is still refused with `422`, `409` or `403`, and nothing is created. Create requests don't answer `503` when 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](/docs/api-authentication#api-envelope-limits), 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:

1. `POST /files`. Waiting for `file.ready` isn't needed for `POST /envelopes`, only for `POST /templates` and `PUT …/documents`.
2. `POST /envelopes` with `file` and `recipients`.
3. Wait for `envelope.prepared`, or `GET /envelopes/{envelope}` until `preparation_status` is `ready`.
4. Add fields with `POST /envelopes/{envelope}/fields`.
5. `POST /envelopes/{envelope}/send`.

Send in one call:

1. `POST /envelopes` with `templates`, `recipients` and `send: true`.
2. Wait for `envelope.sent`, or `GET` until `status` is `sent`. On `envelope.send_failed`, read `send_error`.
3. Create [signing sessions](/docs/embed-integration) 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):

```json
{
  "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](#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:

- `name` and `email`. A new recipient needs both; a `cc` may go without a name, and an `in_person_signer` without an email (it's only for their copy).
- `type`: one of the above, or `in_person_signer` (see [Signing in person](/docs/sign-in-person)). Defaults to `signer`.
- `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 as `Client`.
- `private_message`: an optional plain-text note for this recipient, up to 5,000 characters, with the same variables as `email_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 send `null` to 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 in `access_code`), `sms` (with `auth_phone` in E.164 format) or `email_otp`. Any method other than `none` needs the Pro or Platform plan, and `sms` needs a live key. Leave `auth_method` out 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](#reassigning).
- `embedded`: see [Signing in your app](#signing-in-your-app).
- `host_email`: an `in_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; `null` for all of them. Not when creating an envelope, since its documents don't have IDs yet.
- `roles`: only with `templates`; see [Create from templates](#create-from-templates).
- `id`: only in `PUT …/recipients`.

### Replacing the list

`PUT /envelopes/{envelope}/recipients` takes the whole list, in order, and optional `signing_order`:

```json
{
  "recipients": [
    { "id": "rcp_01J…pat", "email": "pat.example@example.com" },
    { "name": "Sam Witness", "email": "sam@example.com", "type": "approver" }
  ]
}
```

- An entry with `id` updates that recipient. What it leaves out stays as it is, including its fields.
- An entry without `id` is 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 …/recipients` returns 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](/docs/embed-integration), 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](/docs/notifications), 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](#corrections) before that recipient acts. Leaving it out of an update keeps the current value.
- `cc` and `in_person_signer` recipients can't be embedded (`422`).
- In `POST /envelopes`, set `embedded` on an entry in `recipients`.

## 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.

```json
{
  "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](/docs/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:

```json
{
  "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_digest` as the `param`. 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](/docs/embed-integration#listen-for-messages) 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](#preparation). A live send counts toward your plan's [API envelope limit](/docs/api-authentication#api-envelope-limits).

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](#preparation) 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](#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:

```json
{ "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](#create-a-draft-from-a-file) instead. To find envelopes, see [Find envelopes](#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`.

```bash
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`](#create-a-draft-from-a-file).

## 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, by `id`. 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.
- `note` and `expected_revision`, which refuses the change with `409 resource_conflict` (`param: expected_revision`) if the envelope changed since you read it (the envelope's `revision`).
- `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 the `consent_disclosure_version` the signer agreed to (`null` on other entries). `GET /consent_disclosures/{version}` returns its wording.
- Whether signers must agree is the workspace setting `require_esign_consent`, changed with `PATCH /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. With `false`, 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](/docs/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.
