Skip to content

Interactive places

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.

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

Boxed text input places are only available in envelopes with sequential signing.

You can position boxed text input places using either placeholders or 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 caseRecommended box_count
Reference code (6 characters)6
Store number (4 digits)4
ZIP code5
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

typeenumrequired

Specifies the type of place.

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

keystringrequired

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_keystringrequired

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

box_countnumber

The number of individual character boxes to display.

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

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.

hintstring

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

Learn more in Hints and Prompts.

promptstring

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

Learn more in Hints and Prompts.

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

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

widthnumberrequired

The total width of the boxed input field in .

Must be between 30 and 540.

heightnumberrequired

The height of each individual box in .

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

font_sizenumberrequired

The font size in .

Must be between 6 and 12.

Examples

Reference Code
{
  "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
{
  "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
{
  "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"
}