---
title: "Create an envelope"
description: "Create a new envelope with documents and recipients to start the signing process"
canonical: "https://signatureapi.com/docs/api/resources/envelopes/create"
source: "https://signatureapi.com/docs/api/resources/envelopes/create.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T15:56:55Z"
---

# Create an envelope

Create a new envelope with documents and recipients to start the signing process

_Last verified against API version 1.18.0._

Creates an [envelope](https://signatureapi.com/docs/api/resources/envelopes/object) and starts the signing process. The envelope begins in `processing` status while documents are validated and recipients are queued for notification. It transitions to `in_progress` once recipients are notified.

At minimum, provide a `title`, at least one `document`, and at least one `recipient`. All other properties are optional.

## Body parameters

### Required

#### `title` (string, required)

The title of the envelope, displayed to recipients in emails and the signing ceremony. Must be between 1 and 500 characters.

For an internal label that is not shown to recipients, use the `label` property instead.

#### `documents` (array of documents, required)

The documents included in the envelope. An envelope can contain between 1 and 10 documents. Each document must be a publicly accessible PDF or DOCX file. Documents can include interactive places such as signature fields, text inputs, and checkboxes that recipients interact with during the signing ceremony. DOCX documents also support dynamic content via template data.

**PDF Document**

#### `key` (string)

A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API.

Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters.

If not provided, a key is generated automatically.

#### `title` (string)

An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters.

#### `url` (string, required)

The URL where the document or template file is located. The file must be publicly accessible.

You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the [Create Upload](https://signatureapi.com/docs/api/resources/uploads/create) endpoint.

Learn more about your options in [Document URL and Upload](https://signatureapi.com/docs/api/resources/documents/url).

#### `format` (enum, required)

The file format of the document. Determines which features are available.

- `pdf`: Standard PDF file. Supports places via placeholders or fixed positions.
- `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places.

  For PDF documents the format must be `pdf`.

#### `fixed_positions` (array of fixed positions)

**fixed position**

#### `place_key` (string, required)

The key of the place to position. Must match one of the `key` values in the document's `places` array.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `page` (number, required)

The page number where the place is positioned. Page numbering starts at 1.

#### `top` (number, required)

The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge.

#### `left` (number, required)

The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge.

#### `places` (array of places)

Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date).

Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array.

Learn more about [places](https://signatureapi.com/docs/api/resources/places/object).

**signature place**

A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document.

#### `type` (enum, required)

Specifies the type of place.

For a signature place, the value must be `signature`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `height` (number)

The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height.

Must be between 20 and 60. Defaults to 60.

**initials place**

A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document.

#### `type` (enum, required)

Specifies the type of place.

For an initials place, the value must be `initials`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `height` (number)

The height of the initials place in points. The width equals the height.

Must be between 20 and 60. Defaults to 60.

**text place**

A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins.

#### `type` (enum, required)

Specifies the type of place.

For a text place, the value must be `text`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `value` (string, required)

The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient.

Maximum length is 1000 characters.

#### `font_size` (number)

The font size in points.

Must be between 1 and 144. The default is 12.

#### `font_color` (string)

The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black).

**text input place**

A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a text input place, the value must be `text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill this field to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `format` (enum or regex)

Defines the validation format for the user’s input.

Accepted values:

- `email`
- `zipcode-us`
- a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/`

Learn more in [Format Validation](https://signatureapi.com/docs/api/resources/places/text-input#format-validation).

#### `format_message` (string)

The message displayed when the user’s input does not match the required format.

Learn more in [Format Validation -> Adding a Custom Message](https://signatureapi.com/docs/api/resources/places/text-input#format-messages).

#### `width` (number)

The initial width of the text input field in points. The field may expand beyond this width during typing.

Must be between 30 and 540. Defaults to 30.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. Defaults to 12.

**boxed text input place**

A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a boxed text input place, the value must be `boxed_text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `box_count` (number)

The number of individual character boxes to display.

Must be between 1 and 100. Each box accepts a single character from the recipient.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the boxed text input field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/boxed-text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the first box during the signing ceremony to guide the recipient.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/boxed-text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill all boxes to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `width` (number, required)

The total width of the boxed input field in points.

Must be between 30 and 540. The default is 30.

#### `height` (number, required)

The height of each individual box in points.

#### `font_size` (number, required)

The font size in points.

Must be between 6 and 12. The default is 12.

**multiline text input place**

A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a multi-line text input place, the value must be `multiline_text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/multiline-text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/multiline-text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill this field to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `width` (number, required)

The width of the multi-line text input place in points.

Must be between 30 and 540. The default is 30.

#### `line_count` (integer, required)

The number of lines for the multi-line text input field.

Must be between 1 and 100.

#### `line_height` (number)

The line height in points. Must be greater than or equal to `font_size`.

Must be between 6 and 72. The default is 12.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. The default is 12.

**checkbox place**

A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a checkbox place, the value must be `checkbox`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `symbol` (enum)

The symbol to display in the checkbox when it is checked.

Available options are `check` and `xmark`. The default is `check`.

#### `requirement` (enum)

Specifies whether the recipient must check this box to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `optional`.

#### `height` (number)

The height of the checkbox in points. The width equals the height.

Must be between 8 and 40. Defaults to 20.

**dropdown place**

A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a dropdown place, the value must be `dropdown`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `options` (array or enum, required)

Specifies the list of options available in the dropdown.

You can provide either **custom options** or a **predefined option set**.

**Custom options**: An array of objects, each with a `label` (displayed to the user) and an optional `value` (captured when selected). If `value` is omitted, the `label` is used as the value.

```json
"options": [
  { "label": "Option A", "value": "a" },
  { "label": "Option B", "value": "b" }
]
```

**Predefined options**: A string specifying a built-in option set:

ValueDescription

world\_countries\_namesCountry names (e.g., "United States", "Canada") world\_countries\_2\_letter\_codesISO 3166-1 alpha-2 codes (e.g., "US", "CA") world\_countries\_3\_letter\_codesISO 3166-1 alpha-3 codes (e.g., "USA", "CAN") world\_countries\_numeric\_codesISO 3166-1 numeric codes (e.g., "840", "124") us\_states\_namesUS state names (e.g., "California", "Texas") us\_states\_2\_letter\_codesUS state codes (e.g., "CA", "TX")

#### `default` (string)

Specifies the option that is pre-selected when the dropdown is displayed.

The value is first matched against the `label` of each option. If no match is found, it is matched against the `value` of each option. If no match is found, a validation error is returned.

#### `behavior` (enum)

Specifies the behavior of the dropdown during the signing ceremony.

Possible values:

- `auto` (default): Automatically selects the best behavior based on the number of options. Uses `select` for 10 or fewer options, and `combobox` for more than 10 options.
- `select`: Displays a standard dropdown list. Best for short lists where users can quickly scan all options.
- `combobox`: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection.

#### `requirement` (enum)

Specifies whether the recipient must select an option to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `prompt` (string)

A placeholder message shown inside the dropdown field during the signing ceremony.

Maximum length is 100 characters.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/dropdown#hints-and-prompts).

#### `hint` (string)

A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony.

Maximum length is 100 characters.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/dropdown#hints-and-prompts).

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. The default is 12.

#### `width` (number)

The width of the dropdown field in points.

Must be between 30 and 540. The default is 30.

**recipient completed date place**

Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_completed_date`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `date_format` (string)

The date and time format using [Moment.js syntax](https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025).

Defaults to `D MMM YYYY`.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**envelope completed date place**

Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `envelope_completed_date`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `date_format` (string)

The date and time format using [Moment.js syntax](https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025).

Defaults to `D MMM YYYY`.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**recipient name place**

Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_name`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**recipient email place**

Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_email`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**DOCX Document**

#### `key` (string)

A user-provided identifier for this document within the envelope. Must be unique within the envelope. Use the key to reference this document in other parts of the API.

Only lowercase letters, numbers, and underscores are allowed. Must start with a letter. Maximum 32 characters.

If not provided, a key is generated automatically.

#### `title` (string)

An optional display name for the document. When set, the title is shown to recipients during the signing ceremony and in deliverables. Defaults to `null` if not provided. Maximum 500 characters.

#### `url` (string, required)

The URL where the document or template file is located. The file must be publicly accessible.

You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also use the URL returned by the [Create Upload](https://signatureapi.com/docs/api/resources/uploads/create) endpoint.

Learn more about your options in [Document URL and Upload](https://signatureapi.com/docs/api/resources/documents/url).

#### `format` (enum, required)

The file format of the document. Determines which features are available.

- `pdf`: Standard PDF file. Supports places via placeholders or fixed positions.
- `docx`: Microsoft Word file. Supports template fields for dynamic content in addition to places.

  For DOCX documents the format must be `docx`.

#### `data` (object)

Template data used to fill dynamic fields in a DOCX template. Each key corresponds to a `{{key}}` placeholder in the template file.

Keys must be alphanumeric and at most 32 characters. Values can be strings, booleans, or nested objects. Nested keys map to dot-notation placeholders (for example, a key `person` with nested key `name` fills `{{person.name}}`). Defaults to `{}`.

#### `fixed_positions` (array of fixed positions)

**fixed position**

#### `place_key` (string, required)

The key of the place to position. Must match one of the `key` values in the document's `places` array.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `page` (number, required)

The page number where the place is positioned. Page numbering starts at 1.

#### `top` (number, required)

The vertical distance from the top edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `360` places the field 5 inches from the top edge.

#### `left` (number, required)

The horizontal distance from the left edge of the page to the bottom-left corner of the place, measured in points (1 point = 1/72 of an inch). For example, `72` places the field 1 inch from the left edge.

#### `places` (array of places)

Areas within a document where a recipient provides input (such as a signature or text) or where a value is displayed automatically (such as a completion date).

Each place has a `type` that determines its behavior. A place must be positioned using either a `[[place_key]]` placeholder in the document text or an entry in the `fixed_positions` array.

Learn more about [places](https://signatureapi.com/docs/api/resources/places/object).

**signature place**

A location where the recipient, identified by `recipient_key`, draws or types their signature. A single recipient can have multiple signature places across different pages of a document.

#### `type` (enum, required)

Specifies the type of place.

For a signature place, the value must be `signature`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `height` (number)

The height of the signature place in points. The width is calculated automatically using a 5:2 ratio based on this height.

Must be between 20 and 60. Defaults to 60.

**initials place**

A location where the recipient, identified by `recipient_key`, enters their initials. A single recipient can have multiple initials places across different pages of a document.

#### `type` (enum, required)

Specifies the type of place.

For an initials place, the value must be `initials`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `height` (number)

The height of the initials place in points. The width equals the height.

Must be between 20 and 60. Defaults to 60.

**text place**

A read-only text value displayed at a specific location on the document. It is not interactive and does not require a recipient. Use this to pre-fill static information such as company names, reference numbers, or dates before the signing process begins.

#### `type` (enum, required)

Specifies the type of place.

For a text place, the value must be `text`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `value` (string, required)

The text content to display on the document. This is a static value set when the envelope is created and cannot be changed by the recipient.

Maximum length is 1000 characters.

#### `font_size` (number)

The font size in points.

Must be between 1 and 144. The default is 12.

#### `font_color` (string)

The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black).

**text input place**

A location where the recipient, identified by `recipient_key`, types free-form text. Supports input validation, placeholder text, and tooltip hints. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a text input place, the value must be `text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill this field to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `format` (enum or regex)

Defines the validation format for the user’s input.

Accepted values:

- `email`
- `zipcode-us`
- a custom regular expression, enclosed in `/`, for example: `/^[a-z0-9]{1,10}$/`

Learn more in [Format Validation](https://signatureapi.com/docs/api/resources/places/text-input#format-validation).

#### `format_message` (string)

The message displayed when the user’s input does not match the required format.

Learn more in [Format Validation -> Adding a Custom Message](https://signatureapi.com/docs/api/resources/places/text-input#format-messages).

#### `width` (number)

The initial width of the text input field in points. The field may expand beyond this width during typing.

Must be between 30 and 540. Defaults to 30.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. Defaults to 12.

**boxed text input place**

A series of individual character boxes where the recipient, identified by `recipient_key`, enters text one character per box. Use this for structured data such as verification codes, ZIP codes, or the last four digits of an SSN. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a boxed text input place, the value must be `boxed_text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `box_count` (number)

The number of individual character boxes to display.

Must be between 1 and 100. Each box accepts a single character from the recipient.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the boxed text input field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/boxed-text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the first box during the signing ceremony to guide the recipient.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/boxed-text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill all boxes to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `width` (number, required)

The total width of the boxed input field in points.

Must be between 30 and 540. The default is 30.

#### `height` (number, required)

The height of each individual box in points.

#### `font_size` (number, required)

The font size in points.

Must be between 6 and 12. The default is 12.

**multiline text input place**

A location where the recipient, identified by `recipient_key`, enters text that spans multiple lines. Use this for comments, addresses, and longer descriptions. Use `capture_as` to store the entered value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a multi-line text input place, the value must be `multiline_text_input`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `hint` (string)

A tooltip message displayed over the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/multiline-text-input#hints-and-prompts).

#### `prompt` (string)

A placeholder message shown inside the input text field during the signing ceremony.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/multiline-text-input#hints-and-prompts).

#### `requirement` (enum)

Specifies whether the recipient must fill this field to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `width` (number, required)

The width of the multi-line text input place in points.

Must be between 30 and 540. The default is 30.

#### `line_count` (integer, required)

The number of lines for the multi-line text input field.

Must be between 1 and 100.

#### `line_height` (number)

The line height in points. Must be greater than or equal to `font_size`.

Must be between 6 and 72. The default is 12.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. The default is 12.

**checkbox place**

A location where the recipient, identified by `recipient_key`, checks or unchecks a box. Use `capture_as` to store the checkbox value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a checkbox place, the value must be `checkbox`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `symbol` (enum)

The symbol to display in the checkbox when it is checked.

Available options are `check` and `xmark`. The default is `check`.

#### `requirement` (enum)

Specifies whether the recipient must check this box to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `optional`.

#### `height` (number)

The height of the checkbox in points. The width equals the height.

Must be between 8 and 40. Defaults to 20.

**dropdown place**

A location where the recipient, identified by `recipient_key`, selects from a list of options. Options can be a custom list of label-value pairs or a predefined set such as country names or US state codes. Use `capture_as` to store the selected value in the envelope's captures.

#### `type` (enum, required)

Specifies the type of place.

For a dropdown place, the value must be `dropdown`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `options` (array or enum, required)

Specifies the list of options available in the dropdown.

You can provide either **custom options** or a **predefined option set**.

**Custom options**: An array of objects, each with a `label` (displayed to the user) and an optional `value` (captured when selected). If `value` is omitted, the `label` is used as the value.

```json
"options": [
  { "label": "Option A", "value": "a" },
  { "label": "Option B", "value": "b" }
]
```

**Predefined options**: A string specifying a built-in option set:

ValueDescription

world\_countries\_namesCountry names (e.g., "United States", "Canada") world\_countries\_2\_letter\_codesISO 3166-1 alpha-2 codes (e.g., "US", "CA") world\_countries\_3\_letter\_codesISO 3166-1 alpha-3 codes (e.g., "USA", "CAN") world\_countries\_numeric\_codesISO 3166-1 numeric codes (e.g., "840", "124") us\_states\_namesUS state names (e.g., "California", "Texas") us\_states\_2\_letter\_codesUS state codes (e.g., "CA", "TX")

#### `default` (string)

Specifies the option that is pre-selected when the dropdown is displayed.

The value is first matched against the `label` of each option. If no match is found, it is matched against the `value` of each option. If no match is found, a validation error is returned.

#### `behavior` (enum)

Specifies the behavior of the dropdown during the signing ceremony.

Possible values:

- `auto` (default): Automatically selects the best behavior based on the number of options. Uses `select` for 10 or fewer options, and `combobox` for more than 10 options.
- `select`: Displays a standard dropdown list. Best for short lists where users can quickly scan all options.
- `combobox`: Displays a searchable dropdown with type-ahead filtering. Best for long lists where users need to search for their selection.

#### `requirement` (enum)

Specifies whether the recipient must select an option to complete the signing ceremony.

Possible values are `required` or `optional`. The default is `required`.

#### `prompt` (string)

A placeholder message shown inside the dropdown field during the signing ceremony.

Maximum length is 100 characters.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/dropdown#hints-and-prompts).

#### `hint` (string)

A tooltip message displayed when the user hovers over or focuses on the dropdown field during the signing ceremony.

Maximum length is 100 characters.

Learn more in [Hints and Prompts](https://signatureapi.com/docs/api/resources/places/dropdown#hints-and-prompts).

#### `capture_as` (string)

A key that stores the recipient's input in the envelope's `captures` object. When set, the value entered or selected by the recipient is saved under this key after the envelope is completed.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters. Set to `null` to disable capture.

#### `font_size` (number)

The font size in points.

Must be between 6 and 12. The default is 12.

#### `width` (number)

The width of the dropdown field in points.

Must be between 30 and 540. The default is 30.

**recipient completed date place**

Displays the date and time when the recipient, identified by `recipient_key`, completed their action on the envelope. Use `date_format` to control how the date is formatted.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_completed_date`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `date_format` (string)

The date and time format using [Moment.js syntax](https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025).

Defaults to `D MMM YYYY`.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**envelope completed date place**

Displays the date and time when the envelope was completed. The envelope completes when all recipients have finished their actions. Use `date_format` to control how the date is formatted.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `envelope_completed_date`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `date_format` (string)

The date and time format using [Moment.js syntax](https://momentjs.com/docs/#/displaying/format/). Common formats include `D MMM YYYY` (31 Dec 2025), `YYYY-MM-DD` (2025-12-31), and `MM/DD/YYYY` (12/31/2025).

Defaults to `D MMM YYYY`.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**recipient name place**

Displays the name of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_name`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

**recipient email place**

Displays the email address of the recipient, identified by `recipient_key`, at a specific location on the document. The value is inserted automatically. This place is read-only and does not require any action from the recipient.

#### `type` (enum, required)

Specifies the type of place.

For this kind of place, the value must be `recipient_email`.

#### `key` (string, required)

A unique identifier for this place within the document. Use this key to match the place to its position, either through a `[[place_key]]` placeholder in the document or an entry in `fixed_positions`.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters.

#### `recipient_key` (string, required)

The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.

#### `font_size` (number)

The font size in points. Must be between 1 and 144. Defaults to 12.

#### `recipients` (array of recipients, required)

The recipients who participate in the envelope's signing process. An envelope can have between 1 and 10 recipients.

Five types are supported:

- `signer`: Signs the documents.
- `preparer`: Fills in fields before signers receive the documents.
- `approver`: Reviews and approves the documents without signing.
- `automatic_signer`: Has their signature applied automatically.
- `qualified_signer`: Signs with a qualified electronic signature (QES) through your own trust service provider. In public beta.

**Signer**

#### `type` (enum, required)

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

TypeDescription

signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic\_signerThe signature is applied automatically by the system. qualified\_signerSigns with a qualified electronic signature (QES) through your own trust service provider. In public beta. See [Qualified Signer](https://signatureapi.com/docs/api/resources/recipients/qualified-signer).

For signers, the type must be `signer`.

#### `key` (string, required)

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

#### `name` (string, required)

The full name of the recipient. Appears in invitation emails and is pre-filled for typed signatures.

#### `email` (string, required)

The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`.

#### `ceremony` (object)

Configuration for the first ceremony to create for the recipient.

If not provided, a ceremony with `email_link` authentication is created by default.

**Ceremony**

#### `authentication` (array of authentication object, required)

**Email Link Authentication**

With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email link authentication, set `type` to `email_link`.

#### `subject_override` (string)

A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the [envelope title](https://signatureapi.com/docs/api/resources/envelopes/object#title).

Maximum 500 characters.

#### `message_override` (string)

A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the [envelope message](https://signatureapi.com/docs/api/resources/envelopes/object#message).

Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters.

**Email Code Authentication**

With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email code authentication, set `type` to `email_code`.

**Custom Authentication**

With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For custom authentication, set `type` to `custom`.

#### `provider` (string, required)

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

#### `data` (object, required)

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

> **Warning:** The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.
>
> Review our [Terms & Conditions](https://signatureapi.com/docs/legal/terms/terms) for details.

#### `redirect_url` (string)

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `redirect_delay` (integer)

The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to `3`. Allowed range: `0` to `20`.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `url_variant` (enum)

The format of the ceremony URL.

Available options:

- `standard` (default): Full-length URL. Works for most use cases.
- `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

#### `embeddable_in` (array of strings)

Origins allowed to embed this ceremony in an iframe.

These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the [frame-ancestors documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources).

Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`.

> **Note:** Only the origin (scheme and host) is used. Paths are ignored.

#### `delivery_type` (enum)

Controls whether the completed deliverable is automatically emailed to this recipient.

ValueDescription

emailThe completed deliverable is delivered to this recipient by email. This is the default for signers. noneThe completed deliverable is not emailed. Your application is responsible for distributing the deliverable.

#### `signature_options` (array of enum)

The signature methods available to the signer. The first item in the array is shown as the default.

OptionDescription

typedThe signer types their name. It is pre-filled from the recipient's name property. drawnThe signer draws their signature using a mouse, stylus, or touchscreen.

If not specified, both `typed` and `drawn` are available, with `typed` shown first.

**Deprecated Fields**

#### `ceremony_creation` (enum, deprecated)

How the ceremony is created for the recipient.

Available options are `automatic` and `manual`. The default is `automatic`.

> **Note:** This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility.

**Preparer**

#### `type` (enum, required)

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

TypeDescription

signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic\_signerThe signature is applied automatically by the system. qualified\_signerSigns with a qualified electronic signature (QES) through your own trust service provider. In public beta. See [Qualified Signer](https://signatureapi.com/docs/api/resources/recipients/qualified-signer).

For preparers, the type must be `preparer`.

#### `key` (string, required)

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

#### `name` (string, required)

The full name of the recipient. Appears in invitation emails.

#### `email` (string, required)

The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`.

#### `ceremony` (object)

Configuration for the first ceremony to create for the recipient.

If not provided, a ceremony with `email_link` authentication is created by default.

**Ceremony**

#### `authentication` (array of authentication object, required)

**Email Link Authentication**

With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email link authentication, set `type` to `email_link`.

#### `subject_override` (string)

A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the [envelope title](https://signatureapi.com/docs/api/resources/envelopes/object#title).

Maximum 500 characters.

#### `message_override` (string)

A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the [envelope message](https://signatureapi.com/docs/api/resources/envelopes/object#message).

Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters.

**Email Code Authentication**

With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email code authentication, set `type` to `email_code`.

**Custom Authentication**

With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For custom authentication, set `type` to `custom`.

#### `provider` (string, required)

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

#### `data` (object, required)

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

> **Warning:** The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.
>
> Review our [Terms & Conditions](https://signatureapi.com/docs/legal/terms/terms) for details.

#### `redirect_url` (string)

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `redirect_delay` (integer)

The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to `3`. Allowed range: `0` to `20`.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `url_variant` (enum)

The format of the ceremony URL.

Available options:

- `standard` (default): Full-length URL. Works for most use cases.
- `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

#### `embeddable_in` (array of strings)

Origins allowed to embed this ceremony in an iframe.

These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the [frame-ancestors documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources).

Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`.

> **Note:** Only the origin (scheme and host) is used. Paths are ignored.

#### `delivery_type` (enum)

Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished.

ValueDescription

emailThe completed deliverable is delivered to this recipient by email. noneNo emails are sent. Your application is responsible for distributing the ceremony URL and the completed deliverable. This is the default for preparers.

**Deprecated Fields**

#### `ceremony_creation` (enum, deprecated)

How the ceremony is created for the recipient.

Available options are `automatic` and `manual`. The default is `automatic`.

> **Note:** This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility.

**Approver**

#### `type` (enum, required)

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

TypeDescription

signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic\_signerThe signature is applied automatically by the system. qualified\_signerSigns with a qualified electronic signature (QES) through your own trust service provider. In public beta. See [Qualified Signer](https://signatureapi.com/docs/api/resources/recipients/qualified-signer).

For approvers, the type must be `approver`.

#### `key` (string, required)

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

#### `name` (string, required)

The full name of the recipient. Appears in invitation emails.

#### `email` (string, required)

The email address of the recipient. SignatureAPI emails the ceremony link to this address when the ceremony uses `email_link` authentication, and the completed deliverable when `delivery_type` is `email`.

#### `ceremony` (object)

Configuration for the first ceremony to create for the recipient.

If not provided, a ceremony with `email_link` authentication is created by default.

**Ceremony**

#### `authentication` (array of authentication object, required)

**Email Link Authentication**

With **email link authentication**, the recipient receives an email with a direct link to the ceremony. Clicking the link authenticates the recipient and opens the signing session.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email link authentication, set `type` to `email_link`.

#### `subject_override` (string)

A custom subject line for the invitation email sent to this recipient. When not set, the subject defaults to the [envelope title](https://signatureapi.com/docs/api/resources/envelopes/object#title).

Maximum 500 characters.

#### `message_override` (string)

A custom message body for the invitation email sent to this recipient. When not set, the message defaults to the [envelope message](https://signatureapi.com/docs/api/resources/envelopes/object#message).

Supports Markdown formatting: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 2000 characters.

**Email Code Authentication**

With **email code authentication**, the recipient receives an email from SignatureAPI containing a 9-digit code. The recipient must enter this code to authenticate and access the ceremony.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For email code authentication, set `type` to `email_code`.

**Custom Authentication**

With **custom authentication**, your application authenticates the recipient. SignatureAPI provides a ceremony URL that you share or embed in your application to give the recipient access.

#### `type` (enum, required)

The type of authentication. Available values: `email_link`, `email_code`, and `custom`.

For custom authentication, set `type` to `custom`.

#### `provider` (string, required)

The name of your company or application that authenticated the recipient. This value appears in the envelope audit log as the authentication provider.

#### `data` (object, required)

Key-value pairs with metadata about the authentication event, such as timestamps, session IDs, and user identifiers. These values appear in the envelope audit log.

> **Warning:** The values in `data` must be sufficient to verify how the recipient was authenticated. You must retain all records needed to prove the recipient's authentication, such as session information. In cases such as legal proceedings, you may need to provide these records to confirm identity.
>
> Review our [Terms & Conditions](https://signatureapi.com/docs/legal/terms/terms) for details.

#### `redirect_url` (string)

An HTTPS URL to redirect the recipient to after the ceremony finishes.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `redirect_delay` (integer)

The delay in seconds before the ceremony redirects to `redirect_url` (standalone ceremonies) or emits completion events (embedded ceremonies).

Defaults to `3`. Allowed range: `0` to `20`.

Learn more in [Redirect URL](https://signatureapi.com/docs/api/resources/ceremonies/redirect-url).

#### `url_variant` (enum)

The format of the ceremony URL.

Available options:

- `standard` (default): Full-length URL. Works for most use cases.
- `short`: Shortened URL. Use this when sharing through space-constrained channels such as SMS or push notifications.

#### `embeddable_in` (array of strings)

Origins allowed to embed this ceremony in an iframe.

These values set the `frame-ancestors` directive in the ceremony's Content Security Policy (CSP) header. Sources typically take the form of a scheme and host (for example, `https://app.example.com`). Wildcards are supported (for example, `https://*.example.com`). For all available options, see the [frame-ancestors documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors#sources).

Defaults to an empty list (`[]`), which means embedding is not allowed. To allow embedding from all origins (not recommended for production), use `["*"]`.

> **Note:** Only the origin (scheme and host) is used. Paths are ignored.

#### `delivery_type` (enum)

Controls whether SignatureAPI emails the completed deliverable to the recipient once the envelope is finished.

ValueDescription

emailThe completed deliverable is delivered to this recipient by email. noneNo emails are sent. Your application is responsible for distributing the ceremony URL and the completed deliverable. This is the default for approvers.

**Deprecated Fields**

#### `ceremony_creation` (enum, deprecated)

How the ceremony is created for the recipient.

Available options are `automatic` and `manual`. The default is `automatic`.

> **Note:** This property is deprecated. Use the `ceremony` object on the recipient when creating an envelope to control ceremony creation. This property will continue to be supported for backwards compatibility.

**Automatic Signer**

#### `type` (enum, required)

The type of the recipient. Determines what actions the recipient can perform during the ceremony.

TypeDescription

signerSigns documents. Every envelope must have at least one signing recipient. approverReviews and approves documents without signing. preparerFills in document fields on behalf of another party. automatic\_signerThe signature is applied automatically by the system. qualified\_signerSigns with a qualified electronic signature (QES) through your own trust service provider. In public beta. See [Qualified Signer](https://signatureapi.com/docs/api/resources/recipients/qualified-signer).

For automatic signers, the type must be `automatic_signer`.

#### `key` (string, required)

A unique identifier you assign to each recipient in the envelope.

Use it to match recipients with the places they should interact with (such as signature fields) and to identify them in events and webhook notifications.

The key must start with a lowercase letter. It can contain lowercase letters, numbers, and underscores. Maximum 32 characters. It must be unique within the envelope.

#### `name` (string, required)

The full name of the signer. Appears in the audit log line that records the automatic signature.

#### `mandate` (string, required)

A short statement explaining why the initiator is authorized to sign on behalf of this person. This string is shown as-is in the audit log.

Maximum 500 characters. Cannot be empty.

#### `signature` (object)

The signature image to apply to the document. Required when the recipient is assigned any place of type `signature`.

**Preset symbol**

#### `type` (string, required)

The symbol type. Currently only `drawn` is supported.

#### `url` (string, required)

The URL of a PNG upload owned by your account. Both temporary uploads (from `POST /v1/uploads`) and permanent uploads stored via the Dashboard or `POST /v1/uploads/{id}/store` are accepted. The upload must not be expired.

#### `initials` (object)

The initials image to apply to the document. Required when the recipient is assigned any place of type `initials`. Same shape as `signature`.

> **Note:** Automatic signers do not accept `email`, `ceremony`, `delivery_type`, or `signature_options`. They do not receive invitations or access a ceremony.

### Signing options

#### `routing` (enum)

Controls the order in which recipients receive and act on the envelope.

- `sequential`: Recipients act one at a time, in the order listed. Each recipient must complete before the next is notified. This is the default.
- `parallel`: All recipients are notified at the same time and can act in any order.

Learn more about [recipient routing](https://signatureapi.com/docs/api/resources/envelopes/routing).

#### `deliverable` (deliverable object)

Configuration for the deliverable generated when the envelope is completed. The deliverable is sent to all recipients via email. To prevent automatic delivery to a recipient, set that recipient's `delivery_type` to `none`.

If omitted, a `standard` deliverable is generated automatically.

**Standard Deliverable**

> **Tip:** The standard deliverable includes an audit log. To get signed documents without an audit log, use the [simple deliverable](https://signatureapi.com/docs/api/resources/deliverables/simple) instead.

#### `name` (string)

A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters.

#### `type` (enum, required)

The type of the deliverable.

- `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default.
- `simple`: Includes the signed documents only, without an audit log.

  For standard deliverables, the type is `standard`.

#### `language` (enum)

The language for system-generated text in the audit log, including labels and the certificate of completion. Does not affect the content of the signed documents.

Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian), `nl` (Dutch).

Defaults to the envelope language.

#### `timezone` (string)

The timezone used for timestamps in the audit log. Must be a valid IANA Time Zone Database identifier (e.g., `America/New_York`, `Europe/London`). Does not affect timestamps inside the signed documents.

Defaults to the envelope timezone.

#### `timestamp_format` (string)

The format for timestamps in the audit log. Uses MomentJS format tokens (e.g., `MM/DD/YYYY HH:mm:ss`). Does not affect timestamps inside the signed documents.

Defaults to the envelope timestamp format.

#### `included_documents` (array of strings)

The keys of the documents to include in the deliverable. By default, all documents in the envelope are included.

Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys.

#### `password` (string)

The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file.

Password requirements:

- Between 4 and 32 characters
- Letters and numbers only (no special characters or spaces)

When returned in API responses, the password value is masked for security (displayed as `********`).

> **Note:** Password protection is available upon request. [Contact support](https://signatureapi.com/support) to enable this feature.

**Simple Deliverable**

> **Tip:** The simple deliverable does not include an audit log. To get signed documents with an audit log, use the [standard deliverable](https://signatureapi.com/docs/api/resources/deliverables/standard) instead.

#### `name` (string)

A user-provided name for this deliverable. Use this to identify deliverables when an envelope has more than one.

Must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Between 1 and 32 characters.

#### `type` (enum, required)

The type of the deliverable.

- `standard`: Includes the signed documents and an audit log with a certificate of completion. This is the default.
- `simple`: Includes the signed documents only, without an audit log.

  For simple deliverables, the type is `simple`.

#### `included_documents` (array of strings)

The keys of the documents to include in the deliverable. By default, all documents in the envelope are included.

Use this to create a deliverable with only a subset of documents. For example, generate separate deliverables for different recipients. Accepts between 1 and 10 document keys.

#### `password` (string)

The password used to encrypt the deliverable. Recipients must enter this password to access the downloaded file.

Password requirements:

- Between 4 and 32 characters
- Letters and numbers only (no special characters or spaces)

When returned in API responses, the password value is masked for security (displayed as `********`).

> **Note:** Password protection is available upon request. [Contact support](https://signatureapi.com/support) to enable this feature.

#### `attestation` (enum)

The regulatory attestation applied to the envelope. Use this to meet country-specific e-signature requirements.

- `none`: No attestation. This is the default and covers most countries, including the US and EU member states.
- `mx_nom151`: Mexico NOM-151 compliance. Attaches a preservation certificate to the deliverable.
- `br_icp_brasil`: Brazil ICP-Brasil trusted timestamp. Embeds a timestamp in the deliverable.

For more information, see [Attestation](https://signatureapi.com/docs/api/resources/envelopes/attestation).

### Recipient experience

#### `message` (string)

A custom message included in the signing request emails sent to recipients. Use it to provide context about what is being signed.

Supports up to 2,000 characters. Accepts a subset of Markdown:

- `**bold**` for bold text
- `*italic*` for italic text
- `\n\n` for paragraph breaks

Defaults to `null`.

#### `language` (string)

The language used for the signing ceremony, recipient emails, and the audit log in deliverables.

Supported values: `en` (English), `es` (Spanish), `fr` (French), `it` (Italian), `pt` (Portuguese), `de` (German), `zh` (Chinese Simplified), `hu` (Hungarian), `nl` (Dutch).

If not specified, the account's default language is used.

Learn more about [language](https://signatureapi.com/docs/api/resources/envelopes/language).

#### `timezone` (string)

The time zone applied to timestamps in the deliverable's audit log. Must be a valid IANA Time Zone Database identifier (for example, `America/New_York` or `Europe/London`).

If not specified, the account's default time zone is used.

Learn more about [time zones](https://signatureapi.com/docs/api/resources/envelopes/timezone).

#### `timestamp_format` (string)

The date and time format used for timestamps in the deliverable's audit log. Uses MomentJS format tokens (for example, `MM/DD/YYYY HH:mm:ss`).

If not specified, the account's default timestamp format is used.

Learn more about [timestamp formats](https://signatureapi.com/docs/api/resources/envelopes/timestamp-format).

#### `sender` (object)

The sender of the envelope. Sender information appears in emails sent to recipients, identifying who initiated the signing request. If omitted, the account's default sender name and email are used.

**Sender**

#### `name` (string)

The name of the sender, displayed to recipients in emails and the signing ceremony. Maximum 500 characters.

#### `email` (string)

The email address of the sender, shown to recipients for reference. Maximum 320 characters.

#### `organization` (string)

The organization name of the sender, displayed to recipients alongside the sender's name and email. Defaults to `null`. Maximum 500 characters.

#### `branding` (object)

Customizes the visual appearance of the signing ceremony and recipient emails. Branding does not affect internal notifications or signed documents.

Learn more about [branding](https://signatureapi.com/docs/api/resources/envelopes/branding).

**Branding**

#### `logo` (URL)

The URL of the logo image displayed in the header of emails and the signing ceremony. Must be a PNG file uploaded to the Library. Defaults to `null`.

Only files uploaded to your account's Library are accepted. Direct external URLs are not supported.

#### `accent_color` (string)

The accent color applied to buttons in emails and the signing ceremony. Specified as a hex color code (for example, `#2463eb`). Defaults to `#2463eb`.

The color must have a contrast ratio of at least 4.5:1 against white, following [WCAG guidelines](https://www.w3.org/TR/WCAG21/). If the color does not meet this requirement, the API returns an error with a suggested compliant alternative.

#### `email` (object)

Additional customization for emails sent to recipients, including footer text and logo alignment.

**Email options**

#### `footer` (string)

A custom footer included at the bottom of all recipient emails for this envelope, after SignatureAPI's standard footer content. Use it for disclaimers, privacy notices, or contact information. Defaults to `null`.

Supports a subset of Markdown: `**bold**`, `*italic*`, and `\n\n` for paragraph breaks. Maximum 10,000 characters.

#### `logo_position` (enum)

The horizontal alignment of the logo in recipient emails. Accepted values are `left`, `center`, and `right`. Defaults to `left`.

### Organization

#### `label` (string)

A custom label for internal identification. Labels are not shown to recipients. Unlike `title`, which recipients see, the label is for your team's use only. It can be updated at any time via the Update Envelope endpoint.

Maximum 500 characters. Defaults to `null`.

#### `topics` (array of strings)

An array of up to 10 tags used to classify the envelope and filter webhook notifications. Each topic must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. Maximum 32 characters per topic.

Learn more about [topics](https://signatureapi.com/docs/api/resources/envelopes/topics).

#### `metadata` (object)

A set of up to 10 custom key-value pairs for attaching internal reference data to the envelope. Use metadata to link envelopes to records in your own systems.

Keys: up to 32 characters (letters, digits, and underscores). Values: up to 1,000 characters. Do not store sensitive information as metadata.

Learn more about [metadata](https://signatureapi.com/docs/api/resources/envelopes/metadata).

## Returns

Returns a `201 Created` status code along with [an envelope object](https://signatureapi.com/docs/api/resources/envelopes/object) on success, or an [error](https://signatureapi.com/docs/api/errors) otherwise.

### Example: Minimal

A PDF with two signers.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement",
  "message": "Please review the agreement and provide your signature.",
  "routing": "parallel",
  "documents": [
    {
      "key": "service_agreement",
      "title": "Service Agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
      "format": "pdf",
      "places": [
        {
          "key": "client_signs_here",
          "type": "signature",
          "recipient_key": "client"
        },
        {
          "key": "provider_signs_here",
          "type": "signature",
          "recipient_key": "provider"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "client",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    },
    {
      "type": "signer",
      "key": "provider",
      "name": "John Smith",
      "email": "john.smith@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement",
  "label": null,
  "message": "Please review the agreement and provide your signature.",
  "status": "processing",
  "mode": "test",
  "routing": "parallel",
  "language": "en",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "attestation": "none",
  "branding": {
    "logo": null,
    "accent_color": "#2463eb",
    "email": {
      "from": "noreply@signatureapi.com",
      "footer": null,
      "logo_position": "left"
    }
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "topics": [],
  "metadata": {},
  "documents": [
    {
      "id": "doc_4YvlxUZN28CeonDq6rTbvk",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": "Service Agreement",
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [],
      "places": [
        {
          "key": "client_signs_here",
          "type": "signature",
          "recipient_key": "client",
          "height": 60
        },
        {
          "key": "provider_signs_here",
          "type": "signature",
          "recipient_key": "provider",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "client",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "standard",
        "url": null
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "completed_at": null,
      "status_updated_at": "2026-11-02T14:03:11.000Z"
    },
    {
      "id": "re_4VP9v4uPj6jwZzQ14CG2O8",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "provider",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "standard",
        "url": null
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "completed_at": null,
      "status_updated_at": "2026-11-02T14:03:11.000Z"
    }
  ],
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "name": null,
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "type": "standard",
    "status": "pending",
    "url": null,
    "language": "en",
    "timezone": "UTC",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ],
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null
  },
  "captures": {},
  "snapshot_url": null,
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request body contains validation errors.",
  "errors": [
    "recipients[0].email must be a valid email address"
  ]
}
```

### Example: Full

A DOCX template with merge data, branding, an approver and email code authentication.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Offer Letter",
  "label": "Offer Letter for Maria Garcia",
  "routing": "sequential",
  "message": "Welcome to Acme Corp! Please review and sign your offer letter.",
  "topics": [
    "hr",
    "onboarding"
  ],
  "metadata": {
    "candidate_ref": "hr-2210"
  },
  "branding": {
    "logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
    "accent_color": "#9810fa",
    "email": {
      "footer": "**Confidential:** this email is intended only for the named recipient.",
      "logo_position": "left"
    }
  },
  "timezone": "America/New_York",
  "documents": [
    {
      "key": "offer_letter",
      "title": "Offer Letter",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
      "format": "docx",
      "data": {
        "candidateName": "Maria Garcia",
        "position": "Product Designer",
        "startDate": "December 1, 2026",
        "salary": "$92,000"
      },
      "places": [
        {
          "key": "candidate_signs_here",
          "type": "signature",
          "recipient_key": "candidate",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "approver",
      "key": "hiring_manager",
      "name": "Alex Chen",
      "email": "alex.chen@example.com"
    },
    {
      "type": "signer",
      "key": "candidate",
      "name": "Maria Garcia",
      "email": "maria.garcia@example.com",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "delivery_type": "email",
      "ceremony": {
        "authentication": [
          {
            "type": "email_code"
          }
        ],
        "redirect_url": "https://acme.example/welcome",
        "embeddable_in": [],
        "url_variant": "standard"
      }
    }
  ],
  "deliverable": {
    "type": "standard",
    "language": "en",
    "timezone": "America/New_York",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss"
  }
}
```

Response 201 Created:

```json
{
  "id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
  "title": "Offer Letter",
  "label": "Offer Letter for Maria Garcia",
  "message": "Welcome to Acme Corp! Please review and sign your offer letter.",
  "status": "processing",
  "mode": "test",
  "routing": "sequential",
  "language": "en",
  "timezone": "America/New_York",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "attestation": "none",
  "branding": {
    "logo": "https://api.signatureapi.com/v1/uploads/upl_42NTdNnkg6dGLx8jR1X1wm",
    "accent_color": "#9810fa",
    "email": {
      "from": "noreply@signatureapi.com",
      "footer": "**Confidential:** this email is intended only for the named recipient.",
      "logo_position": "left"
    }
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "topics": [
    "hr",
    "onboarding"
  ],
  "metadata": {
    "candidate_ref": "hr-2210"
  },
  "documents": [
    {
      "id": "doc_0Pwd2LsJXeWGOJQwRctqC1",
      "envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
      "key": "offer_letter",
      "title": "Offer Letter",
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/acme-offer-letter-template.docx",
      "format": "docx",
      "data": {
        "candidateName": "Maria Garcia",
        "position": "Product Designer",
        "startDate": "December 1, 2026",
        "salary": "$92,000"
      },
      "fixed_positions": [],
      "places": [
        {
          "key": "candidate_signs_here",
          "type": "signature",
          "recipient_key": "candidate",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_1mdt9PluVuu4QIhYYe8R1P",
      "envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
      "type": "approver",
      "key": "hiring_manager",
      "name": "Alex Chen",
      "email": "alex.chen@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "redirect_url": null,
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "standard",
        "url": null
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "completed_at": null,
      "status_updated_at": "2026-11-02T16:30:00.000Z"
    },
    {
      "id": "re_2f0wBwlt2te0kjU5QeL3Nl",
      "envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
      "type": "signer",
      "key": "candidate",
      "name": "Maria Garcia",
      "email": "maria.garcia@example.com",
      "status": "pending",
      "ceremony": {
        "authentication": [
          {
            "type": "email_code"
          }
        ],
        "redirect_url": "https://acme.example/welcome",
        "redirect_delay": 3,
        "embeddable_in": [],
        "url_variant": "standard",
        "url": null
      },
      "delivery_type": "email",
      "ceremony_creation": "automatic",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "completed_at": null,
      "status_updated_at": "2026-11-02T16:30:00.000Z"
    }
  ],
  "deliverable": {
    "id": "del_4l3fQxvjRTltbPbzIbOlmK",
    "name": null,
    "envelope_id": "688d2c9f-5dbe-4bc4-bd0b-2e0459016be8",
    "type": "standard",
    "status": "pending",
    "url": null,
    "language": "en",
    "timezone": "America/New_York",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "offer_letter"
    ],
    "password": null,
    "created_at": "2026-11-02T16:30:00.000Z",
    "generated_at": null
  },
  "captures": {},
  "snapshot_url": null,
  "created_at": "2026-11-02T16:30:00.000Z",
  "completed_at": null
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
