Create Document: Fields

Table of contents
Getting Started
Methods
Create Document: Fields
Bulk Sending
Hidden Tags
Embedded Signing
Embedded Requesting
OAuth 2.0
Webhooks
Libraries
Stay up to date

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

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