On this page, you will learn the different ways to add fields to your documents.

Two methods can be used:

Method A: Add fields using Smart Anchors: to do so you only have to add text anchors directly in your signable documents when you generate them.
Method B: Add fields manually within the Signature Request by providing the coordinates.

Method A: Using Smart Anchors

The easiest way to create and position fields is to add text anchors directly in your signable documents, using any word processor (Word, Google Docs, dynamic text generation solution...).

Those text anchors have a specific pattern to follow to create the desired field. So for each field, there is a pattern to respect to create the dedicated Smart Anchor.

Those text anchors should be of the same colour as the background to make them invisible on the final document.

⚠️
Limits to use Smart Anchors
To maintain performance, the usage of Smart Anchors is only possible on documents fitting the following criteria:

150 pages or less

50Mb or less

We do not support multiline anchors

If an anchor refers to a non-existing Signer position the field will not be created

For better compatibility, we recommend using the Arial font when adding a Smart Anchor into a document.

If a document has more than 150 pages, no error will be sent but the Smart Anchors won't be parsed.

📘
Document upload and Smart Anchors

Additionally you must set the key parse_anchors at "true" when uploading the document to indicate you need anchors to be parsed

If there are several signers, each of them needs to get its own Signature Field with the dedicated signer index

POST /signature_requests/{signatureRequestId}/documents

curl --location --request POST '{baseUrl}/signature_requests/{signatureRequestId}/documents' \
--header 'Authorization: Bearer {apiKey}' \
--form 'file=@"/Users/user/file_with_smart_anchors.pdf"' \
--form 'nature="signable_document"' \
--form 'parse_anchors="true"'

{
    "id": "5e3dad11-a934-468a-8768-010f996da350",
    "filename": "file_with_smart_anchors.pdf",
    "nature": "signable_document",
    "content_type": "application/pdf",
    "sha256": "2d39a22864d7859858bdbe019a02e667a804de5c7791ecb4ca4cc64a44ad63ad",
    "is_protected": false,
    "is_signed": false,
    "created_at": "2022-03-24T11:15:30+00:00",
    "total_pages": 5,
    "is_locked": false,
    "initials": null,
    "total_anchors": 6
}

The match with each Signer is done using the s1 .... sn part of the anchors, where s1 designates the first Signer of the Signature Request (in the order in which the Signers were added to the Signature Request).

When uploading a document with anchor parsing enabled, the response will contain a total_anchors attribute equal to the number of anchors found in the document.

You can now use this document normally to create a signature request, the fields corresponding to the anchors will be automatically created when the signature request is activated.

Error management: A Smart Anchor will not be recognized if a field value is not correct.

Signature Field

Pattern: {{signer_index|signature|width|height}}
Example: {{s1|signature|85|37}}

Variable	Description	Value
`signer_index`	index of the Signer to which the field is related. For instance `s1` for the first Signer, `s2` for the second Signer and so on. The signers index is determined in the order in which the Signers were added to the Signature Request.	`sn`, with n `integer`
`width`	width of the signature field, starting at the top left of the text anchor.	min `85`, max `580`
`height`	height of the signature field, starting at the top left of the text anchor.	min `37`, max `253`

Variable

Description

Value

signer_index

index of the Signer to which the field is related. For instance s1 for the first Signer, s2 for the second Signer and so on.

The signers index is determined in the order in which the Signers were added to the Signature Request.

sn, with n integer

width

width of the signature field, starting at the top left of the text anchor.

min 85, max 580

height

height of the signature field, starting at the top left of the text anchor.

min 37, max 253

Mention Field

Pattern: {{signer_index|mention|mention_content}}
Example: {{s1|mention|Read and approved on the %date%}}

Variable	Description	Value
`signer_index`	index of the Signer to which the field is related. For instance `s1` for the first Signer, `s2` for the second signer and so on. The Signers' indexes are determined in the order in which the Signers were added to the Signature Request.	`sn`, with n `integer`
`mention_content`	The text you want to be displayed in the mention.	You can use dynamic tags when creating the mentions: `%date%` will display the current date when the Signer sign the Signature Request (eg. "24-03-2022") `%datetime%` will display the current date and time when the Signer sign the Signature Request (eg. "24-03-2022 10:30 UTC+0")HTML content is not allowed.

Variable

Description

Value

signer_index

index of the Signer to which the field is related. For instance s1 for the first Signer, s2 for the second signer and so on.

The Signers' indexes are determined in the order in which the Signers were added to the Signature Request.

sn, with n integer

mention_content

