What is a Text Field?

A Text Field allows you to collect structured input from a Signer during the Signature process.

This input will automatically be added to the Document with information directly provided by the Signer, such as names, addresses, or other custom details.

Text Field creation

Before jumping to the creation options, let’s review the main characteristics of a Text Field:

Parameters	Descriptions
`width`	Width of the Text Field. Optional. Constraints: • If not set, the width is automatically calculated with the `max_length` value • 24px is the minimum authorized • The width of the Field must be adapted to the maximum length.
`height`	Height of the Text Field. Optional. Constraints: • The default value is 24px • 1px is the minimum value authorized • The height must take into account the font size (10px) and the line height (1.5). To calculate the height, please use this formula: height = (nb of lines) x font-size (10) x line height (1.5)
`max_length`	Maximal count of characters allowed in the Text Field.
`question`	Question asked to the Signer.
`instruction`	Extra information given to the Signer to fill the Text Field. It can be for example a text to copy. Optional.
`optional`	Define if the Text Field is optional or not. Defaults to `false` and is optional.
`font`	Define the font family, color, size, and style variant configuration. Optional.

Text Field creation with Smart Anchors

To create a Text Field using Smart Anchors, all you have to do is to add this tag to your Document:

Pattern: {{signer_index|text|max_length|width|height|question|instruction|optional}}
Example: {{s1|text|150|100|165|text field with specific width and height?|Important for us|t}}

The Signers index (s1, s2, s3, etc) is determined by the Signers order in the Signature Request. If the index references a non-existent Signer, the Field won’t be created.

Text Field creation with API endpoints

To create a Text Field using the API endpoints, you have two options:

Create a Signer and a Text Field at the same time using this endpoint:/POST /signature_requests/{signatureRequestId}/signers
Add a Text Field to an existing Signer using this endpoint:/POST /fields/{signatureRequestId}/documents/{documentId}/fields. This is the option to favour if you want to customise the Text Field, as detailed below.

Retrieve Text Field value once filled by the Signer

To retrieve the Signer input, you will need to:

Fetch Text Fields related to a specific Signer using this endpoint:/GET /signature_requests/{signatureRequestId}/documents/{documentId}/fields&signer_id[eq]=500800fc-3f91-4e86-a9c9-866809a1e3c9s&type[eq]=text.
Get the input value in the answer parameter of the desired Text Field in the response payload.

Customisation

Text Field appearance

You can configure the font family, color, size, and style variant of a Text Field. To do that, you have to fill in the font parameters when creating a Text Field with the following values.

Parameter	Optional	Details
`family`	`true`	• String of font family name (valid values are available in the API Reference) • Default value is Inconsolata
`color`	`true`	• Hexa string of the desired color • Default value is `#000000`
`size`	`true`	• Integer value of the desired pixel size • Min size: 7px • Max size: 96px • Default values is 12px
`variants`	`true`	Object containing the following possible values: `"variants": { "italic": false, "bold": false }`

⚠️ Font customisation is subject to the following rules:

Font customisation is only available when adding a Text Field to an existing Signer. It is not available when creating a Signer and a Text Field simultaneously.
Font customization is unavailable for Fields created through Smart Anchors.
If a font node is provided, then height and width properties become mandatory, and Field sizes will not be automatically calculated.