Methods

List Businesses

A list of existing businesses on your Xodo Sign account can be accessed by making a simple HTTP GET call to the Xodo Sign API's business endpoint.

API Response Objects:

Name	Description
business_id	Returns the Business ID of the given business.
business_status	Returns `1` if the given business is active; or `2` if the given business is inactive or deleted.
business_identifier	Returns the Workspace URL (sub domain) of the given business.
business_name	Returns the Business Name of the given business.
creation_time_stamp	Returns the creation date and time of the given business as UNIX time stamp.
is_primary	Returns `1` if the given business is the Primary Business.

List Businesses `HTTP GET`

API Request

https://api.eversign.com/business
	? access_key = YOUR_ACCESS_KEY

API Response

[{
	"business_id": 1,
	"business_status": 1,
	"business_identifier": "first",
	"business_name": "My First Business",
	"creation_time_stamp": 1490203825,
	"is_primary": 1
}, {
	"business_id": 2,
	"business_status": 1,
	"business_identifier": "second",
	"business_name": "My Second Business",
	"creation_time_stamp": 1490203925,
	"is_primary": 0
}]

Create Document

In order to create a document an HTTP POST request containing a series of parameters and objects to the API's document endpoint is required. All parameters and objects are specified below:

Name	Description	Default
sandbox	Set to `1` in order to enable Sandbox Mode.	`0`
is_draft	Set to `1` in order to save this document as a draft.	`0`
title	This parameter is used in order to specify a document title.	-
message	This parameter is used in order to specify a document message.	-
use_signer_order	Set to `1` in order to enable Signing Order for this document.	`0`
reminders	Set to `1` in order to enable Auto Reminders for this document.	`0`
require_all_signers	Set to `1` in order to require all signers to sign to complete this document.	`0`
custom_requester_name	This parameter can be used to specify a custom requester name for this document. If used, all email communication related to this document and signing-related notifications will carry this name as the requester (sender) name.	-
custom_requester_email	This parameter can be used to specify a custom requester email address for this document. If used, all email communication related to this document and signing-related notifications will carry this email address as the requester (sender) email address.	-
redirect	This parameter is used to specify a custom completion redirect URL. If empty, the default Post-Signature Completion URL specified in your Xodo Sign Business or the Xodo Sign signature completion page will be used.	Default URL
redirect_decline	This parameter is used to specify a custom decline redirect URL. If empty, the default Post-Signature Decline URL specified in your Xodo Sign Business or the Xodo Sign signature declined page will be used.	Default URL
client	This parameter is used to specify an internal reference for your application, such as an identification string of the server or client making the API request.	-
expires	This parameter is used to specify a custom expiration date for your document. (Required format: Unix Time Stamp) If empty, the default document expiration period specified in your business settings will be used.	Default Expiration
embedded_signing_enabled	Set to `1` in order to enable Embedded Signing for this document. If enabled, this document can be signed within an iFrame embedded on your website and email authentication will be disabled.	`0`
flexible_signing	Set to `1` in order to create this document without specifying fields. Signers will be able to place their own fields during signing.	`0`
use_hidden_tags	Set to `1` to parse hidden tags placed on your document.	`0`

files Object
Document files can be uploaded to your document either by providing a URL, a reference to an existing file ID or through a base64 string. This object can contain multiple sub arrays.

Name	Description	Details
name	Specify a name for the file to be uploaded.	Required
file_id	Specify an existing file reference ID in order to use a specific file that has already been uploaded once using your Xodo Sign account. Files can be uploaded using the API's built-in File Upload Method ».	Required
file_url	A URL leading to the file you would like to upload as your document file. Click here to view all supported file formats.	Required
file_base64	Specify a base64 string of the file you would like to upload. Click here to view all supported file formats.	Required

Required Please specify only one of three upload parameters (file_url, file_id or file_base64) for each sub array.

signers Object
This object must contain a sub array for each signer of the document being created. Each sub array requires a unique ID, name and email address.

Name	Description	Details
id	A unique identification number (integer) for this signer. We recommend numbering your signers from 1 to X.	Required
name	This parameter is used to specify the full name of the current signer.	Required
email	This parameter is used to specify the email address of the current signer.	Required
order	If the `use_signer_order` parameter is set to `1`, set this parameter to the signer order number of the current signer.	Optional
pin	This parameter is used to specify a Signer PIN for the current signer.	Optional
signer_authentication_sms_enabled	This parameter is used to specify if signer authentication by SMS is enabled.	Optional
signer_authentication_phone_number	If signer authentication by SMS is enabled, this parameter is used to specify the phone number to which SMS validation will be delivered. ITU call prefix can start both with 00 or + sign.	Optional
message	This parameter can be used to specify a custom message (upon document delivery) for the current signer. Please note that for the current signer the general document message will be overriden by this parameter.	Optional
deliver_email	This parameter is only applicable if `embedded_signing_enabled` is set to `1`. By default, signers of embedded documents are not notified (default: `deliver_email: 0`) about a new document to be signed. Set `deliver_email` to `1` to send a notification email to this signer anyway.	Optional
language	This parameter is used to specify the language in which signing notifications (emails), the document status page and the signature process will appear for this signer.	Optional

At least one signer Please note that at least one signer sub array must be specified.

Signer Authentication Overages Signer authentication by SMS has limited credits. Exceeding these credits is allowed for all non-free accounts and it will result in additional charges (overages).

recipients Object
This object can contain a sub array for each CC of the document to be signed.

Name	Description	Details
name	This parameter is used to specify the full name of the current CC.	Required
email	This parameter is used to specify the email address of the current CC.	Required
language	This parameter is used to specify the language in which document CC notifications (emails) and the document status page will appear for this CC.	Optional

meta Object
This object contains optional key-value data that should be attached to the document. This data will be included when making a GET call for the document created.

fields Object
The fields that should be placed on the document, expressed as a 2-dimensional JSON array. One array of fields is required for each file provided in the files object. If a file has no fields, an empty array must be provided. This structure is illustrated below:

In our example above, the fields of type signature and text will be placed onto the pages of the first document file uploaded, and the fields of type note and attachment will be placed onto the second document file uploaded.

