Meet our new brand: eversign is now Xodo Sign! Learn more

Getting Started

Methods

Create Document: Fields

Bulk Sending

Hidden Tags

Embedded Signing

Embedded Requesting

OAuth 2.0

Webhooks

Libraries

Stay up to date

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 field
  • initials: Initials field
  • date_signed: Date Signed field
  • note: Multi-line text field
  • text: Single-line text field
  • checkbox: Checkbox
  • radio: Radio Button
  • dropdown: Dropdown Menu
  • attachment: Attachment field
No Fields If you are creating a document and no fields are specified within your HTTP POST request body the Xodo Sign API will automatically append to your document an additional signature page containing 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 supported
  • initials: not supported
  • date_signed: not supported
  • note: Enter text content
  • text: Enter text content
  • checkbox: Set to 0 to uncheck; set to 1 to check.
  • radio: Set to 0 to uncheck; set to 1 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 letters B for bold, U for underlined and I for italic, in an order of your choice. Example: BUI
Compatibility Plese note that only text-based field types (Date Signed, Note, Text, Dropdown) support style options.

Supported Fonts:

  • arial: Arial
  • calibri: Calibri
  • courier_new: Courier New
  • helvetica: Helvetica
  • georgia: Georgia
  • times_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 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
}