Methods

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

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.

HTTP GET

List Businesses

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.

HTTP POST

Create Document

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.

HTTP POST

Create Template

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 to this signer 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

HTTP POST

Use Template

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.

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.

HTTP GET

Get Document /
Template

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

HTTP GET

List Documents

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

HTTP GET

List Templates

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

HTTP POST

Send Reminder

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

HTTP POST

Reassign Signer

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

HTTP DELETE

Delete Document /
Template

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.

HTTP DELETE

Trash Document

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.

HTTP DELETE

Cancel Document

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.

HTTP GET

Download Original PDF

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.

HTTP GET

Download Final PDF

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.

HTTP POST

Upload File

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.

HTTP GET

Generate Blank CSV
from Template

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.

HTTP POST

Validate Bulk Sending
CSV from Template

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

HTTP POST

Create Bulk Job

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

HTTP GET

Get Bulk Job by id

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

HTTP GET

Get Bulk Job Status
by id

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

HTTP GET

Get Bulk Job
Documents by id

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

HTTP GET

Get Bulk Jobs list

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)

HTTP GET

Audit Log

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.

signer_can_not_be_reminded

This signer cannot be reminded. This is most likely you're trying to send a reminder to a signer who's not yet the next one in the signing order of the document.

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."
  }
}