Name	Description
type	The type of the field to be placed. You can view a list of all available field types by clicking here.
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.
height	The field's height 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.
validation_type	Enable Field Validation for this field. Available validation types are `email_address`, `letters_only` and `numbers_only`.
text_style	The letters `B` for bold, `U` for underlined and `I` for italic, in an order of your choice. Example: `BUI`
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_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`
value	Set to `1` to mark `checkbox` or `radio` fields checked; or specify text content for `note` or `text` fields. For `dropdown` fields, set this parameter to an option value 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.
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.

No Fields If no signature fields are specified within your document creation request 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.

Create Document `HTTP POST`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

{
	"sandbox": 0,
	"is_draft": 0,
	"embedded": 0,
	"title": "Sample Document",
	"message": "This is my general document message.",
	"use_signer_order": 1,
	"reminders": 1,
	"require_all_signers": 1,
	"custom_requester_name": "",
	"custom_requester_email": "",
	"redirect": "https://myredirect.com/completed",
	"redirect_decline": "https://myredirect.com/declined",
	"client": "",
	"embedded_signing_enabled": 0,
	"flexible_signing": 0,
	"use_hidden_tags": 0,
	"files": [{
		"name": "My Document File",
		"file_url": "https://eversign.com/uploads/sample-document.pdf",
		"file_id": "",
		"file_base64": ""
	}, {
		"name": "My Second Document File",
		"file_url": "https://eversign.com/uploads/sample-document.pdf",
		"file_id": "",
		"file_base64": ""
	}],
	"signers": [{
		"id": 1,
		"name": "Paul McSign",
		"email": "paul@mcsign.com",
		"order": 1,
		"pin": "3874",
		"signer_authentication_sms_enabled": 0,
		"signer_authentication_phone_number": "+000000000000000",
		"message": "This is my custom message to Paul.",
		"deliver_email": "",
		"language": "en"
	}, {
		"id": 2,
		"name": "Julian McSign",
		"email": "julian@mcsign.com",
		"order": 2,
		"pin": "3944",
		"message": "",
		"deliver_email": "",
		"language": "en"
	}],
	"recipients": [{
		"name": "Jane McSign",
		"email": "jane@mcsign.com",
		"language": "en"
	}, {
		"name": "Frank McSign",
		"email": "frank@mcsign.com",
		"language": "en"
	}],
	"meta": {
		"some_key": "some_value",
		"another_key": "another_value"
	},
	"fields": [
        [
            {
                "merge": 0,
                "identifier": "unique_field_identifier_1",
                "name": "Full Name",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 119.42348754448399,
                "y": 169.54655093793733,
                "page": 1,
                "width": 148,
                "height": 18,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_2",
                "name": "Title",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 109.25978647686833,
                "y": 209.37132254666102,
                "page": 1,
                "width": 55,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_3",
                "name": "Company",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 142.7153024911032,
                "y": 247.92509080617012,
                "page": 1,
                "width": 105,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_4",
                "name": "Email",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 115.18861209964413,
                "y": 288.1735301979653,
                "page": 1,
                "width": 154,
                "height": 18,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_5",
                "name": "Signature",
                "options": "",
                "group": "",
                "value": "",
                "type": "signature",
                "x": 143.1387900355872,
                "y": 318.2539427960439,
                "page": 1,
                "width": 120,
                "height": 35,
                "signer": 1,
                "validation_type": "",
                "required": 1,
                "readonly": 0,
                "text_size": "",
                "text_color": "",
                "text_style": "",
                "text_font": ""
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_6",
                "name": "Date Signed",
                "options": "",
                "group": "",
                "value": "",
                "type": "date_signed",
                "x": 111.37722419928825,
                "y": 365.70473450005505,
                "page": 1,
                "width": 60,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            }
        ],
        []
    ]
}

API Response

If successful, the Xodo Sign API will return the entire document in JSON format. In order to see how this response looks like, please jump to the Get Document section.

Create Template

In order to create a template an HTTP POST request containing a series of parameters and objects to the API's document endpoint is required. All parameters and objects are specified below:

Name	Description	Default
sandbox	Set to `1` in order to enable Sandbox Mode.	`0`
is_draft	Set to `1` in order to save this template as a draft.	`0`
is_template	This parameter must be set to `1` in order to confirm template creation.	`1`
title	This parameter is used in order to specify a template title.	-
message	This parameter is used in order to specify a template message.	-
use_signer_order	Set to `1` in order to enable Signing Order for this template.	`0`
reminders	Set to `1` in order to enable Auto Reminders for this template.	`0`
require_all_signers	Set to `1` in order to require all signers to sign to complete this template.	`0`

files Object
Template files can be uploaded to your template either by providing a URL, a reference to an existing file ID or through a base64 string. This object can contain multiple sub arrays.

Name	Description	Details
name	Specify a name for the file to be uploaded.	Required
file_id	Specify an existing file reference ID in order to use a specific file that has already been uploaded once using your Xodo Sign account. Files can be uploaded using the API's built-in File Upload Method ».	Required
file_url	A URL leading to the file you would like to upload as your template file. Click here to view all supported file formats.	Required
file_base64	Specify a base64 string of the file you would like to upload. Click here to view all supported file formats.	Required

Required Please specify only one of three upload parameters (file_url, file_id or file_base64) for each sub array.

signers Object
This object must contain a sub array for each signer role of the template being created. Each sub array requires a unique ID and role name.

Name	Description	Details
id	A unique identification number (integer) for this signer. We recommend numbering your signers from 1 to X.	Required
role	This parameter is used to specify a name for this signer role (e.g. "Client").	Required
name	This parameter is used to pre-fill a full name for this signer role.	Optional
email	This parameter is used to pre-fill an email address for this signer role.	Optional
order	If the `use_signer_order` parameter is set to `1`, set this parameter to the signer order number of the current signer role.	Optional
pin	This parameter is used to pre-fill a Signer PIN for the current signer role.	Optional
message	This parameter can be used to specify a custom message (upon document delivery) for the current signer role. Please note that for the current signer role the general template message will be overriden by this parameter.	Optional
language	This parameter is used to pre-fill the language in which signing notifications (emails), the document status page and the signature process will appear for this signer role.	Optional
required	If the `required` parameter is set to `1`, this signer role will require a name and email address the template is used.	Optional

Templates without roles You can also choose to create your template without providing a role. In this case, it will only act as an appendix document (e.g. terms and conditions document) and cannot contain any signer-related fields.

recipients Object
This object can contain a sub array for each CC of the document to be signed.

Name	Description	Details
role	This parameter is used to specify a name for this signer role (e.g. "Client").	Required
name	This parameter is used to pre-fill a full name for this signer role.	Optional
email	This parameter is used to pre-fill an email address for this signer role.	Optional
language	This parameter is used to specify the language in which document CC notifications (emails) and the document status page will appear for this CC.	Optional
required	If the `required` parameter is set to `1`, this CC role will require a name and email address when the template is used.	Optional

meta Object
This object contains optional key-value data that should be attached to the document. This data will be included when making a GET call for the document created.

fields Object
The fields that should be placed on the template, expressed as a 2-dimensional JSON array. One array of fields is required for each file provided in the files object. If a file has no fields, an empty array must be provided. This structure is illustrated below:

In our example above, the fields of type signature and text will be placed onto the pages of the first template file uploaded, and the fields of type note and attachment will be placed onto the second template file uploaded.

Name	Description
type	The type of the field to be placed. You can view a list of all available field types by clicking here.
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.
height	The field's height 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.
merge	Set to `1` in order to make this field a Merge Field.
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.
validation_type	Enable Field Validation for this field. Available validation types are `email_address`, `letters_only` and `numbers_only`.
text_style	The letters `B` for bold, `U` for underlined and `I` for italic, in an order of your choice. Example: `BUI`
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_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`
value	Set to `1` to mark `checkbox` or `radio` fields checked; or specify text content for `note` or `text` fields. For `dropdown` fields, set this parameter to an option value 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.
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.

Create Template `HTTP POST`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

{
	"sandbox": 0,
	"is_template": 1,
	"is_draft": 0,
	"title": "test_title",
	"message": "test_message",
	"use_signer_order": 0,
	"reminders": 0,
	"require_all_signers": 0,
	"files": [{
		"name": "My Template File",
		"file_url": "https://eversign.com/uploads/sample-document.pdf",
		"file_id": "",
		"file_base64": ""
	}],
	"signers": [{
		"id": 1,
		"role": "Client",
		"name": "",
		"email": "",
		"required": 1
	}],
	"recipients": [],
	"meta": {
		"some_key": "some_value",
		"another_key": "another_value"
	},
	"fields": [
		[
            {
                "merge": 0,
                "identifier": "unique_field_identifier_1",
                "name": "Full Name",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 119.42348754448399,
                "y": 169.54655093793733,
                "page": 1,
                "width": 148,
                "height": 18,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_2",
                "name": "Title",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 109.25978647686833,
                "y": 209.37132254666102,
                "page": 1,
                "width": 55,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_3",
                "name": "Company",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 142.7153024911032,
                "y": 247.92509080617012,
                "page": 1,
                "width": 105,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_4",
                "name": "Email",
                "options": "",
                "group": "",
                "value": "",
                "type": "text",
                "x": 115.18861209964413,
                "y": 288.1735301979653,
                "page": 1,
                "width": 154,
                "height": 18,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_5",
                "name": "Signature",
                "options": "",
                "group": "",
                "value": "",
                "type": "signature",
                "x": 143.1387900355872,
                "y": 318.2539427960439,
                "page": 1,
                "width": 120,
                "height": 35,
                "signer": 1,
                "validation_type": "",
                "required": 1,
                "readonly": 0,
                "text_size": "",
                "text_color": "",
                "text_style": "",
                "text_font": ""
            },
            {
                "merge": 0,
                "identifier": "unique_field_identifier_6",
                "name": "Date Signed",
                "options": "",
                "group": "",
                "value": "",
                "type": "date_signed",
                "x": 111.37722419928825,
                "y": 365.70473450005505,
                "page": 1,
                "width": 60,
                "height": 17,
                "signer": 1,
                "validation_type": "",
                "required": 0,
                "readonly": 0,
                "text_size": 10,
                "text_color": "#000000",
                "text_style": "",
                "text_font": "arial"
            }
        ]
	]
}

