---
title: "Document"
description: "The document object is a PDF or DOCX file inside an envelope: its source URL, format, template data, places and fixed positions, plus size and page limits."
canonical: "https://signatureapi.com/docs/api/resources/documents/object"
source: "https://signatureapi.com/docs/api/resources/documents/object.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Document

The document object is a PDF or DOCX file inside an envelope: its source URL, format, template data, places and fixed positions, plus size and page limits.

_Last verified against API version 1.18.0._

A **document** is a PDF or DOCX file within an [envelope](https://signatureapi.com/docs/api/resources/envelopes/object). Each envelope can contain between 1 and 10 documents. Recipients sign, approve, or prepare documents during their [ceremony](https://signatureapi.com/docs/api/resources/ceremonies/object).

Documents are defined inside the `documents` array when [creating an envelope](https://signatureapi.com/docs/api/resources/envelopes/create). They are not created or updated independently.

A document belongs to an [envelope](https://signatureapi.com/docs/api/resources/envelopes/object).

## Document formats

SignatureAPI supports two document formats. The `format` property is optional and defaults to `pdf`, so a PDF document can leave it out. Set `format` to `docx` for Word files.

**PDF** (`format: "pdf"`) accepts standard PDF files. Place fields using [placeholders](https://signatureapi.com/docs/api/resources/documents/object#place-positioning) embedded in the document text or [fixed coordinates](https://signatureapi.com/docs/api/resources/documents/object#place-positioning) on a page.

**DOCX** (`format: "docx"`) accepts Microsoft Word files. In addition to places, DOCX documents support [template fields](https://signatureapi.com/docs/api/resources/documents/templates) that merge dynamic data into the document before signing begins.

> **Warning:** If you upload a DOCX file but omit `format` or set it to `"pdf"`, the API returns a [cannot-parse-document](https://signatureapi.com/docs/v1/errors/cannot-parse-document) error. Always set `format: "docx"` for Word files.

> **Note:** DOCX files created with Google Docs or LibreOffice may not be compatible. If you get a [cannot-parse-document](https://signatureapi.com/docs/v1/errors/cannot-parse-document) error, open the file in Microsoft Word and re-save it. This resolves most compatibility issues.

## Providing a file

Set the `url` property to an HTTPS URL for the file. SignatureAPI downloads the file when the envelope is created.

The URL must come from a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), such as Amazon S3, Google Cloud Storage, Azure Blob Storage or Cloudflare R2. You can also [upload the file to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) and use the URL it returns.

**How to provide the document file**

|  | Use it when | How |
|---|---|---|
| [DOCX template with data](https://signatureapi.com/docs/api/resources/documents/templates) | The document is generated from your data for each envelope: names, dates or amounts | Put `{{key}}` fields in a DOCX file, set `format` to `docx` and send the values in the document's `data` property. SignatureAPI merges them before signing begins. |
| [Public URL](https://signatureapi.com/docs/api/resources/documents/url) | The finished file is at a public URL, for example on Amazon S3, Azure Blob Storage or Cloudflare R2 | Set the document's `url` to the file's URL; SignatureAPI downloads it when the envelope is created. For Amazon S3, pre-signed URLs are recommended. |
| [Upload through the API](https://signatureapi.com/docs/api/resources/uploads/create) | The file is on your server, for this envelope only | Send the bytes to `POST /v1/uploads` and use the `url` it returns as the document `url`. API uploads are deleted 24 hours after creation, and the maximum file size is 4.5 MB. |
| [Permanent upload or the Library](https://signatureapi.com/docs/api/resources/uploads/store) | You reuse the same file across many envelopes | Store the upload through the API, or upload the file to the Library in the Dashboard. Library files never expire and can be reused across envelopes. |

## Limits

These limits apply to every document, whether it comes from a supported host or an upload:

| Limit                  | Value   | Error when exceeded                                                                          |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------- |
| Documents per envelope | 1 to 10 | [validation-error](https://signatureapi.com/docs/v1/errors/validation-error)                 |
| File size              | 10 MB   | [cannot-download-document](https://signatureapi.com/docs/v1/errors/cannot-download-document) |
| Pages per document     | 100     | [too-many-pages](https://signatureapi.com/docs/v1/errors/too-many-pages)                     |
| Places per document    | 100     | [too-many-places](https://signatureapi.com/docs/v1/errors/too-many-places)                   |

A file sent through [Create Upload](https://signatureapi.com/docs/api/resources/uploads/create) has a lower size limit of 4.5 MB per request.

## Places

[Places](https://signatureapi.com/docs/api/resources/places/object) are areas in a document where recipients interact or where information is displayed automatically. Input places include signatures, initials, text inputs, checkboxes, and dropdowns. Informational places include static text, completion dates, and recipient details.

Define places in the `places` array. Each place has a `key` and a `type`.

## Place positioning

A place must be positioned in the document. There are two methods.

**Placeholders**: Embed `[[place_key]]` in the document text. The place appears at that location. This works for both PDF and DOCX documents.

**Fixed positions**: Specify the `page`, `top`, and `left` values in the `fixed_positions` array. Coordinates are measured in points (1 point = 1/72 inch) from the top-left corner of the page.

See [Place Positioning](https://signatureapi.com/docs/api/resources/places/positioning) for details and examples.

## Attributes

**PDF Document**

#### `id` (string)

The unique identifier of the document. Document IDs start with `doc_`.

#### `envelope_id` (uuid)

The unique identifier of the envelope, in UUID format.

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

#### `page_count` (integer)

The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged.

#### `url` (string)

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)

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 is `pdf`.

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

**fixed position**

#### `place_key` (string)

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)

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

#### `top` (number)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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

#### `box_count` (integer)

The number of individual character boxes to display.

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

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

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

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

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

#### `width` (number)

The total width of the boxed input field in points.

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

#### `height` (number)

The height of each individual box in points.

#### `font_size` (number)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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

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

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

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

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

#### `width` (number)

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

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

#### `line_count` (integer)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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 string)

The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`.

#### `default` (string)

The pre-selected option when the dropdown is displayed.

#### `behavior` (enum)

The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`.

#### `requirement` (enum)

Whether the recipient must select an option. Possible values: `required` or `optional`.

#### `prompt` (string)

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

#### `hint` (string)

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

#### `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 for the dropdown field.

#### `width` (number)

The width of the dropdown field in points.

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

**DOCX Document**

#### `id` (string)

The unique identifier of the document. Document IDs start with `doc_`.

#### `envelope_id` (uuid)

The unique identifier of the envelope, in UUID format.

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

#### `page_count` (integer)

The total number of pages in the document after processing. For DOCX templates, this reflects the page count after template data has been merged.

#### `url` (string)

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)

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 is `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)

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)

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

#### `top` (number)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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

#### `box_count` (integer)

The number of individual character boxes to display.

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

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

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

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

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

#### `width` (number)

The total width of the boxed input field in points.

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

#### `height` (number)

The height of each individual box in points.

#### `font_size` (number)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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

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

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

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

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

#### `width` (number)

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

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

#### `line_count` (integer)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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)

Specifies the type of place.

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

#### `key` (string)

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)

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 string)

The list of options available in the dropdown. Either an array of custom `label`/`value` pairs, or a string specifying a predefined option set such as `us_states_names` or `world_countries_names`.

#### `default` (string)

The pre-selected option when the dropdown is displayed.

#### `behavior` (enum)

The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`.

#### `requirement` (enum)

Whether the recipient must select an option. Possible values: `required` or `optional`.

#### `prompt` (string)

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

#### `hint` (string)

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

#### `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 for the dropdown field.

#### `width` (number)

The width of the dropdown field in points.

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

**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)

Specifies the type of place.

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

#### `key` (string)

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)

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

### Example: PDF document

Response 200 OK:

```json
{
  "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": [
    {
      "place_key": "provider_signs_here",
      "page": 3,
      "top": 600,
      "left": 72
    }
  ],
  "places": [
    {
      "key": "provider_signs_here",
      "type": "signature",
      "recipient_key": "provider",
      "height": 60
    },
    {
      "key": "client_signs_here",
      "type": "signature",
      "recipient_key": "client",
      "height": 60
    }
  ]
}
```

### Example: DOCX document

A Word template merged with data.

Response 200 OK:

```json
{
  "id": "doc_3QZHETuFIzFmrX6KaTLZLV",
  "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "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": {
    "date": "November 2nd, 2026",
    "employer": {
      "name": "Acme Corp Legal",
      "organization": "Acme Corp"
    },
    "candidate": {
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  },
  "fixed_positions": [],
  "places": [
    {
      "key": "employer_signs_here",
      "type": "signature",
      "recipient_key": "employer",
      "height": 60
    },
    {
      "key": "candidate_signs_here",
      "type": "signature",
      "recipient_key": "candidate",
      "height": 60
    }
  ]
}
```
