Create Document: Fields
This section intends to outline in detail how to work with fields when creating a document or using a template.
Field Types
The following field types are the supported by the Xodo Sign API:
signature
: Signature fieldinitials
: Initials fielddate_signed
: Date Signed fieldnote
: Multi-line text fieldtext
: Single-line text fieldcheckbox
: Checkboxradio
: Radio Buttondropdown
: Dropdown Menuattachment
: Attachment field
signature
fields to be completed by each signer. Furthermore, field date signed
will be populated with the current date.
Sample Field
A document's fields
object can contain multiple field arrays. Below you will see an
example field:
{ "type": "text", "x": "97.54942119323242", "y": "123.7079252003562", "width": "55", "height": "17", "page": "1", "signer": "1", "name": "Full Name", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI", "validation_type": "", "value": "" }
Field Values
The value
parameter is used to pre-fill fields or to fill Merge
Fields when using a template. This paramter is only supported by specific fields and
comes with functions individual to most field types:
signature
: not supportedinitials
: not supporteddate_signed
: not supportednote
: Enter text contenttext
: Enter text contentcheckbox
: Set to0
to uncheck; set to1
to check.radio
: Set to0
to uncheck; set to1
to check.dropdown
: Set to option value to select option.attachment
: not supported
Field Style
A field's styling can be adjusted using 4 parameters:
text_size
: Set to your preferred font size number (string or integer), e.g.16
.text_color
: Set to your preferred HEX color code, e.g.#FF0000
text_font
: Set to the font identifier of your preferred font, e.g.arial
.text_style
: The lettersB
for bold,U
for underlined andI
for italic, in an order of your choice. Example:BUI
Supported Fonts:
arial
: Arialcalibri
: Calibricourier_new
: Courier Newhelvetica
: Helveticageorgia
: Georgiatimes_new_roman
: Times New Roman
Field Style
Please find below all available styling parameters in use:
{ [...] "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI", [...] }
Field Validation
There are 3 types of field validation that can be enabled:
letters_only
Requires the given field value to contain letters only.numbers_only
: Requires the given field value to contain numbers only.email_address
: Requires the given field value to be a syntactically valid email address.
Field Validation
Please find below the field validation parameter in use:
{ [...] "field_validation": "letters_only", [...] }
Signature Fields
Signature fields come with a basic structure and very little settings:
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 120 ) |
height | The field's height in pixels. (Minimum recommended width: 35 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
Sample Signature Field
Find below an example signature
field:
{ "type": "signature", "x": "120.43", "y": "479.02", "width": "120", "height": "35", "page": "2", "signer": "1", "identifier": "unique_field_identifier_1", "required": 1 }
Initials Fields
Initials fields come with the same settings like signature fields:
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 43 ) |
height | The field's height in pixels. (Minimum recommended width: 43 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
Sample Initials Field
Find below an example initials
field:
{ "type": "initials", "x": "230.43", "y": "579.02", "width": "43", "height": "43", "page": "2", "signer": "1", "identifier": "unique_field_identifier_1", "required": 1 }
Date Signed Fields
Date Signed fields are used to stamp the exact date a signature was placed on a document. They are non-editable in content, but their styling can be adjusted.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 60 ) |
height | The field's height in pixels. (Minimum recommended width: 17 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
identifier | The field's Field Identifier. |
text_size | Set to your preferred font size number (string or integer), e.g. 16 . |
text_color | Set to your preferred HEX color code, e.g. #FF0000 |
text_font | Set to the font identifier of your preferred font, e.g. arial . Jump to
section Field Style
to learn about supported fonts.
|
text_style | The letters B for bold, U for underlined and I
for italic, in an order of your choice. Example: BUI |
Sample Date Signed Field
Find below an example date_signed
field:
{ "type": "date_signed", "x": "97.54942119323242", "y": "123.7079252003562", "width": "60", "height": "17", "page": "1", "signer": "1", "identifier": "unique_field_identifier_1", "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI" }
Note Fields
Note fields are used to place multi-line inputs/textareas or text paragraphs.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 55 ) |
height | The field's height in pixels. (Minimum recommended width: 17 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
readonly | Set to 1 in order to make this field a Read-Only
Field.
|
text_size | Set to your preferred font size number (string or integer), e.g. 16 . |
text_color | Set to your preferred HEX color code, e.g. #FF0000 |
text_font | Set to the font identifier of your preferred font, e.g. arial . Jump to
section Field Style
to learn about supported fonts.
|
text_style | The letters B for bold, U for underlined and I
for italic, in an order of your choice. Example: BUI |
validation_type | Enable Field
Validation for this field. Available validation types are
email_address , letters_only and numbers_only .
|
value | Specify text content to pre-fill field. |
Sample Note Field
Find below an example note
field:
{ "type": "note", "x": "97.54942119323242", "y": "123.7079252003562", "width": "55", "height": "17", "page": "1", "signer": "1", "name": "Full Name", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI", "validation_type": "", "value": "" }
Text Fields
Text fields are used to place single-line text inputs.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 55 ) |
height | The field's height in pixels. (Minimum recommended width: 17 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
readonly | Set to 1 in order to make this field a Read-Only
Field.
|
text_size | Set to your preferred font size number (string or integer), e.g. 16 . |
text_color | Set to your preferred HEX color code, e.g. #FF0000 |
text_font | Set to the font identifier of your preferred font, e.g. arial . Jump to
section Field Style
to learn about supported fonts.
|
text_style | The letters B for bold, U for underlined and I
for italic, in an order of your choice. Example: BUI |
validation_type | Enable Field
Validation for this field. Available validation types are
email_address , letters_only and numbers_only .
|
value | Specify text content to pre-fill field. |
Sample Text Field
Find below an example text
field:
{ "type": "text", "x": "97.54942119323242", "y": "123.7079252003562", "width": "55", "height": "17", "page": "1", "signer": "1", "name": "Full Name", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI", "validation_type": "", "value": "" }
Checkbox Fields
Checkbox fields come with a fixed pixel width and height of 14x14
.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
readonly | Set to 1 in order to make this field a Read-Only
Field.
|
value | Set to 0 or leave empty to mark unchecked; Set to 1 to mark
checked
|
Sample Checkbox Field
Find below an example checkbox
field:
{ "type": "checkbox", "x": "97.54942119323242", "y": "123.7079252003562", "page": "1", "signer": "1", "name": "Receive Newsletter", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "value": "" }
Radio Button Fields
Radio Button fields come with a fixed pixel width and height of 14x14
. The
additional group
parameter is used to identify radio button groups.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
readonly | Set to 1 in order to make this field a Read-Only
Field.
|
value | Set to 0 or leave empty to mark unchecked; Set to 1 to mark
checked
|
group | This parameter is used to identify radio button groups. radio fields
belonging to the same group must carry the same group parameter. Please note that this
parameter must be numeric.
|
Sample Radio Button Field
Find below two example radio
fields:
[{ "type": "radio", "x": "97.54942119323242", "y": "123.7079252003562", "page": "1", "signer": "1", "name": "Credit Card", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "value": "1", "group": "1" }, { "type": "radio", "x": "102.54342119323242", "y": "123.7079252003562", "page": "1", "signer": "1", "name": "PayPal", "identifier": "unique_field_identifier_2", "required": 1, "readonly": 0, "value": "", "group": "1" }]
Dropdown Fields
Dropdown fields can be used to enable signers of a document to easily choose between multiple
options. Using the API's options
parameter these options can be specified.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 63 ) |
height | The field's height in pixels. (Minimum recommended width: 19 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
text_size | Set to your preferred font size number (string or integer), e.g. 16 . |
text_color | Set to your preferred HEX color code, e.g. #FF0000 |
text_font | Set to the font identifier of your preferred font, e.g. arial . Jump to
section Field Style
to learn about supported fonts.
|
text_style | The letters B for bold, U for underlined and I
for italic, in an order of your choice. Example: BUI |
required | Set to 1 in order to make this field a Required
Field.
|
readonly | Set to 1 in order to make this field a Read-Only
Field.
|
value | Set to an existing option in order to pre-select it. |
options | This parameter must contain a simple JSON array containing all available options of a
dropdown field. In order to pre-select an option, simply set the value
parameter to the option value.
|
Sample Dropdown Field
Find below an example dropdown
field:
{ "type": "dropdown", "x": "97.54942119323242", "y": "123.7079252003562", "width": "55", "height": "17", "page": "1", "signer": "1", "name": "Full Name", "identifier": "unique_field_identifier_1", "required": 1, "readonly": 0, "text_size": 16, "text_color": "#FF0000", "text_font": "arial", "text_style": "BUI", "validation_type": "", "value": "Option 1", "options": [ "Option 1", "Option 2", "Option 3" ] }
Attachment Fields
Attachment fields are used to enable signers to upload one or multiple files.
Name | Description |
---|---|
type | Field type. Click here to view all available field types. |
x | The field's horizontal margin from the left side of the document in pixels. |
y | The field's vertical margin from the top of the document in pixels. |
width | The field's width in pixels. (Minimum recommended width: 28 ) |
height | The field's height in pixels. (Minimum recommended width: 28 ) |
page | The number of the document page where the field should be placed. |
signer | The unique ID of the signer this field should be assigned to. If this field should
become a No Signer
field, please set this parameter to OWNER .
|
name | The field's Field Label. |
identifier | The field's Field Identifier. |
required | Set to 1 in order to make this field a Required
Field.
|
Sample Attachment Field
Find below an example attachment
field:
{ "type": "attachment", "x": "97.54942119323242", "y": "123.7079252003562", "width": "28", "height": "28", "page": "1", "signer": "1", "name": "Attachment", "identifier": "unique_field_identifier_1", "required": 1 }