API Response

If successful, the Xodo Sign API will return the entire template in JSON format. In order to see how this response looks like, please jump to the Get Template section.

Use Template

An existing template can be used by making an HTTP POST request to the document endpoint containing some key parameters. All optional and required parameters are listed in the table below.

Look up your template Before using a template you might want to access it in order to review its signer and recipient roles, fields and other settings. In order to look up your template, a GET Template request is required.

Name	Description
sandbox	Set to `1` in order to enable Sandbox Mode.
template_id	Set to the Template ID (Document Hash) of the template you would like to use.
title	This parameter is used in order to specify a document title.
message	This parameter is used in order to specify a document message.
custom_requester_name	This parameter can be used to specify a custom requester name for this document. If used, all email communication related to this document and signing-related notifications will carry this name as the requester (sender) name.
custom_requester_email	This parameter can be used to specify a custom requester email address for this document. If used, all email communication related to this document and signing-related notifications will carry this email address as the requester (sender) email address.
redirect	This parameter is used to specify a custom completion redirect URL. If empty, the default Post-Signature Completion URL specified in your Xodo Sign Business or the Xodo Sign signature completion page will be used.
redirect_decline	This parameter is used to specify a custom decline redirect URL. If empty, the default Post-Signature Decline URL specified in your Xodo Sign Business or the Xodo Sign signature declined page will be used.
client	This parameter is used to specify an internal reference for your application, such as an identification string of the server or client making the API request.
expires	This parameter is used to specify a custom expiration date for your document. (Required format: Unix Time Stamp) If empty, the default document expiration period specified in your business settings will be used.
embedded_signing_enabled	Set to `1` in order to enable Embedded Signing for this document. If enabled, this document can be signed within an iFrame embedded on your website and email authentication will be disabled.

signers Object
This object must contain a sub array for each signing role of your template. Each sub array must contain the role name, signer name and signer email address. At this point, an optional Signer PIN and message can be specified as well.

Name	Description	Details
role	The name of this signing role.	Required
name	This parameter is used to specify the full name of the current signer.	Optional
email	This parameter is used to specify the email address of the current signer.	Optional
pin	This parameter is used to specify a Signer PIN for the current signer.	Optional
signer_authentication_sms_enabled	This parameter is used to specify if signer authentication by SMS is enabled.	Optional
signer_authentication_phone_number	If signer authentication by SMS is enabled, this parameter is used to specify the phone number to which SMS validation will be delivered. ITU call prefix can start both with 00 or + sign.	Optional
message	This parameter can be used to specify a custom message (upon document delivery) for the current signer. Please note that for the current signer the general document message will be overriden by this parameter.	Optional
deliver_email	This parameter is only applicable if `embedded_signing_enabled` is set to `1`. By default, signers of embedded documents are not notified (default: `deliver_email: 0`) about a new document to be signed. Set `deliver_email` to `1` to send a notification email for this role anyway.	Optional
language	This parameter is used to specify the language in which signing notification emails, the document status page and the signature process will appear for this signer. Click here for a list of supported languages.	Optional

All required roles must be specified Please note that all required roles must be specified in order to use a template.

Signer Authentication Overages Signer authentication by SMS has limited credits. Exceeding these credits is allowed for all non-free accounts and it will result in additional charges (overages).

recipients Object
This object must contain a sub array for each recipient (CC) role of your template. Each sub array must contain the role name, CC name and CC email address.

Name	Description	Details
role	The name of this CC role.	Required
name	This parameter is used to specify the full name of the current CC.	Required
email	This parameter is used to specify the email address of the current CC.	Required
language	This parameter is used to specify the language in which document CC notifications (emails) and the document status page will appear for this CC. Click here for a list of supported languages.	Optional

fields Object
This object must contain a sub array for each Merge Field of this template.

Name	Description	Details
identifier	The field's Field Identifier.	Required
value	The field's value. Click here to see a list of allowed field values per field.	Required

Use Template `HTTP POST`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

{
	"sandbox": 0,
	"template_id": "j6yMcaF4gQBIIQ",
	"title": "My New Document",
	"message": "This is my message.",
	"custom_requester_name": "",
	"custom_requester_email": "",
	"redirect": "https://myredirect.com/completed",
	"redirect_decline": "https://myredirect.com/declined",
	"client": "",
	"expires": 1494276966,
	"embedded_signing_enabled": 0,
	"signers": [{
		"role": "Sales Rep",
		"name": "Paul McSign",
		"email": "paul@mcsign.com",
		"pin": "1234",
		"signer_authentication_sms_enabled": 1,
		"signer_authentication_phone_number": "+43123221234",
		"message": "This is my custom message to Paul.",
		"deliver_email": "",
		"language": "en"
	}, {
		"role": "Client",
		"name": "Julian McSign",
		"email": "julian@mcsign.com",
		"pin": "4321",
		"message": "",
		"deliver_email": "",
		"language": "en"
	}],
	"recipients": [{
		"role": "Assistant",
		"name": "Jane McSign",
		"email": "jane@mcsign.com",
		"language": "en"
	}, {
		"role": "Finance Department",
		"name": "Frank McSign",
		"email": "frank@mcsign.com",
		"language": "en"
	}],
	"fields": [{
		"identifier": "unique_field_identifier_1",
		"value": "Merge Field Content"
	}, {
		"identifier": "unique_field_identifier_2",
		"value": "Other Merge Field Content"
	}]
}

API Response

If successful, the Xodo Sign API will return the created document in JSON format. In order to see how a response like this looks like, please jump to the Get Document section.

Get Document/Template

An existing document or template can be accessed using a straightforward HTTP GET call. If successful, the API will return the entire document/template data set. All the objects contained in the API response are described below:

Name	Description
document_hash	The unique hash (identification) of the requested document.
requester_email	The email address of the document sender.
custom_requester_name	If specified during document creation, this parameter will contain your custom requester name.
custom_requester_email	If specified during document creation, this parameter will contain your custom requester email address.
is_draft	Returns `1` if the requested document is in draft status.
is_template	Returns `1` if the requested document is a template.
is_completed	Returns `1` if the signing of requested document has been completed.
is_archived	Returns `1` if the requested document is archived.
is_deleted	Returns `1` if the requested document is deleted.
is_trashed	Returns `1` if the requested document is trashed.
is_cancelled	Returns `1` if the requested document is cancelled.
embedded	Returns `1` if the requested document is a Template Link.
in_person	Returns `1` if In-Person Signing is active for the requested document.
permission	Returns `1` if the requested template is available to its creator only, or returns `2` if the requested template is available to all Staff members (Templates only).
template_id	Returns a template hash if the requested document has been created from a template.
title	Returns the title of the requested document.
message	Returns the general message of the requested document.
use_signer_order	Returns `1` if a Signing Order is active for the requested document.
reminders	Returns `1` if Auto Reminders are enabled for the requested document.
require_all_signers	Returns `1` if all signers are required to sign to complete the requested document.
redirect	Returns the completion redirect URL for the requested document.
redirect_decline	Returns the decline redirect URL for the requested document.
client	Returns your internal reference for this document (if specified during creation).
created	Returns the requested document's creation UNIX time stamp.
completed	Returns the requested document's completion UNIX time stamp.
expires	Returns the requested document's expiration UNIX time stamp.
embedded_signing_enabled	Returns `1` if Embedded Signing is enabled for this document.
flexible_signing	Returns `1` if this document was created without any fields placed. The signers of this document are required to place fields during signing. [Only available for documents]