The text you want to be displayed in the mention.

You can use dynamic tags when creating the mentions:

%date% will display the current date when the Signer sign the Signature Request (eg. "24-03-2022")
%datetime% will display the current date and time when the Signer sign the Signature Request (eg. "24-03-2022 10:30 UTC+0")HTML content is not allowed.

Checkbox Field

Pattern: {{signer_index|checkbox|size|optional|checked|name}}
Example: {{s1|checkbox|24|t|f|Checkbox1}}
Deprecated pattern: {{signer_index|checkbox|optional|checked|name}}

Variable	Description	Value
`signer_index`	index of the Signer to which the field is related. For instance `s1` for the first Signer, `s2` for the second Signer and so on. The Signers index is determined in the order in which the Signers were added to the Signature Request.	`sn`, with n `integer`
`size`	Size of the checkbox. The ommition of this parameter is deprecated and it should be present for all new integrations	Minimum size is `8px` Maximum size is `240px` Default size is `24px`
`optional`	Set if the checkbox is optional or not. If it is not optional then the Signer can only sign if the checkbox is checked.	- `t` for `true` `f` for `false`
`checked`	Set if the checkbox is initially checked when the Signer sees the document.	- `t` for `true` `f` for `false`
`name`	A custom name given to the checkbox to later identify the answers. This attribute will be included in webhooks and when accessing the Signers objects through the API.	Custom `string`

Text Field (Text input)

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}}

Attribute	Description	Value
`signer_index`	Index of the Signer to which the field is related. For instance `s1` for the first Signer, `s2` for the second Signer and so on. The Signers index is determined in the order in which the Signers were added to the Signature Request.	`sn`, with n `integer`
`max_length`	Maximal count of characters in the Text Field.
`width`	Width of the Text Field.	In pixel. Minimum width is `24`. Default value is `198`. The width of the field must be adapted to the maximum length. Each character must be `6px` wide and we apply a padding (left and right) of `4px`. For example, for a 12 characters text field, the width should be at least `80px`. `width >= (max_length * 6px) + (2 * 4px)` The Smart Anchor will not be recognized if this value is not correct. Optional.
`height`	Height of the Text Field.	In pixel. Minimum height is `24` (it corresponds to one line). Default value is `24`. Value for more that one line = `(# of lines + 1) * 15` The Smart Anchor will not be recognized if this value is not correct. Optional.
`question`	Question which is going to be asked to the Signer.	Custom `string`.
`instruction`	Can be used to give more instructions to the Signer, for example, a text to copy.	Custom `string`. Optional.
`optional`	If the text field is optional or not. Default to `false`.	- `t` for `true` `f` for `false`

Radio Button Field

Pattern: {{signer_index|radio|size|group_name|optional|radio_button_name}}
Example: {{s1|radio|28|group_name_1|t|my_radio_button_name}}

Attribute	Description	Value
`signer_index`	Index of the Signer to which the field is related. For instance `s1` for the first Signer, `s2` for the second Signer and so on. The Signers index is determined in the order in which the Signers were added to the Signature Request.	`sn`, with n `integer`
`size`	Size of the radio field. The size represents both the height and width of a radio field. This parameter is optional, the default value is 24px.	Minimum size is `8px` Maximum size is `240px` Default size is `24px`
`group_name`	This name will be used to group radio fields belonging to the same radio group. This name is only used during the smart anchors parsing and will not be exposed after.	`string`
`optional`	If the radio field is optional or not. ℹ️ Only the first radio field of the group determines whether the whole group is optional or not.	`t` for `true` `f` for `false`
`radio_button_name`	This name will be used to name the radio button.	- `string` `not required` Max characters allowed is `128`

Method B: Manual Field creation

The Fields are positioned on your documents by specifying:

the document on which it should be placed
the page in the document
the coordinates of the field in this page

A manual field needs to be attached to a Signer or a Signature Request.

For each manual field, you should at least set those parameters:

Attribute	Description
`document_id`	Id of the document on which the field will be added
`type`	The type of field. See below.
`page`	The page of the document on which the field is positoned
`x`	The top-left x coordinates of the field with the x-axis starting at the left of the page
`y`	The top-left y coordinates of the field with the y-axis starting at the top of the page

We will take an example on a PDF document in A4 format which is the norm (A4 layout: width: 596, height: 842)

Top left of the page: x: 0, y: 0
Bottom right of the page x: 400, y: 650

📘
How to find x, y coordinates for your Fields
If your PDF document is always the same, you can use our tool, PlaceIt, to find the coordinates of the Fields.

