> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Document

> The document object represents a PDF or DOCX file within an envelope

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

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

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

## Document formats

SignatureAPI supports two document formats. You must set the `format` property to match the file type.

**PDF** (`format: "pdf"`) accepts standard PDF files. Place fields using [placeholders](#place-positioning) embedded in the document text or [fixed coordinates](#place-positioning) on a page.

**DOCX** (`format: "docx"`) accepts Microsoft Word files. In addition to places, DOCX documents support [template fields](/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](/docs/v1/errors/cannot-parse-document) error. Always set `format: "docx"` for Word files.</Warning>

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

## Providing a file

Set the `url` property to a publicly accessible URL for the file. SignatureAPI downloads the file when the envelope is created.

You can host files on Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and other services. You can also [upload files directly to SignatureAPI](/docs/api/resources/documents/url) and use the returned URL.

## Places

[Places](/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](/docs/api/resources/places/positioning) for details and examples.

## Attributes

<Expandable title="PDF Document">
  <ResponseField name="id" type="string">
    The unique identifier of the document. Document IDs start with `doc_`.
  </ResponseField>

  <ResponseField name="envelope_id" type="uuid">
    The unique identifier of the envelope, in UUID format.
  </ResponseField>

  <ResponseField name="key" type="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.
  </ResponseField>

  <ResponseField name="title" type="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.
  </ResponseField>

  <ResponseField name="page_count" type="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.
  </ResponseField>

  <ResponseField name="url" type="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](/docs/api/resources/uploads/create) endpoint.

    Learn more about your options in [Document URL and Upload](/docs/api/resources/documents/url).
  </ResponseField>

  <ResponseField name="format" type="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`.
  </ResponseField>

  <ResponseField name="fixed_positions" type="array of fixed positions">
    <Expandable title="fixed position">
      <ResponseField name="place_key" type="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.
      </ResponseField>

      <ResponseField name="page" type="number">
        The page number where the place is positioned. Page numbering starts at 1.
      </ResponseField>

      <ResponseField name="top" type="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.
      </ResponseField>

      <ResponseField name="left" type="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.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="places" type="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](/docs/api/resources/places/object).

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a signature place, the value must be `signature`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the signature place in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width is calculated automatically using a 5:2 ratio based on this height.

        Must be between 20 and 60. Defaults to 60.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For an initials place, the value must be `initials`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the initials place in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width equals the height.

        Must be between 20 and 60. Defaults to 60.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a text place, the value must be `text`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="value" type="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.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in points.

        Must be between 1 and 144. The default is 12.
      </ResponseField>

      <ResponseField name="font_color" type="string">
        The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black).
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a text input place, the value must be `text_input`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill this field to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="format" type="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](/docs/api/resources/places/text-input#format-validation).
      </ResponseField>

      <ResponseField name="format_message" type="string">
        The message displayed when the user’s input does not match the required format.

        Learn more in [Format Validation -> Adding a Custom Message](/docs/api/resources/places/text-input#adding-a-custom-message).
      </ResponseField>

      <ResponseField name="width" type="number">
        The initial width of the text input field in <Tooltip tip="1/72 of an inch">points</Tooltip>. The field may expand beyond this width during typing.

        Must be between 30 and 540. Defaults to 30.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72 of an inch">points</Tooltip>.

        Must be between 6 and 12. Defaults to 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a boxed text input place, the value must be `boxed_text_input`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="box_count" type="integer">
        The number of individual character boxes to display.

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

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill all boxes to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the first box during the signing ceremony to guide the recipient.

        Learn more in [Hints and Prompts](/docs/api/resources/places/boxed-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the boxed text input field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/boxed-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="width" type="number">
        The total width of the boxed input field in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 30 and 540. The default is 30.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of each individual box in <Tooltip tip="1/72th of an inch">points</Tooltip>.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 6 and 12. The default is 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

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

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill this field to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/multiline-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/multiline-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="width" type="number">
        The width of the multi-line text input place in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 30 and 540. The default is 30.
      </ResponseField>

      <ResponseField name="line_count" type="integer">
        The number of lines for the multi-line text input field.

        Must be between 1 and 100.
      </ResponseField>

      <ResponseField name="line_height" type="number">
        The line height in <Tooltip tip="1/72th of an inch">points</Tooltip>. Must be greater than or equal to `font_size`.

        Must be between 6 and 72. The default is 12.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 6 and 12. The default is 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a checkbox place, the value must be `checkbox`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="symbol" type="enum">
        The symbol to display in the checkbox when it is checked.

        Available options are `check` and `xmark`. The default is `check`.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must check this box to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `optional`.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the checkbox in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width equals the height.

        Must be between 8 and 40. Defaults to 20.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a dropdown place, the value must be `dropdown`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="options" type="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`.
      </ResponseField>

      <ResponseField name="default" type="string">
        The pre-selected option when the dropdown is displayed.
      </ResponseField>

      <ResponseField name="behavior" type="enum">
        The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Whether the recipient must select an option. Possible values: `required` or `optional`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the dropdown field during the signing ceremony.
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed when the user hovers over or focuses on the dropdown field.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in points for the dropdown field.
      </ResponseField>

      <ResponseField name="width" type="number">
        The width of the dropdown field in points.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_completed_date`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="date_format" type="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`.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `envelope_completed_date`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="date_format" type="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`.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_name`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_email`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

<Expandable title="DOCX Document">
  <ResponseField name="id" type="string">
    The unique identifier of the document. Document IDs start with `doc_`.
  </ResponseField>

  <ResponseField name="envelope_id" type="uuid">
    The unique identifier of the envelope, in UUID format.
  </ResponseField>

  <ResponseField name="key" type="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.
  </ResponseField>

  <ResponseField name="title" type="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.
  </ResponseField>

  <ResponseField name="page_count" type="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.
  </ResponseField>

  <ResponseField name="url" type="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](/docs/api/resources/uploads/create) endpoint.

    Learn more about your options in [Document URL and Upload](/docs/api/resources/documents/url).
  </ResponseField>

  <ResponseField name="format" type="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`.
  </ResponseField>

  <ResponseField name="data" type="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 `{}`.
  </ResponseField>

  <ResponseField name="fixed_positions" type="array of fixed positions">
    <Expandable title="fixed position">
      <ResponseField name="place_key" type="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.
      </ResponseField>

      <ResponseField name="page" type="number">
        The page number where the place is positioned. Page numbering starts at 1.
      </ResponseField>

      <ResponseField name="top" type="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.
      </ResponseField>

      <ResponseField name="left" type="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.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="places" type="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](/docs/api/resources/places/object).

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a signature place, the value must be `signature`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the signature place in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width is calculated automatically using a 5:2 ratio based on this height.

        Must be between 20 and 60. Defaults to 60.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For an initials place, the value must be `initials`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the initials place in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width equals the height.

        Must be between 20 and 60. Defaults to 60.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a text place, the value must be `text`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="value" type="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.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in points.

        Must be between 1 and 144. The default is 12.
      </ResponseField>

      <ResponseField name="font_color" type="string">
        The font color for this text place. Must be a six-digit hex color code with a leading `#`. Defaults to `#000000` (black).
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a text input place, the value must be `text_input`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill this field to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="format" type="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](/docs/api/resources/places/text-input#format-validation).
      </ResponseField>

      <ResponseField name="format_message" type="string">
        The message displayed when the user’s input does not match the required format.

        Learn more in [Format Validation -> Adding a Custom Message](/docs/api/resources/places/text-input#adding-a-custom-message).
      </ResponseField>

      <ResponseField name="width" type="number">
        The initial width of the text input field in <Tooltip tip="1/72 of an inch">points</Tooltip>. The field may expand beyond this width during typing.

        Must be between 30 and 540. Defaults to 30.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72 of an inch">points</Tooltip>.

        Must be between 6 and 12. Defaults to 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a boxed text input place, the value must be `boxed_text_input`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="box_count" type="integer">
        The number of individual character boxes to display.

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

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill all boxes to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the first box during the signing ceremony to guide the recipient.

        Learn more in [Hints and Prompts](/docs/api/resources/places/boxed-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the boxed text input field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/boxed-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="width" type="number">
        The total width of the boxed input field in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 30 and 540. The default is 30.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of each individual box in <Tooltip tip="1/72th of an inch">points</Tooltip>.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 6 and 12. The default is 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

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

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must fill this field to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `required`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/multiline-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed over the input text field during the signing ceremony.

        Learn more in [Hints and Prompts](/docs/api/resources/places/multiline-text-input#hints-and-prompts).
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="width" type="number">
        The width of the multi-line text input place in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 30 and 540. The default is 30.
      </ResponseField>

      <ResponseField name="line_count" type="integer">
        The number of lines for the multi-line text input field.

        Must be between 1 and 100.
      </ResponseField>

      <ResponseField name="line_height" type="number">
        The line height in <Tooltip tip="1/72th of an inch">points</Tooltip>. Must be greater than or equal to `font_size`.

        Must be between 6 and 72. The default is 12.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in <Tooltip tip="1/72th of an inch">points</Tooltip>.

        Must be between 6 and 12. The default is 12.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a checkbox place, the value must be `checkbox`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="symbol" type="enum">
        The symbol to display in the checkbox when it is checked.

        Available options are `check` and `xmark`. The default is `check`.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Specifies whether the recipient must check this box to complete the signing ceremony.

        Possible values are `required` or `optional`. The default is `optional`.
      </ResponseField>

      <ResponseField name="height" type="number">
        The height of the checkbox in <Tooltip tip="1/72 of an inch">points</Tooltip>. The width equals the height.

        Must be between 8 and 40. Defaults to 20.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For a dropdown place, the value must be `dropdown`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="options" type="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`.
      </ResponseField>

      <ResponseField name="default" type="string">
        The pre-selected option when the dropdown is displayed.
      </ResponseField>

      <ResponseField name="behavior" type="enum">
        The display behavior of the dropdown. Possible values: `auto`, `select`, or `combobox`.
      </ResponseField>

      <ResponseField name="requirement" type="enum">
        Whether the recipient must select an option. Possible values: `required` or `optional`.
      </ResponseField>

      <ResponseField name="prompt" type="string">
        A placeholder message shown inside the dropdown field during the signing ceremony.
      </ResponseField>

      <ResponseField name="hint" type="string">
        A tooltip message displayed when the user hovers over or focuses on the dropdown field.
      </ResponseField>

      <ResponseField name="capture_as" type="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.
      </ResponseField>

      <ResponseField name="font_size" type="number">
        The font size in points for the dropdown field.
      </ResponseField>

      <ResponseField name="width" type="number">
        The width of the dropdown field in points.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_completed_date`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>

      <ResponseField name="date_format" type="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`.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `envelope_completed_date`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="date_format" type="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`.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_name`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>
    </Expandable>

    <Expandable title="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.

      <ResponseField name="type" type="enum">
        Specifies the type of place.

        For this kind of place, the value must be `recipient_email`.
      </ResponseField>

      <ResponseField name="key" type="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.
      </ResponseField>

      <ResponseField name="recipient_key" type="string">
        The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Expandable>

<ResponseExample>
  ```json PDF document theme={null}
  // HTTP Status Code 200

  {
    "id": "doc_3jBYlxa9gv0fGLzFAnfwxe",
    "envelope_id": "5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13",
    "key": "agreement",
    "title": "Service Agreement",
    "page_count": 3,
    "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/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": "service_provider",
        "height": 60
      },
      {
        "key": "client_signs_here",
        "type": "signature",
        "recipient_key": "client",
        "height": 60
      }
    ]
  }
  ```

  ```json DOCX document theme={null}
  // HTTP Status Code 200

  {
    "id": "doc_8hKpmnFR6CFr6oChasgVb9",
    "envelope_id": "5e5ace5e-bd1e-4d5a-bb1f-6a2b2e42cd13",
    "key": "agreement",
    "title": "Service Agreement",
    "page_count": 2,
    "url": "https://pub-e5051420e98a4fdfb3fd42a62fbf06fa.r2.dev/agreement-template.docx",
    "format": "docx",
    "data": {
      "date": "December 31st, 2025",
      "serviceProvider": {
        "name": "Jane Smith",
        "organization": "ACME Global, Inc."
      },
      "client": {
        "name": "Michael J. Miller",
        "organization": "Miller Industries"
      }
    },
    "fixed_positions": [],
    "places": [
      {
        "key": "provider_signs_here",
        "type": "signature",
        "recipient_key": "service_provider",
        "height": 60
      },
      {
        "key": "client_signs_here",
        "type": "signature",
        "recipient_key": "client",
        "height": 60
      }
    ]
  }
  ```
</ResponseExample>