files Object

Name	Description
name	Returns the name of this document file.
file_id	Returns the file ID of this document file.
pages	Returns the number of pages contained in this document file.

signers Object

Name	Description
id	Returns the unique signer ID of this signer.
name	Returns the full name of this signer.
email	Returns the email address of this signer.
role	Returns the role name of this signer role (Templates only).
order	Returns the signing order number of this signer.
pin	Returns the Signer PIN assigned to this signer.
signer_authentication_sms_enabled	This parameter is used to specify if signer authentication by SMS is enabled.
signer_authentication_phone_number	If signer authentication by SMS is enabled, this parameter is used to specify the phone number to which SMS validation will be delivered. ITU call prefix can start both with 00 or + sign.
message	Returns the custom message to this signer (if specified).
signed	Returns `1` if this signer has signed the requested document.
signed_timestamp	Returns a UNIX time stamp of the date of signature.
required	Returns `1` if this signing role is required (Templates only).
deliver_email	Returns `1` if an initial notification email was sent to the signer. This object is only applicable if `embedded_signing_enabled` is set to `1`.
language	Returns the 2-letter language code of the language chosen for this signer.
declined	Returns `1` if this signer has declined to sign.
declined_timestamp	Returns a UNIX timestamp of the date when the signer declined the document. This field is only applicable if `decline` is set to `1`.
declined_reason	Returns a reason for declination stated by the signer who declined the document. This field is only applicable if `decline` is set to `1`.
removed	Returns `1` if this signer was removed.
bounced	Returns `1` if the signer's email address could not be reached.
sent	Returns `1` if the requested document has been sent to this signer.
viewed	Returns `1` if this signer has viewed the requested document.
status	Returns the signing status of this signer. Click here to view all existing signing statues values.

Signing Status Values:

declined: Signer has declined to sign
signed: Signer has signed
waiting_for_signature: Signer has not signed yet
on_hold: Document delivery is queued (waiting for other signers to sign)

recipients Object

Name	Description
name	Returns the full name of this CC.
email	Returns the email address of this CC.
role	Returns the role name of this CC role (Templates only).
message	Returns the custom message to this CC (if specified).
required	Returns `1` if this CC role is required (Templates only).
language	Returns the 2-letter language code of the language chosen for this CC.

fields Object

Name	Description
merge	Returns `1` if the given field is a Merge Field.
identifier	Returns the given field's Field Identifier.
name	Returns the given field's Field Label.
options	Returns an array of dropdown menu options (Dropdown fields only).
group	Returns the Radio Button field group value.
value	Returns the given field's value. Click here to see a list of allowed field values per field.
type	Returns the given Field Type. Click here to see a list of all existing Field Types.
x	Returns the given field's horizontal margin from the left side of the document in pixels.
y	Returns the given field's vertical margin from the top of the document in pixels.
page	Returns the number of the document page where the given field is placed.
width	Returns the given field's width in pixels.
height	Returns the given field's height in pixels.
signer	Returns the unique signer ID of the signer the given field is assigned to.
validation_type	Returns the validation type specified for the given field.
required	Returns `1` if the given field is a Required Field.
readonly	Returns `1` if the given field is a Read-Only Field.
text_size	Returns the font size assigned to the given field.
text_color	Returns the HEX color code assigned to the given field.
text_style	Returns the B(old), U(nderline), I(talic) style options assigned to the given field.
text_font	Returns the font identifier assigned to the given field.
files	Returns an array of files attached to this field, each containing `name` (file name), `size` (file size in bytes) and `url` (URL to file) objects. For `attachment` fields only.

log Object

Name	Description
event	The identifier of the logged event.
signer	The unique signer ID of the signer the logged event is assigned to.
timestamp	The UNIX time stamp of the logged event.

Document Event Values:

There is a series of different event values that can be inside a document's log object:

document_created: Document has been created
document_edited: Document has been edited
document_completed: Document has been completed
document_sent: Document has been sent
document_restored: Document has been restored from trash
document_cancelled: Document has been cancelled
document_trashed: Document has been trashed
document_archived: Document has been archived
document_unarchived: Document has been unarchived
document_deleted: Document has been deleted
document_expired: Document has expired
document_viewed: Document has been opened/viewed
document_declined: Document has been declined
document_signed: Document has been signed by a signer

meta Object
If specified, this object contains a sub array for each custom field specified for the requested document.

Get Document/Template `HTTP GET`

API Request

Please find below an example HTTP GET request accessing an existing document or template:

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQAIIQ

API Response

{
    "document_hash": "A4X5GeinpUtjhz",
    "requester_email": "your@email.com",
    "custom_requester_name": "",
    "custom_requester_email": "",
    "is_draft": 0,
    "is_template": 0,
    "is_completed": 0,
    "is_archived": 0,
    "is_deleted": 0,
    "is_trashed": 0,
    "is_cancelled": 0,
    "embedded": 0,
    "in_person": 0,
    "permission": "",
    "template_id": "",
    "title": "Sample Document",
    "message": "This is my general document message.",
    "use_signer_order": 1,
    "reminders": 1,
    "require_all_signers": 1,
    "redirect": "https://myredirect.com/completed",
    "redirect_decline": "https://myredirect.com/declined",
    "client": "",
    "created": 1491822481,
    "completed": 1491852481,
    "expires": 1494276966,
    "embedded_signing_enabled": 0,
    "flexible_signing": 0,
    "files": [{
        "name": "My Document File",
        "file_id": "FMA4SyCuHjrusK",
        "pages": 3
    }],
    "signers": [{
        "id": 1,
        "name": "Paul McSign",
        "email": "paul@mcsign.com",
        "role": "",
        "order": 1,
        "pin": "3874",
        "signer_authentication_sms_enabled": 1,
        "signer_authentication_phone_number": "+43123221234",
        "message": "This is my custom message to Paul.",
        "signed": 0,
        "signed_timestamp": "",
        "required": 0,
        "deliver_email": "",
        "language": "en",
        "declined": 0,
        "removed": 0,
        "bounced": 0,
        "sent": 1,
        "viewed": 0,
        "status": "waiting_for_signature"
    }, {
        "id": 2,
        "name": "Julian McSign",
        "email": "julian@mcsign.com",
        "role": "",
        "order": 2,
        "pin": "3944",
        "message": "",
        "signed": 0,
        "signed_timestamp": "",
        "required": 0,
        "deliver_email": "",
        "language": "en",
        "declined": 0,
        "removed": 0,
        "bounced": 0,
        "sent": 0,
        "viewed": 0,
        "status": "on_hold"
    }],
    "recipients": [{
        "name": "Jane McSign",
        "email": "jane@mcsign.com",
        "role": "",
        "message": "",
        "required": 0,
        "language": "en",
    }, {
        "name": "Frank McSign",
        "email": "frank@mcsign.com",
        "role": "",
        "message": "",
        "required": 0,
        "language": "en",
    }],
    "fields": [
        [{
            "merge": 0,
            "identifier": "unique_field_identifier_1",
            "name": "",
            "options": "",
            "group": "",
            "value": "",
            "type": "signature",
            "x": 120.43811219947,
            "y": 479.02760463045,
            "page": 2,
            "width": 120,
            "height": 35,
            "signer": 1,
            "validation_type": "",
            "required": 1,
            "readonly": 0,
            "text_size": "",
            "text_color": "",
            "text_style": "",
            "text_font": "",
            "files": ""
        }, {
            "merge": 0,
            "identifier": "unique_field_identifier_2",
            "name": "",
            "options": "",
            "group": "",
            "value": "",
            "type": "signature",
            "x": 363.49421193232,
            "y": 479.57257346394,
            "page": 2,
            "width": 120,
            "height": 35,
            "signer": 2,
            "validation_type": "",
            "required": 1,
            "readonly": 0,
            "text_size": "",
            "text_color": "",
            "text_style": "",
            "text_font": "",
            "files": ""
        }, {
            "merge": 0,
            "identifier": "unique_field_identifier_3",
            "name": "Full Name",
            "options": "",
            "group": "",
            "value": "",
            "type": "text",
            "x": 97.549421193232,
            "y": 123.70792520036,
            "page": 1,
            "width": 55,
            "height": 17,
            "signer": 1,
            "validation_type": "",
            "required": 1,
            "readonly": 0,
            "text_size": 10,
            "text_color": "#000000",
            "text_style": "",
            "text_font": "arial",
            "files": ""
        }, {
            "merge": 0,
            "identifier": "unique_field_identifier_4",
            "name": "Full Name",
            "options": "",
            "group": "",
            "value": "",
            "type": "text",
            "x": 276.29919857524,
            "y": 123.16295636687,
            "page": 1,
            "width": 55,
            "height": 17,
            "signer": 2,
            "validation_type": "letters_only",
            "required": 1,
            "readonly": 0,
            "text_size": 10,
            "text_color": "#000000",
            "text_style": "",
            "text_font": "arial",
            "files": ""
        }, {
            "merge": 0,
            "identifier": "unique_field_identifier_5",
            "name": "Dropdown",
            "options": [
                "Option 1",
                "Option 2",
                "Option 3"
            ],
            "group": "",
            "value": "Option 1",
            "type": "dropdown",
            "x": 440.4,
            "y": 204.2,
            "page": 2,
            "width": 92,
            "height": 23,
            "signer": 1,
            "validation_type": "",
            "required": 1,
            "readonly": 0,
            "text_size": "",
            "text_color": "",
            "text_style": "",
            "text_font": "",
            "files": ""
        }]
    ],
    "log": [{
        "event": "document_created",
        "signer": "",
        "timestamp": 1491822484
    }, {
        "event": "document_sent",
        "signer": 1,
        "timestamp": 1491822485
    }],
    "meta": {
        "some_key": "some_value",
        "another_key": "another_value"
    }
}

