---
title: "Boxed Text Input Place"
description: "Collect short structured values such as reference codes, ZIP codes or dates in a row of single-character boxes that the recipient fills in while signing."
canonical: "https://signatureapi.com/docs/api/resources/places/boxed-text-input"
source: "https://signatureapi.com/docs/api/resources/places/boxed-text-input.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T11:48:11Z"
---

# Boxed Text Input Place

Collect short structured values such as reference codes, ZIP codes or dates in a row of single-character boxes that the recipient fills in while signing.

_Last verified against API version 1.18.0._

A **boxed text input place** displays a series of individual character boxes. Each box accepts one character, making this place type ideal for structured data such as reference codes, ZIP codes, or date components.

![A boxed text input during signing: a row of single-character boxes with 1, 2 and 3 typed in the first three and a hint tooltip above the row](https://signatureapi.com/docs/images/boxed-input.webp)

> **Note:** Boxed text input places are only available in envelopes with sequential signing.

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

## Box Count

The `box_count` property sets how many individual character boxes appear. Set this value based on the expected input length.

| Use case                      | Recommended `box_count` |
| ----------------------------- | ----------------------- |
| Reference code (6 characters) | 6                       |
| Store number (4 digits)       | 4                       |
| ZIP code                      | 5                       |
| Year (YYYY)                   | 4                       |
| Month or day (MM/DD)          | 2                       |

## Hints and Prompts

Use `hint` and `prompt` to guide recipients while filling in the boxes.

- **`hint`**: A tooltip shown when the recipient hovers over or focuses on the field.
- **`prompt`**: Placeholder text displayed inside the first box.

```json
{
  "hint": "The 6-character code printed on your order form",
  "prompt": "0"
}
```

## Capturing Input

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

## Size and Appearance

All three properties are required.

- **`width`**: The total width of the field in points (1/72 inch). Must be between 30 and 540.
- **`height`**: The height of each box in points (1/72 inch). Must be between 6 and 60, and at least `font_size`.
- **`font_size`**: The text size inside each box, in points. Must be between 6 and 12.

Each box is `width / box_count` points wide; keep it at least `font_size`.

## Attributes

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

Specifies the type of place.

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

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

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

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

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

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

#### `box_count` (number)

The number of individual character boxes to display.

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

#### `capture_as` (string)

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

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

#### `hint` (string)

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

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

#### `prompt` (string)

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

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

#### `requirement` (enum)

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

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

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

The total width of the boxed input field in points.

Must be between 30 and 540.

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

The height of each individual box in points.

Must be between 6 and 60, and greater than or equal to `font_size`.

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

The font size in points.

Must be between 6 and 12.

## Examples

#### Reference Code

```json
{
  "key": "order_reference",
  "type": "boxed_text_input",
  "recipient_key": "signer",
  "font_size": 12,
  "width": 150,
  "height": 20,
  "box_count": 6,
  "capture_as": "order_reference",
  "hint": "The 6-character code printed on your order form",
  "requirement": "required"
}
```

#### Store Number

```json
{
  "key": "store_number",
  "type": "boxed_text_input",
  "recipient_key": "franchisee",
  "font_size": 12,
  "width": 100,
  "height": 20,
  "box_count": 4,
  "capture_as": "store_number",
  "hint": "Your 4-digit store number",
  "requirement": "required"
}
```

#### Purchase Order

```json
{
  "key": "po_number",
  "type": "boxed_text_input",
  "recipient_key": "buyer",
  "font_size": 12,
  "width": 225,
  "height": 20,
  "box_count": 9,
  "capture_as": "po_number",
  "hint": "Your 9-digit purchase order number",
  "requirement": "required"
}
```
