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. • To calculate the width, please use this formula: `width = max_length x character_width (depending on fontSize)`
`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 (default is 10px) and the line height (1.5). To calculate the height, please use this formula: height = (nb of lines) x font-size (default is 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.
`name`	Name of the Field. Optional.
`default_value`	Default value pre-filled for the Signer. Optional.
`read_only`	Define if the value of the Field can be edited by the Signer. It can only be set to `true` if a `default_value` is specified. Defaults to `false` and is 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|name}}
Example: {{s1|text|20|120|165|text field with specific width and height?|Important for us|t|Text1}}

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 the Text Field thanks to its name using this endpoint:/GET /signature_requests/{signatureRequestId}/documents/{documentId}/fields&signer_id[eq]=500800fc-3f91-4e86-a9c9-866809a1e3c9s&type[eq]=text&name[eq]=Text1.

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.