List Documents

A list of existing documents can be accessed by making a simple HTTP GET call. By appending the API's type parameter to the API request URL and setting it to a document status you can filter your results accordingly.

type Parameter: This parameter accepts the following status values:

all
my_action_required
waiting_for_others
completed
drafts
cancelled

Per default the result is limited to 500 items. You may provide a lower limit via the limit parameter. If the number of total results exceeds the limit, you can access the next set of items via the page parameter (page index starts at 1): https://api.eversign.com/document?access_key=YOUR_ACCESS_KEY& business_id=1&type=all&limit=10&page=2

List Documents `HTTP GET`

API Request

Please find below an example HTTP GET request accessing a list of all existing documents:

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& type = all

API Response

If a successful request is made, the Xodo Sign API will return an array containing all existing documents.

List Templates

In order to access a list of templates, please set the API's type parameter to templates, or to one of the other allowed status values.

type Parameter: This parameter accepts the following status values:

templates
templates_archived
template_drafts

List Templates `HTTP GET`

API Request

Please find below an example HTTP GET request accessing a list of all existing documents:

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& type = templates

API Response

If a successful request is made, the Xodo Sign API will return an array containing all existing templates.

Send Reminder

A reminder can be sent on a per-signer basis only. In order to send a reminder to an individual signer, a simple HTTP POST request to the API's send_reminder endpoint is required.

The following two parameters must be contained in the HTTP POST request:

Name	Description	Details
document_hash	The unique hash (ID) of the document to send a reminder for.	Required
signer_id	The ID of the signer to send a reminder to.	Required

Send Reminder `HTTP POST`

API Request

https://api.eversign.com/send_reminder
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

{
	"document_hash": "j6yMcaF2gQBIIS",
	"signer_id": "1"
}

API Response

If successful, the API will return the following response:

{
	"success": true,
}

Reassign Signer

Just like a signer can forward their signing responsibility to another person, it's possible to reassign this responsibility as the document owner, a business admin or business owner via the API as well. An HTTP POST request to the API's reassign endpoint is required.

The document owner and both the old and the new signer will receive an email notification.

The following parameters must be contained in the HTTP POST request:

Name	Description	Details
document_hash	The unique hash (ID) of the document for which the signer should be changed.	Required
signer_id	The ID of the signer which should be reassigned/replaced.	Required
new_signer_name	The name of the new signer.	Required
new_signer_email	The email of the new signer.	Required
reason	The reason for the reassignment.	Optional

Reassign Signer `HTTP POST`

API Request

https://api.eversign.com/reassign
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

{
    "reason": "YOUR_REASON",
    "signer_id": 1,
    "document_hash": "j6yMcaF2gQBIIS",
    "new_signer_name": "Jane McSign",
    "new_signer_email": "jane@mcsign.com"
}

API Response

If successful, the API will return the following response:

{
    "success": true
}

Delete Document/Template

A document or template can be deleted by making an HTTP DELETE call to API's document endpoint and appending the document_hash GET parameter containing the document or template hash.

Implicit business logic

Pending / in-process documents have to be canceled first before they can be deleted
Completed documents have to be trashed first before they can be deleted
Draft documents have to be trashed first before they can be deleted

Delete Document/Template `HTTP DELETE`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQBIIS

API Response

If successful, the API will return the following response:

{
	"success": true,
}

Trash Document/Template

A document or template can be trashed by making an HTTP DELETE call to the API's document endpoint and appending both the document_hash GET parameter containing the document hash and the trash GET parameter and setting it to 1.

Trash Document `HTTP DELETE`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQBIIS
	& trash = 1

API Response

If successful, the API will return the following response:

{
	"success": true,
}

Cancel Document

A document can be cancelled by making an HTTP DELETE call to the API's document endpoint and appending both the document_hash GET parameter containing the document hash and the cancel GET parameter and setting it to 1.

Cancel Document `HTTP DELETE`

API Request

https://api.eversign.com/document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQBIIS
	& cancel = 1

API Response

If successful, the API will return the following response:

{
	"success": true,
}

Download Original PDF

The original PDF file of a document can be downloaded by making an HTTP GET request to the API's download_raw_document endpoint and setting the document_hash HTTP GET parameter to the hash of the document you would like to download.

Download Original PDF `HTTP GET`

API Request

https://api.eversign.com/download_raw_document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQBIIS

API Response

If successful, the Xodo Sign API will return the original version of the requested document as PDF.

Download Final PDF

The final PDF version of a document can be downloaded by making an HTTP GET request to the API's download_final_document endpoint and setting the document_hash HTTP GET parameter to the hash of the document you would like to download.

The following parameters can be appended in the HTTP GET request:

Name	Description
audit_trail	Append this parameter and set it to `1` to have an Audit Trail attached to your final PDF document.
document_id	Append this parameter and set it to `AT` to download only the Audit Trail of your document. You can also use this parameter to download specific files of a multi-file document by appending the sequency number of the respective file, e.g. `0` for the first file, `1` for the secnond file, etc.
url_only	Append this parameter and set it to `1` to have the API return only the URL of the requested document.

Download Final PDF `HTTP GET`

API Request

https://api.eversign.com/download_final_document
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1
	& document_hash = j6yMcaF2gQBIIS
	& audit_trail = 1

API Response

