Text input places allow you to request specific information from recipients during the signing ceremony. These are similar to fields in other electronic signature platforms.
Text input places are only available in envelopes with sequential signing.
You can position Text Input Places inside a document using either fixed positions or placeholders.

​
Hints and Prompts

You can use hint and prompt properties to guide recipients while filling out text fields:
  • Hint: A message shown as a tooltip when the user hovers over or focus on the text field. Set it using the hint property.
  • Prompt: A placeholder-style message displayed inside the text field. Set it using the prompt property.
For example, a text input place configured with the following properties: 
{
  //...
  "hint": "Your 8-digit reference code",
  "prompt": "12345678"
  //...
}
During the signing ceremony, the field will appear like this:

​
Format Validation

The format property allows you to control the type of input users can enter into a field. This property can accept either predefined formats or custom regular expressions.

​
Predefined Formats

You can use one of the following predefined values:
FormatDescription
emailEmail address
zipcode-usUS ZIP code
More predefined formats are coming soon! Have a specific format in mind? Let us know.

​
Custom Regular Expressions

If the predefined formats don’t meet your needs, you can define a custom format using a regular expression. Enclose the regular expression in forward slashes. For example, to require exactly 8 numeric digits: 
{
  // ...
  "format": "/^[0-9]{8}$/"
  // ...
}

​
Adding a Custom Message

To guide users during input, you can include a format_message property. This message is displayed when the input doesn’t match the required format. For example: 
{
  // ...
  "format": "/^[0-9]{8}$/",
  "format_message": "Must be exactly 8 numeric digits (0-9)"
  // ...
}
During the signing ceremony, the format_message is displayed to help users understand the input requirements:

​
Size and Appearance

You can customize the size and appearance of text input places to better fit your document layout:

​
Width

The width property sets the initial width of the text input field in points (1/72 of an inch). The field can expand beyond this width as users type to accommodate longer text entries.

​
Font Size

The font_size property controls the size of the text displayed within the input field, measured in points. The default font size is 12 points.

​
Example

For example, a text input field can be used to place a text box at the placeholder [[buyer_email]]. This allows the recipient with the key “buyer” to provide their email address. This field is set to optional. 
"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
      }
    ]
    ...
  }
]

​
Parameters

​
type
enum
required
Specifies the type of place.For a text input place, the value must be text_input.
​
key
string
required
A user-provided key that identifies a place within a document.It must be up to 32 characters long, using only lowercase letters, numbers, or underscores, and it must begin with a letter.
​
recipient_key
string
required
A user-provided key that identifies a recipient within an envelope.It must match one of the recipient.key values in the envelope’s recipient list.
​
capture_as
string
A user-defined identifier used to store the value entered by the recipient. This value will be included in the captures object of the Envelope.Must start with a lowercase letter and contain only lowercase letters, numbers, or underscores. Maximum length is 32.
​
hint
string
A tooltip message displayed over the input text field during the signing ceremony.Learn more in Hints and Prompts.
​
prompt
string
A placeholder message shown inside the input text field during the signing ceremony.Learn more in 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.
​
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.
​
width
number
The initial width of the text input place in .Must be between 30 and 540. The default is 30.
​
font_size
number
The font size in .Must be between 6 and 12. The default is 12.