When it comes to creating a manual field, two options are possible:

Use the dedicated endpoint (option 1 in the examples below).
Add this field when you create a Signer or a Signature request (option 2 in the example below)

Signature Field

Parameter	Optional	Details
`height`	true	- Default value is `37` px `37` px is the minimum authorized `1000` px is the maximum authorized
`width`	true	- Default value is `85` px `85` px is the minimum authorized `2000` px is the maximum authorized

Parameter

Optional

Details

height

true

- Default value is 37 px

37 px is the minimum authorized
1000 px is the maximum authorized

width

true

- Default value is 85 px

85 px is the minimum authorized
2000 px is the maximum authorized

/POST /fields/{signatureRequestId}/documents/{documentId}/fields

{
    "signer_id": "{{signerId}}",
    "height": 37,
    "width": 85,
    "page": 2,
    "x": 400,
    "y": 650,
    "type": "signature"
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "signature",
      "page": 2,
      "x": 400,
      "y": 650,
      "height": 37,
      "width": 180
    }
  ]
}

Mention Field

Parameter	Optional	Details
`width`	true	- If not set, the width is automatically calculated with the mention length `24` px is the minimum authorized
`height`	true	- If not set, the height will be automatically calculated based on the number of line breaks in the mention content. Otherwise, height should be equal to 24 or a multiple of 15 greater than 24: 24, 30, 45, etc.
`mention`	false	- `255` is the maximum number of characters allowed HTML content is not allowed.

Parameter

Optional

Details

width

true

- If not set, the width is automatically calculated with the mention length

24 px is the minimum authorized

height

true

- If not set, the height will be automatically calculated based on the number of line breaks in the mention content. Otherwise, height should be equal to 24 or a multiple of 15 greater than 24: 24, 30, 45, etc.

mention

false

- 255 is the maximum number of characters allowed

HTML content is not allowed.

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "mention",
      "page": 1,
      "x": 20,
      "y": 700,
      "width": 20,
      "height":24,
      "mention": "Read and approved the %date%"
    }
  ]
}

Checkbox Field

Parameter	Optional	Details
`name`	true	- `128` is the maximum number of characters allowed
`optional`	false	- If set to `true`, the checkbox has to be checked by the signer in order to sign
`checked`	false	- If set to `true`, the checkbox will be pre-checked when the signer will open the document
`size`	false	- Default value is `24` px `8` px is the minimum authorized `240` px is the maximum authorized

/POST /fields/{signatureRequestId}/documents/{documentId}/fields

{
    "signer_id": "{{signerId}}",
    "type": "checkbox",
    "page": 1,
    "x": 20,
    "y": 700,
    "name": "Checkbox 1",
    "optional": true,
    "checked": false,
    "size": 24
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "checkbox",
      "page": 1,
      "x": 20,
      "y": 700,
      "name": "Checkbox 1",
      "optional": true,
      "checked": false,
      "size": 24
    }
  ]
}

Text Field (Text input)

Parameter	Optional	Details
`max_length`	false	- Maximal count of characters in the Text Field
`optional`	false	- If set to `true`, the signer has to fill the text in order to sign
`question`	false	- The question for the signer `255` is the maximum number of characters allowed
`instruction`	true	- Can be used to give more instructions to the Signer `10000` is the maximum number of characters allowed
`width`	true	- Default value is `198` px `24` px is the minimum authorized
`height`	true	- Default value is `24` px `24` px is the minimum authorized Value for more that one line = `(# of lines + 1) * 15`

More details about Text Fields can be found in our API reference (Signer > Body Param > Option 1 > Fields > Option 3)

/POST /fields/{signatureRequestId}/documents/{documentId}/fields

{
    "signer_id": "{{signerId}}",
    "type": "text",
    "page": 1,
    "x": 20,
    "y": 20,
    "max_length": 80,
    "optional": true,
    "question": "What is your name?"
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "text",
      "page": 1,
      "x": 20,
      "y": 20,
      "max_length": 80,
      "optional": true,
      "question": "What is your name?"
    }
  ]
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "text",
      "page": 1,
      "x": 20,
      "y": 20,
      "max_length": 10,
      "optional": true,
      "question": "What is your name?",
      "width": 60
    }
  ]
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "text",
      "page": 1,
      "x": 20,
      "y": 20,
      "max_length": 150,
      "optional": true,
      "question": "What is your name?",
      "height": 45
    }
  ]
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "type": "text",
      "page": 1,
      "x": 20,
      "y": 20,
      "max_length": 150,
      "optional": true,
      "question": "What is your name?",
      "width": 100,
      "height": 165
    }
  ]
}