If successful, the Xodo Sign API will return the final version of the requested document as PDF.

Upload File

Document files can be uploaded to your Xodo Sign business by making an HTTP POST request containing the file content to the API's file endpoint. The API will then return a unique file_id that can be re-used when creating documents via the API.

API Response Objects:

Name	Description
file_id	Returns the file's unique identification hash.
total_pages	Returns the number of document pages.

File expiration Files will be retained for a maximum of 30 days. If they haven't been referenced in a document's files object within this timeframe, they will be deleted. Files that are used in documents are part of that document and will not be deleted.

Upload File `HTTP POST`

API Request

In order to upload a file, please send a multipart/form-data request containing the key parameter named upload and the file as value via HTTP POST request to the following URL:

https://api.eversign.com/file
        ?access_key = YOUR_ACCESS_KEY
        & business_id = 1

API Response

If successful, the API will return a response object containing an ID for the uploaded file and the number of pages.

{
     "file_id": "lZJk9QZ8ze3777",
     "total_pages": 3
}

Generate Bulk Sending CSV from Template

Bulk Sending endpoints can be used to send multiple documents based on a specific template. The Bulk Sending feature is based on providing a CSV template containing data about documents that should be created. This data needs to be in the correct form that is structured according to the template we want to use.

Look up your template Before using a template for Bulk Sending you might want to access it to review its signer and recipient roles, fields, and other settings. To look up your template, a GET Template request is required.

Generate Blank CSV from Template `HTTP GET`

API Request

https://api.eversign.com/template/{template_hash}/bulk/csv/blank
        ? access_key = YOUR_ACCESS_KEY
        & business_id = BUSINESS_ID

API Response

If successful, the Xodo Sign API will return the Blank CSV structure in Text format. This structure contains CSV headers specially crafted for {template_hash} used in the GET call.

Validate Bulk Sending CSV

Once the CSV file with Bulk Sending data is ready, it should be validated before the Bulk Job is executed.

This validation contains several important points:

Checking if the CSV is structured correctly, according to what the template expects.
Checking if all required fields are present.
Checking if all entries are in the correct format (i.e. email format).
Checking for hard limits.
Checking for the possible overages or overage restrictions.

Hard limits At the moment, there is a hard limit of 250 created documents per single Bulk Job. In the future, as the feature evolves these limits will increase.

Validation will always occur Validation is very important for the Bulk Sending feature. Even if you do not call this endpoint to specifically validate data, the same validation will occur automatically when you try to create a Bulk Job. Meaning, this validation endpoint is for your convenience, to improve user experience in your integration.

API Response if validation is successful

If validation is successful, the Xodo Sign API will return JSON response with validated data which is already prepared in the correct JSON format, for the Create Bulk Job endpoint.

API Response if validation is not successful

If validation is not successful, API will return JSON response with type "validation_errors". This JSON will contain "details" with an array of all validations that were not successful. Each validation has a row, validation error and description.

List of Bulk Sending validation violations

Validation Violation Type	Violation Info
required_entry_is_not_provided	You did not provide an entry that is required by the template.
required_entry_validation_failed	You provided an entry in a format that is not expected by the template.
headers_do_not_match_template	You provided CSV with headers that do not match what the template expects. For example, you might be uploading CSV to the wrong template or a template update since you generated CSV.
bulk_sending_size_exceeded	Your provided CSV with number of entries that is exceeding Bulk Sending size limits.
not_enough_api_credits_for_bulk_sending	You are trying to create a Bulk Job with a large number of documents. This bulk job exceeds Bulk Sending size limits.
bulk_sending_job_is_empty	You are trying to create a Bulk Job with 0 entries.
problem_while_parsing_bulk_sending_job_file	There was a problem while parsing the bulk job file (an example: duplicated header)
multiple_participants_with_same_email	You are trying to create a document where multiple recipients have the same email address, which is not supported.

Validate Bulk Sending CSV from Template`HTTP POST`

API Request

https://api.eversign.com/template/{template_hash}/bulk/csv/validate
	? access_key = YOUR_ACCESS_KEY
	& business_id = BUSINESS_ID

CSV file should be attached as form element within the body of API request --form 'csv_with_bulk_data=@".../csv_file_with_values.csv"'

API Response if validation is successful

[
    [
        "sender name",
        "sender email",
        "recipient name",
        "recipient email"
    ],
    [
        "signer1",
        "signer1@test.com",
        "recipient1",
        "recipient1@test.com"
    ],
    [
        "signer2",
        "signer2@test.com",
        "recipient2",
        "recipient2@test.com"
    ],
    ...
]

API Response if validation is not successful

{
    "success": false,
    "error": {
        "code": 0,
        "type": "validation_errors"
    },
    "details": [
        {
            "row": 1,
            "validation_error": "required_entry_is_not_provided",
            "description": "Required entry for 'sender name' is not provided"
        },
        {
            "row": 2,
            "validation_error": "required_entry_is_not_provided",
            "description": "Required entry for 'sender email' is not provided"
        },
        {
            "row": 3,
            "validation_error": "required_entry_validation_failed",
            "description": "Entry 'signer3test.com' for 'sender email' is not an email"
        }
    ]
}

Create Bulk Job

Bulk Sending endpoints can be used to send multiple documents based on a specific template.

Look up your template Before using a template for Bulk Sending you might want to access it in order to review its signer and recipient roles, fields and other settings. In order to look up your template, a GET Template request is required.

Be aware of possible additional costs Bulk Sending feature is generally used to generate lots of documents. All of these documents are counted against your API quota, which increases the probability that your quota will be used up. When this happens, the system will check if you have overage allowed. If overages are allowed, Bulk Job will proceed and you will be additionally charged for additional API documents.

Bulk Job Status

Once Bulk Job is executed, an API response will contain a status parameter

A status parameter can have the following values:

DOCUMENTS_CREATED - all documents from the Bulk Job were successfully created
DOCUMENTS_CREATED_WITH_ERRORS - some documents from the Bulk Job were not successfully created

Create Bulk Job`HTTP POST`

API Request

https://api.eversign.com/template/{template_hash}/bulk/job
	? access_key = YOUR_ACCESS_KEY
	& business_id = 1

[
    [
        "sender name",
        "sender email",
        "recipient name",
        "recipient email"
    ],
    [
        "signer1",
        "signer1@test.com",
        "recipient1",
        "recipient1@test.com"
    ],
    [
        "signer2",
        "signer2@test.com",
        "recipient2",
        "recipient2@test.com"
    ],
    ...
]

{
    "entry_id": 33,
    "template_hash": "d5516...95ef77d",
    "business_id": 1,
    "user_id": 1,
    "document_count": 6,
    "created_at": "2021-01-01T12:00:00+00:00",
    "status": "COMPLETED"
}

Get Bulk Job by id

An existing Bulk Job can be retrieved from the server by providing its unique id.

API Response Object:

Name	Description
entry_id	Unique database id of this job
template_hash	Hash identifier of the template used for the job
business_id	Id of a business from which the job was requested
user_id	Id of a user that requested this job
document_count	Number of documents successfully created by the job
created_at	Job's creation time in UTC
status	Current status of the Bulk Job

Possible values for status:

DOCUMENTS_CREATED
DOCUMENTS_CREATED_WITH_ERRORS

Get Bulk Job by id `HTTP GET`

API Request

https://api.eversign.com//bulk_job/{bulkSendingJobId}
        ? access_key = YOUR_ACCESS_KEY
        & business_id = BUSINESS_ID

API Response

A successful response will return a Bulk Job object as JSON

{
    "entry_id": 21,
    "template_hash": "be259ae9d7e98247fbad924f0bc0479e",
    "business_id": 7,
    "user_id": 5,
    "document_count": 211,
    "created_at": "2022-02-10T14:53:17+00:00",
    "status": "DOCUMENTS_CREATED"
}

