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

# Text Input Place

> Collect information from recipients during signing with text input fields

A **text input place** marks a location in a document where a recipient types free-form text during the signing ceremony. These serve the same purpose as form fields in other e-signature platforms.

<Note>Text input places are only available in envelopes with sequential signing.</Note>

You can position text input places using either [placeholders](/docs/api/resources/places/positioning/#placeholders) or [fixed positions](/docs/api/resources/places/positioning/#fixed-positions).

## Hints and Prompts

Use `hint` and `prompt` to guide recipients while they fill out a text field.

* **`hint`**: A tooltip shown when the recipient hovers over or focuses on the field.
* **`prompt`**: Placeholder text displayed inside the field. It disappears when the recipient starts typing.

```json theme={null}
{
  //...
  "hint": "Your 8-digit reference code",
  "prompt": "12345678"
  //...
}
```

During the signing ceremony, the field appears like this:

<img src="https://mintcdn.com/signatureapi-daf4ee54/UqiVROmDb8Tz-1YC/docs/images/text-input-guides.png?fit=max&auto=format&n=UqiVROmDb8Tz-1YC&q=85&s=2685172a19a6aa28a264f5c39f391f0d" className={"border border-gray-500 shadow-none"} width="1090" height="258" data-path="docs/images/text-input-guides.png" />

## Format Validation

The `format` property validates what the recipient can enter. You can use a predefined format or a custom regular expression.

### Predefined formats

| Value        | Description   |
| ------------ | ------------- |
| `email`      | Email address |
| `zipcode-us` | US ZIP code   |

<Tip>More predefined formats are coming. [Let us know](https://signatureapi.com/support) if you need a specific format.</Tip>

### Custom regular expressions

Wrap a regular expression in forward slashes to define a custom format. For example, to require exactly 8 numeric digits:

```json theme={null}
{
  //...
  "format": "/^[0-9]{8}$/"
  //...
}
```

### Format messages

Set `format_message` to show a custom message when the recipient's input does not match the required format.

```json theme={null}
{
  //...
  "format": "/^[0-9]{8}$/",
  "format_message": "Must be exactly 8 numeric digits (0-9)"
  //...
}
```

During signing, the message is displayed like this:

<img src="https://mintcdn.com/signatureapi-daf4ee54/UqiVROmDb8Tz-1YC/docs/images/text-input-format-message.png?fit=max&auto=format&n=UqiVROmDb8Tz-1YC&q=85&s=44bb151aa4872785428e766d80f28ac2" className={"border border-gray-500 shadow-none"} width="1090" height="320" data-path="docs/images/text-input-format-message.png" />

## Capturing Input

Set `capture_as` to store the value the recipient enters in the envelope's `captures` object. After the envelope is completed, you can retrieve the value using the key you specified.

## Size and Appearance

* **`width`**: The initial width of the field in points (1/72 inch). The field may expand beyond this width as the recipient types.
* **`font_size`**: The text size inside the field, in points. Must be between 6 and 12. Defaults to 12.

## Attributes

<ParamField body="type" type="enum" required={true}>
  Specifies the type of place.

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

<ParamField body="key" type="string" required={true}>
  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.
</ParamField>

<ParamField body="recipient_key" type="string" required={true}>
  The key of the recipient assigned to this place. Must match one of the `key` values in the envelope's `recipients` array.
</ParamField>

<ParamField body="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.
</ParamField>

<ParamField body="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).
</ParamField>

<ParamField body="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).
</ParamField>

<ParamField body="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`.
</ParamField>

<ParamField body="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).
</ParamField>

<ParamField body="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).
</ParamField>

<ParamField body="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.
</ParamField>

<ParamField body="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.
</ParamField>

## Examples

<CodeGroup>
  ```json Optional Email Field theme={null}
  "documents": [
    {
      //...
      "places": [
        {
          "key": "buyer_email",
          "type": "text_input",
          "recipient_key": "buyer",
          "capture_as": "buyer_email",
          "prompt": "john@example.com",
          "hint": "Please enter your email",
          "format": "email",
          "requirement": "optional",
          "width": 200,
          "font_size": 8
        }
      ]
      //...
    }
  ]
  ```

  ```json Required Reference Number theme={null}
  "documents": [
    {
      //...
      "places": [
        {
          "key": "reference_number",
          "type": "text_input",
          "recipient_key": "applicant",
          "capture_as": "ref_number",
          "prompt": "12345678",
          "hint": "Your 8-digit reference code",
          "format": "/^[0-9]{8}$/",
          "format_message": "Must be exactly 8 digits",
          "requirement": "required",
          "width": 120
        }
      ]
      //...
    }
  ]
  ```

  ```json Address Field (Wide) theme={null}
  "documents": [
    {
      //...
      "places": [
        {
          "key": "mailing_address",
          "type": "text_input",
          "recipient_key": "borrower",
          "capture_as": "borrower_address",
          "prompt": "123 Main St, City, State ZIP",
          "hint": "Enter your full mailing address",
          "requirement": "required",
          "width": 350,
          "font_size": 10
        }
      ]
      //...
    }
  ]
  ```

  ```json US ZIP Code theme={null}
  "documents": [
    {
      //...
      "places": [
        {
          "key": "zip_code",
          "type": "text_input",
          "recipient_key": "customer",
          "capture_as": "customer_zip",
          "prompt": "90210",
          "format": "zipcode-us",
          "requirement": "required",
          "width": 80
        }
      ]
      //...
    }
  ]
  ```
</CodeGroup>