Guides
Status PageRoadmapTestimoniesShare feedback

Fields creation

Suggest Edits

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}}
VariableDescriptionValue
signer_indexindex 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
widthwidth of the signature field, starting at the top left of the text anchor.min 85, max 580
heightheight 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%}}
VariableDescriptionValue
signer_indexindex 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_contentThe 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}}
VariableDescriptionValue
signer_indexindex 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
sizeSize 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
optionalSet 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
checkedSet if the checkbox is initially checked when the Signer sees the document.- t for true

- f for false
nameA 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}}
AttributeDescriptionValue
signer_indexIndex 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_lengthMaximal count of characters in the Text Field.
widthWidth 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.
heightHeight 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.
questionQuestion which is going to be asked to the Signer.Custom string.
instructionCan be used to give more instructions to the Signer, for example, a text to copy.Custom string.

Optional.
optionalIf 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}}
AttributeDescriptionValue
signer_indexIndex 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
sizeSize 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_nameThis 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
optionalIf 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_nameThis 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:

AttributeDescription
document_idId of the document on which the field will be added
typeThe type of field. See below.
pageThe page of the document on which the field is positoned
xThe top-left x coordinates of the field with the x-axis starting at the left of the page
yThe 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

ParameterOptionalDetails
heighttrue- Default value is 37 px

- 37 px is the minimum authorized
- 1000 px is the maximum authorized
widthtrue- 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

ParameterOptionalDetails
widthtrue- 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.
mentionfalse- 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

ParameterOptionalDetails
nametrue- 128 is the maximum number of characters allowed
optionalfalse- If set to true, the checkbox has to be checked by the signer in order to sign
checkedfalse- If set to true, the checkbox will be pre-checked when the signer will open the document
sizefalse- 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)

ParameterOptionalDetails
max_lengthfalse- Maximal count of characters in the Text Field
optionalfalse- If set to true, the signer has to fill the text in order to sign
questionfalse- The question for the signer

- 255 is the maximum number of characters allowed
instructiontrue- Can be used to give more instructions to the Signer

- 10000 is the maximum number of characters allowed
widthtrue- Default value is 198 px

- 24 px is the minimum authorized
heighttrue- 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

ParameterOptionalDetails
pagefalsePage in which the Read-only Text Field must be included
xfalsex position of the Read-only Text Field in the Document
yfalsey position of the Read-only Text Field in the Document
widthtrueIf not set, the width is automatically calculated with the mention length
heighttrueThe 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
textfalseText 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

ParameterOptionalDetails
optionalfalse- If set to true, the signer has to check at least one radio in order to sign
nametrue- The name of the radio group

- 128 is the maximum number of characters allowed

Radio Button (list of)

ParameterOptionalDetails
nametrue- The name of the radio button

- 128 is the maximum number of characters allowed
sizetrue- 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.
ParameterOptionalDetails
familytrue- string of font family name (valid values are available in the API Reference)

- default value is Inconsolata
colortrue- hexa string of the desired color

- default value is #000000
sizetrue- 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
variantstrueobject 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.

Updated 7 months ago