Get Bulk Job Status by id

A status of a Bulk Job can be retrieved from the server by providing the job's unique id.

API Response Object:

Name	Description
bulk_job_created_at	Job's creation time in UTC
completed_documents	Number of documents with `completed` status
cancelled_documents	Number of documents with `cancelled` status
in_progress_documents	Number of documents with `in_progress` status
document_count	Number of documents successfully created by the job

origin_template Object

Name	Description
business_id	Id of a business which created the template
document_hash	Unique hashed document identifier
document_title	Title of the template document file
document_creation_ts	Unix timestamp of the template document creation

bulk_job_owner Object

Contains information about the Bulk Job owner

Get Bulk Job Status by id `HTTP GET`

API Request

https://api.eversign.com//bulk_job/{bulkSendingJobId}/status
        ? access_key = YOUR_ACCESS_KEY
        & business_id = BUSINESS_ID

API Response

A successful response will return a Bulk Job Status as JSON

{
    "bulk_job_created_at": "2022-02-10T14:53:17+00:00",
    "completed_documents": 11,
    "cancelled_documents": 2,
    "in_progress_documents": 1,
    "document_count": 14,
    "origin_template": {
        "business_id": "139",
        "document_hash": "9ae99c2824047ab5d9ed27fbf0be7e49",
        "document_title": "Partnership_Contract_template.pdf",
        "document_creation_ts": 1644504697
    },
    "bulk_job_owner": {
        "email_address": "john.doe@example.com",
        "first_name": "John",
        "last_name": "Doe"
    }
}

Get Bulk Job Documents by id

Users can retrieve Documents of a Bulk Job from the server by providing a job id. In addition, the user may paginate the results by providing the additional query to the HTTP GET request.

limit Parameter (optional):
number (0 - 1000) of documents to fetch (default: 100)

offset Parameter (optional):
number (min. 0) of documents to skip

API Response Object

pagination Object: contains pagination data

Name	Description
limit	Maximum amount of documents to fetch
offset	Number of documents to skip when fetching results
count	Amount of documents received from the request
total	Total number of documents in this job

data Array: contains document objects

Get Bulk Job Documents by id `HTTP GET`

API Request

https://api.eversign.com//bulk_job/{bulkSendingJobId}/documents
        ? access_key = YOUR_ACCESS_KEY
        & business_id = BUSINESS_ID
        & limit = LIMIT
        & offset = OFFSET

API Response

A successful response will return Documents from a Bulk Job.