Read-only Text Fields

Parameter	Optional	Details
`page`	false	Page in which the Read-only Text Field must be included
`x`	false	x position of the Read-only Text Field in the Document
`y`	false	y position of the Read-only Text Field in the Document
`width`	true	If not set, the width is automatically calculated with the mention length
`height`	true	The height must be 24 or a multiple of 15 greater than 24. If height is not provided, it will be calculated depending on the number of newlines in the mention
`text`	false	Text to display

/POST /fields/{signatureRequestId}/documents/{documentId}/fields

{
    "type": "read-only-text-field",
    "page": 1,
    "x": 20,
    "y": 20,
    "text": "Here is a Read-only Text Field"
}

More information about how to create Read-only Text fields can be found in our API Reference.

Radio Button Fields

Radio Group

Parameter	Optional	Details
`optional`	false	- If set to `true`, the signer has to check at least one radio in order to sign
`name`	true	- The name of the radio group `128` is the maximum number of characters allowed

Parameter

Optional

Details

optional

false

- If set to true, the signer has to check at least one radio in order to sign

name

true

- The name of the radio group

128 is the maximum number of characters allowed

Radio Button (list of)

Parameter	Optional	Details
`name`	true	- The name of the radio button `128` is the maximum number of characters allowed
`size`	true	- Default value is `24` px `8` px is the minimum authorized `240` px is the maximum authorized It applies to all the radio buttons of the same group

Parameter

Optional

Details

name

true

- The name of the radio button

128 is the maximum number of characters allowed

size

true

- Default value is 24 px

8 px is the minimum authorized
240 px is the maximum authorized
It applies to all the radio buttons of the same group

/POST /fields/{signatureRequestId}/documents/{documentId}/fields

{
    "signer_id": "{{signerId}}",
      "page": 1,
      "type": "radio_group",
      "optional": false,
      "name": "Radio group name",
      "radios": [
        {
          "name": "Radio 1 name",
          "x": 110,
          "y": 115,
          "size": 26
        },
        {
          "name": "Radio 2 name",
          "x": 120,
          "y": 125
        },
        {
          "name": "Radio 3 name",
          "x": 130,
          "y": 135
        }
      ]
}

/POST /signature_requests/{signatureRequestId}/signers

{
  "info": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "+33700000000",
    "locale": "fr"
  },
  "fields": [
    {
      "document_id": "{{documentId}}",
      "page": 1,
      "type": "radio_group",
      "optional": false,
      "name": "Radio group name",
      "radios": [
        {
          "name": "Radio 1 name",
          "x": 110,
          "y": 115,
          "size": 26
        },
        {
          "name": "Radio 2 name",
          "x": 120,
          "y": 125
        },
        {
          "name": "Radio 3 name",
          "x": 130,
          "y": 135
        }
      ]
    }
  ]
}

Fields style customisation

It is possible to configure the font family, color, size, and style variant on the following field types: Mention, Text, and Read-only Text. This aims to enhance customization options for text fields.

⚠️
Rules on using the font Object in Payload
Font customization is subject to the following additional rules:

It is only available through the fields creation endpoints and is not available through Smart Anchors.

If a font node is provided, then height and width properties become mandatory, and field sizes will not be automatically calculated.

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: `7 px` Max size: `96 px` default values are: 10px for Read-only Text and Mention 12px for Text fields
`variants`	`true`	object containing the following possible values:\ `"variants": { "italic": false, "bold": false }`

More information about how to customize text fields can be found in our API Reference.

Fields creation

Method A: Using Smart Anchors

Limits to use Smart Anchors

Document upload and Smart Anchors

Signature Field

Mention Field

Checkbox Field

Text Field (Text input)

Radio Button Field

Method B: Manual Field creation

How to find x, y coordinates for your Fields

Signature Field

Mention Field

Checkbox Field

Text Field (Text input)

Read-only Text Fields

Radio Button Fields

Fields style customisation

Rules on using the `font` Object in Payload

Method A: Using Smart Anchors

Limits to use Smart Anchors

Document upload and Smart Anchors

Signature Field

Mention Field

Checkbox Field

Text Field (Text input)

Radio Button Field

Method B: Manual Field creation

How to find x, y coordinates for your Fields

Signature Field

Mention Field

Checkbox Field

Text Field (Text input)

Read-only Text Fields

Radio Button Fields

Fields style customisation

Rules on using the font Object in Payload

Rules on using the `font` Object in Payload