{
    "pagination": {
        "limit": 100,
        "offset": 0,
        "count": 14,
        "total": 14
    },
    "data": [
    {
        "entry_id": 39,
        "business_id": "13",
        "document_hash": "a39a04440186d77420a6639ea008e5e7",
        "api_client_id": "eversign_api",
        "user_id": "27",
        "is_draft": "0",
        "is_completed": "1",
        "is_pending_completion": "0",
        "is_template": "0",
        "is_embedded_template": "0",
        "is_iframe": "0",
        "template_permission": "",
        "require_all_signers": "0",
        "enable_reminders": "0",
        "enable_flexible_signing": "0",
        "is_archived": "0",
        "is_trashed": "0",
        "is_deleted": "0",
        "is_cancelled": "0",
        "is_expired": "0",
        "document_type": "1",
        "document_title": "Partnership_Contract_template.pdf",
        "document_subject": "",
        "document_message": "",
        "document_status": "",
        "document_creation_ts": 1644504797,
        "use_signer_order": "0",
        "document_redirect_url": "",
        "document_redirect_url_decline": "",
        "origin_template_id": "9ae99c2824047ab5d9ed27fbf0be7e49",
        "template_disable_email_validation": "0",
        "add_signature_page": "0",
        "document_expiration_ts": "1652280797",
        "document_completion_ts": "",
        "document_file_checksum": "04157c28f984a810d42d6d564719221b",
        "document_completion_attempt_ts": "",
        "document_failed_completion_count": "",
        "oauth_attribution_app_id": "",
        "oauth_attribution_charge_user_id": "",
        "general_attribution_charge_user_id": "27",
        "custom_requester_name": "",
        "custom_requester_email": "",
        "document_meta_summary": "{\"s\":[{\"n\":\"John\",\"e\":\"John.Doe@example.com\",\"u\":\"\"}],\"r\":[],\"f\":[{\"n\":\"Partnership_Contract_template.pdf\"}]}",
        "pending_vault_id": "",
        "pending_vault_id_status": "",
        "api_overage_amount": null,
        "bulk_sending_job": {
            "entry_id": 479,
            "template_hash": "9ae99c2824047ab5d9ed27fbf0be7e49",
            "business_id": 139,
            "user_id": 27,
            "document_count": 14,
            "created_at": "2022-02-10T14:53:17+00:00",
            "status": "DOCUMENTS_CREATED"
        }
    },
    {...},
}

Get Bulk Jobs list

Users can retrieve a list of their Bulk Jobs from the server. In addition, the user may paginate the results by providing the additional query to the HTTP GET request.

limit Parameter (optional):
number (0 - 1000) of documents to fetch (default: 100)

offset Parameter (optional):
number (min. 0) of documents to skip

API Response Object

pagination Object: contains pagination data

Name	Description
limit	Maximum amount of jobs to fetch
offset	Number of jobs to skip when fetching results
count	Amount of jobs received from the request
total	Total number of jobs

data Array: contains Bulk Job objects

Get Bulk Jobs list`HTTP GET`

API Request

https://api.eversign.com//bulk_job
        ? access_key = YOUR_ACCESS_KEY
        & business_id = BUSINESS_ID
        & limit = LIMIT
        & offset = OFFSET

API Response

A successful response will return a list of Bulk Jobs for this user.

{
    "pagination": {
        "limit": 2,
        "offset": 0,
        "count": 2,
        "total": 21
    },
    "data": [
        {
            "entry_id": 47,
            "template_hash": "7e48240f0be2594fbabc2979ed97ae9d",
            "business_id": 13,
            "user_id": 27,
            "document_count": 14,
            "created_at": "2022-02-12T16:11:02+00:00",
            "status": "DOCUMENTS_CREATED",
            "document_title": "My original template 53"
        },
        {...}
    ]
}

Audit Log

An audit log of a document can be accessed using the HTTP GET call. If successful, the API will return the entire history of the document's actions as an array of objects.

API Response Objects:

Name	Description
entry_id	Unique database ID of this log
event_type	The event name identifier
event_assoc_signer	Signer's number for this document
event_assoc_signer_name	Signer's full name
event_assoc_signer_email	Signer's email address
event_assoc_signer_additional_data	Additional data for the following events: `document_created`, `signer_2fa_enabled`, `document_viewed` if `signer_authentication_sms_enabled`, `document_forwarded`, `document_revoked`, `signer_bounced`, `document_declined`, `document_signed` if `pin_protection_enabled`
time_stamp	Unix time of the occurring event
document_checksum	Data integrity value for this document
combined_checksum	Combined checksum based on `event_type`, `time_stamp` and `document_checksum`
client_ip	IP address of the client for a set of actions performed by a client (`document_viewed`, `document_declined`, etc.)
signer_ip	IP address of the signer (if signing)
merged_document_file_checksum	Checksum of the document's file after it has been modified (signed)

Audit Log `HTTP GET`

API Request

A request to the following URL should result with a list of events for a document:

https://api.eversign.com/document/{document_hash}/audit_log
	? access_key = YOUR_ACCESS_KEY
	& business_id = YOUR_BUSINESS_ID

API Response

A successful response will contain every event performed on this document.

[
    {...},
    {
        "entry_id": 202201,
        "event_type": "document_viewed",
        "event_assoc_signer": "1",
        "event_assoc_signer_name": "John Doe",
        "event_assoc_signer_email": "John.Doe@eversign.com",
        "event_assoc_signer_additional_data": {
            "signer_authentication_sms_enabled": 1,
            "signer_authentication_phone_number": "+15550000000"
        },
        "time_stamp": "1642604310",
        "document_checksum": "1f1beb5b97c283ff1f7c3d9500aed8de",
        "combined_checksum": "6730698649a3e4e300948bc57f7a94f4",
        "client_ip": "127.0.0.1",
        "signer_ip": "",
        "merged_document_file_checksum": ""
    },
]

Errors

Whenever an API request to the Xodo Sign API fails, an error will be returned. Errors always carry "success": false, an error code, a type object and an info string.

There are different types of errors, presented and described in the table below.

Error Type	Error Info
invalid_access_token	The access token used within the OAuth2 call is not valid.
inactive_access_token	The access token used within the OAuth2 call is not active.
user_not_found	The user associated with the access token used in the OAuth2 call is not found.
application_inactive	OAuth2 application deactivated (on the "Developer" page in Xodo Sign)
missing_access_key	You have not supplied an API Access Key. [Required format: access_key=YOUR_ACCESS_KEY]
invalid_access_key	You have not supplied a valid API Access Key. Please provide a detailed description of what you wanted to do and steps to reproduce to the Technical Support: support@eversign.com
inactive_user	Permission denied - User not active.
invalid_api_function	This API Function does not exist. This can be caused by a malformed URL in the API request.
invalid_business_id	Provided business_id is not in a valid form (number expected).
business_inactive	Business used in API call is not active.
invalid_language_identifier	The language identifier provided in the API call is not valid. A list of supported languages can be found here API documentation : Languages
invalid_language_items	Original language translation for language item does not exist.
invalid_document_hash	It is not possible to get document details for the provided document hash.
document_permission_denied	You do not have permission to execute an API call toward a defined document.
signer_not_found	A signer can not be found based on the signer hash provided in the API call.
no_team_members_found	There were no team members found during the team members list.
invalid_type	A provided "type" parameter in the API request URL is not a valid option or is missing.
no_signatures_found	Trying to list signatures where no signatures were found.
no_contacts_found_for_business	Listing contacts for business, but no contacts were found.
no_businesses_found_for_user	Listing businesses for the user, but no businesses were found.
database_connection_failed	Indicates database connectivity issues. Please provide a detailed description of what you wanted to do and steps to reproduce to the Technical Support: support@eversign.com
invalid_business_identifier	Validation of the business identifier failed. You have provided a business identifier in an incorrect format.
team_member_limit_reached	You have reached the limit of team members you can create with your current plan. For detailed information about our plans visit Xodo Sign.com/pricing
invalid_email_address	You have specified an invalid email address.
team_member_exists	Team member already exists.
contact_already_exists	Contact already exists.
missing_or_invalid_business_name	You are creating a new business, but no business name is provided.
business_identifier_exists	You are creating a new business, but you are using a business identifier that already exists.
missing_object_id	You are trying to interact with the object, but no identification was provided. This might indicate internal errors. You should examine your API call, if no resolution was found, please provide a detailed description of what you wanted to do and steps to reproduce to the Technical Support: support@eversign.com
not_found	The requested entity was not found. This is a very generic error type which can be related to signature, document, team member, contact, etc.
permission_denied	Permission to interact with the requested entity is denied. This is a very generic error type which can be related to business, user account, document, signature, etc.
missing_contact_id	You are trying to modify or delete a contact, without providing identification.
database_error	Indicates database connectivity issues, Please provide a detailed description of what you wanted to do and steps to reproduce to the technical Support: support@eversign.com
missing_files	Indicates that document can not be created without a file. This error can occur when creating document without files or when creating document from template where file was not reachable.
invalid_fields_input	The structure provided in fields is invalid. Make sure you provide a 2 dimensional array that has the same size as the array provided in files.
template_missing_files	Indicates that template can not be created without a file.
missing_file_content	One or more document files could not be uploaded. In this case you can retry your API call. If the issue is persistent, please contact the technical Support: support@eversign.com
template_is_draft	Draft templates can not be used to create documents.
no_delete_permission	You are trying to delete a document from someone else's business but do not have permission to do that.
missing_signers	You did not provide signers.
signer_authentication_combined_with_pin_not_supported	You are trying to create a signer with both pin and signer authentication enabled. This is not supported
signer_authentication_phone_number_invalid	You enabled signer authentication, but did not provide a phone number, or did not provide it in the correct format which is E.164 international standard
signer_authentication_sms_overage_not_possible_with_free_account	You are trying to overage/overspend signer authentication with a free account.
signer_authentication_sms_disabled	Signer Authentication with SMS is disabled.
provided_hash_does_not_reference_template	You provided an invalid template hash in the Bulk Sending endpoint.
uploaded_file_mime_type_not_supported	You are trying to upload a file with a mime type that is not supported.
updating_expiry_date_of_finalized_document	You are trying to update a finalized document with a new expiry date.
failed_generating_images	The file you are uploading can not be used to generate preview images. The most likely reason is a broken or corrupted file.

Sample Error

Please find below an example error message returned by the Xodo Sign API:

{
  "success": false,
  "error": {
    "code": 103,
    "type": "invalid_api_function",
    "info": "This API Function does not exist."
  }
}

Getting Started

Methods

Create Document: Fields

Bulk Sending

Hidden Tags

Embedded Signing

Embedded Requesting

OAuth 2.0

Webhooks

Libraries

Stay up to date

Methods

List Businesses

List Businesses HTTP GET

Create Document

Create Document HTTP POST

Create Template

Create Template HTTP POST

Use Template

Use Template HTTP POST

Get Document/Template

Get Document/Template HTTP GET

List Documents

List Documents HTTP GET

List Templates

List Templates HTTP GET

Send Reminder

Send Reminder HTTP POST

Reassign Signer

Reassign Signer HTTP POST

Delete Document/Template

Delete Document/Template HTTP DELETE

Trash Document/Template

Trash Document HTTP DELETE

Cancel Document

Cancel Document HTTP DELETE

Download Original PDF

Download Original PDF HTTP GET

Download Final PDF

Download Final PDF HTTP GET

Upload File

Upload File HTTP POST

Generate Bulk Sending CSV from Template

Generate Blank CSV from Template HTTP GET

Validate Bulk Sending CSV

List of Bulk Sending validation violations

Validate Bulk Sending CSV from TemplateHTTP POST

Create Bulk Job

Bulk Job Status

Create Bulk JobHTTP POST

Get Bulk Job by id

Get Bulk Job by id HTTP GET

Get Bulk Job Status by id

Get Bulk Job Status by id HTTP GET

Get Bulk Job Documents by id

Get Bulk Job Documents by id HTTP GET

Get Bulk Jobs list

Get Bulk Jobs listHTTP GET

Audit Log

Audit Log HTTP GET

Errors

Sample Error

List Businesses `HTTP GET`

Create Document `HTTP POST`

Create Template `HTTP POST`

Use Template `HTTP POST`

Get Document/Template `HTTP GET`

List Documents `HTTP GET`

List Templates `HTTP GET`

Send Reminder `HTTP POST`

Reassign Signer `HTTP POST`

Delete Document/Template `HTTP DELETE`

Trash Document `HTTP DELETE`

Cancel Document `HTTP DELETE`

Download Original PDF `HTTP GET`

Download Final PDF `HTTP GET`

Upload File `HTTP POST`

Generate Blank CSV from Template `HTTP GET`

Validate Bulk Sending CSV from Template`HTTP POST`

Create Bulk Job`HTTP POST`

Get Bulk Job by id `HTTP GET`

Get Bulk Job Status by id `HTTP GET`

Get Bulk Job Documents by id `HTTP GET`

Get Bulk Jobs list`HTTP GET`

Audit Log `HTTP GET`