eSignatures.io API

One liner: send yourself a contract

To send yourself a test contract, simply replace the EMAIL ADDRESS in this line:

curl -X POST https://c21bc7:@esignatures.io/api/contracts -d '{"template_id": "20ac76c9","signers":[{"name":"Sam Signer","email":"EMAIL ADDRESS"}]}'

Requests, responses

The API calls are organized around REST. Our API is predictable, uses HTTP response codes (2xx, 4xx, 5xx) to indicate API results/errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. JSON is returned by all API responses, including errors.

Basic Authentication

curl https://<secret-token>:@esignatures.io/api/<query>
curl -X POST https://<secret-token>:@esignatures.io/api/<action>

Authenticate your account when using the API by including your secret API token in the request.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. API requests without authentication will fail.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Basic auth	Description
username	Your API secret token, displayed on your API dashboard page, when logged in

Zapier integration

eSignatures.io currently has the following Zapier triggers and actions:

• action: send contract
• trigger: contract sent to signer
• trigger: contract signed by signer
• trigger: contract signed by everyone

Find us on this Zapier page…

Contracts

Contracts can be fully managed via the API. Sending a contract can be done with a single API call, and after that signatures are collected, and notifications are provided at every stage of the contract’s lifecycle via webhooks.

Sending a contract

POST /api/contracts HTTP/1.1

JSON request parameters

{
  "template_id": "4templ44-6666-3333-4444-555555555555",
  "signers": [
    {
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "redirect_url": "https://your-website.com/aftersign",
      "auto_sign": "no",
      "skip_signature_request_email": "no"
    }
  ],
  "custom_fields": [
      {
        "api_key": "client_address1",
        "value": "69 Yonge St"
      }
  ],
  "emails": {
    "signature_request_subject": "Your document is ready to sign",
    "signature_request_text": "Hi __FULL_NAME__, \n\n To sign the contract please <link>click on this link...</link> \n\n Kind Regards",
    "final_contract_subject": "Your document is signed",
    "final_contract_text": "Hi __FULL_NAME__, \n\n Your document is signed.\n\nKind Regards",
    "cc_email_addresses": ["tom@email.com", "francis@email.com"]
  },
  "locale": "en",
  "embedded": "no",
  "test": "yes"
}

JSON response

{
  "status": "queued",
  "data": {
    "contract": {
      "id": "1contr11-2222-3333-4444-555555555555",
      "status": "sent",
      "template_name": "Sample NDA",
      "signers": [
        {
          "id": "6signer6-9999-2222-4444-111111111111",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "mobile": "+12481234567",
          "embedded_url": "https://esignatures.io/sign_contracts/6signer6-9999-2222-4444-111111111111?embedded=yes"
        }
      ]
    }
  }
}

Example request

curl -X POST https://<secret-token>:@esignatures.io/api/contracts -d '{"template_id": "4templ44-6666-3333-4444-555555555555","signers":[{"name":"Sam Signer","email":"sam@tenants.com","mobile":"+12481234567"}],"custom_fields":[{"api_key":"special-conditions","value":"Allowed currencies: \n -USD \n -GBP \n -EUR"}], "test": "yes"}'

This request creates the contract and sends the emails to the signers to collect the signatures. At every step of the process, for every action, a webhook notification is triggered.

Parameter	Required	Description
template_id	yes	Specifies the template to be used for the contract (the template_id is shown when editing the template)
signers		List of signers
signers:name	yes	Name of the signer
signers:email	cond	Email address of the signer - for identification. Either email or mobile is required.
signers:mobile	cond	Mobile number of the signer - for identification. Either email or mobile is required.
signers:redirect_url	no	The URL you want the signer redirected to after they successfully sign
signers:auto_sign	no	When set to yes, the signer’s signature will automatically be added to the contract
signers:skip_signature_request_email	no	When set to yes, the signer will not receive signature request, or identification emails. Note: this email is part of the signer (email) identification process - your service needs to identify the signer when this email is disabled.
custom_fields	no	List of texts to replace in the template
custom_fields:api_key		The “api_key” is specified by you in the template editor
custom_fields:value		The text to insert in the contract for the given custom field (new line character: \n). For Text input fields it can provide the default value.
custom_fields:select_position		For Select fields only - The position of the default option, starting from 0
emails:signature_request_subject	no	The subject in the email that will be sent to the signers when collecting their signatures
emails:signature_request_text	no	The text in the email that will be sent to the signers. __FULL_NAME__ constant is replaced by the name of the signer. The text for the link can be embedded between <link></link> nodes.
emails:final_contract_subject	no	The subject in the email that will be sent to the signers with the final PDF contract
emails:final_contract_text	no	The text in the email that will be sent to the signers with the final PDF contract. __FULL_NAME__ constant is replaced by the name of the signer.
emails:cc_email_addresses	no	List of email addresses to CC the signed PDF contract
locale	no	Setting the signer page/emails language. Currently available locales: es no it sv pt hu nl sk fr de en
embedded	no	The response will include an ‘embedded_url’ for every signer, to be inserted in the embedded iframe’s url code. If set to yes, no signatures requests are sent to the signers. (See further documentation below)
test	no	The sent contract is marked as 'demonstration only’, and no fee is deducted for sending the contract (the optional SMS fee still applies)

Response field	Description
status	queued
contract:id	Id of the contract
contract:template_name	Name of the template the contract is based on
contract:signers:id	Id of the signer
contract:signers:name	Name of the signer
contract:signers:email	Email of the signer
contract:signers:mobile	Mobile of the signer
contract:signers:embedded_url	Url for the signer, that can be embedded in an iframe. Find more information at the Notes section of this document.

Note: skip_signature_request_email

When using this setting, your signers need to be authenticated on your website before they may sign legally binding contracts.

As part of the generic signing process, eSignatures.io sends an email with a unique link for identification purposes. When skip_signature_request_email=yes, no email is sent to the signer, and your website needs to validate the email address for the signer.

Querying contract details

GET /api/contracts/<contract_id> HTTP/1.1

JSON response

{
  "data": {
    "id": "1contr11-2222-3333-4444-555555555555",
    "status": "sent",
    "template_name": "Sample NDA",
    "contract_pdf_url": "https://aws.com/contracts/1contr11-2222-3333-4444-555555555555?secret_token=x123y",
    "signers": [
      {
        "id": "6signer6-9999-2222-4444-111111111111",
        "name": "Sam Signer",
        "email": "sam@tenants.com",
        "mobile": "+12481234567",
        "embedded_url": "https://esignatures.io/sign_contracts/6signer6-9999-2222-4444-111111111111?embedded=yes",
        "events": [
          {
            "event": "sign_contract",
            "timestamp": "2015-10-22T18:19:35.979"
          }
        ],
        "custom_fields": [
          {
            "api_key": "city",
            "value": "Boston"
          }
        ]
      }
    ]
  }
}

Example request

curl -X GET https://<secret-token>:@esignatures.io/api/contracts/1contr11-2222-3333-4444-555555555555

Returns the details of a contract, the details of the signers, including the contract events, the signer events, and the values the signers entered.

Response field	Description
id	Id of the contract
status	'sent’ / 'signed’ / 'withdrawn’
template_name	Name of the template
contract_pdf_url	When the contract is signed, the finalized PDF can be accessed via this url. Expires in 24 hours following the request. (as part of the json response, this string might be encoded)
signers	List of signers
signers:id	Id of the signer
signers:name	Name of the signer
signers:email	Email of the signer
signers:mobile	Mobile of the signer
signers:embedded_url	Url for the signer, that can be embedded in an iframe. Find more information at the Notes section of this document (as part of the json response, this string might be encoded)
signers:events	Events of the signer
signers:events:event	'contract_sent’ / 'reminder_emailed’ / 'reminder_sms_sent’ / 'contract_viewed’ / 'delivering_contract_email_failure’ / 'email_spam_complaint’ / 'delivering_contract_sms_failure’ / 'sign_contract’ / 'final_contract_sent’/ 'signature_declined’ / 'disable_reminders’
signers:events:timestamp	Time of the event
signers:custom_fields:api_key	The “api_key” specified by you in the template editor for the given field
signers:custom_fields:value	The value the signer entered for this field

Withdrawing a contract

Withdrawn contracts can’t be signed any more, and signed contracts can’t be withdrawn.

Withdrawing the contract doesn’t result in deletion of the contract related information, the contract details can still be queried.

POST /api/contracts/<contract_id>/withdraw HTTP/1.1

JSON response

{
  "status": "queued"
}

Example request

curl -X POST https://<secret-token>:@esignatures.io/api/contracts/1contr11-2222-3333-4444-555555555555/withdraw

Response field	Description
status	'queued’

Templates

Templates can be created and maintained with the built-in editor. Editing the templates is straightforward, and collaborators can be invited.

The templates can have custom fields, such as names and addresses. The content for these fields can be specified by either the signers, or by the API.

List of templates

GET /api/templates HTTP/1.1

JSON response

{
  "data": [
    {
      "template_id": "4templ44-6666-3333-4444-555555555555",
      "template_name": "Residential Tenancy Agreement"
    }
  ]
}

Example request

curl -X GET https://<secret-token>:@esignatures.io/api/templates

Returns the list of templates you can send.

Response field	Description
template_id	Id of the template
template_name	Name of the template

Query template details

GET /api/templates/<template_id> HTTP/1.1

JSON response

{
  "data": {
    "template_id": "4templ44-6666-3333-4444-555555555555",
    "template_name": "Residential Tenancy Agreement",
    "created_at": "2015-10-24T15:15:35.979",
    "custom_fields": ["postcode"]
  }
}

Example request

curl -X GET https://<secret-token>:@esignatures.io/api/templates/4templ44-6666-3333-4444-555555555555

Returns the details of the template. The custom field keys are specified with the template editor.

Response field	Description
template_id	Id of the template
template_name	Name of the template
created_at	Date of creation
custom_fields	List of api_key-s, which are specified by you in the template editor

Signers

Updating signer details

POST /api/contracts/<contract_id>/signers/<signer_id> HTTP/1.1

JSON request parameters

{
  "name": "Sam Signer",
  "email": "sam@tenants.com",
  "mobile": "+1 541 754 3010"
}

JSON response

{
  "status": "queued"
}

Example request

curl -X POST https://<secret-token>:@esignatures.io/api/contracts/1contr11-2222-3333-4444-555555555555/signers/6signer6-9999-2222-4444-111111111111 -d '{"email":"sam@tenants.com", "name":"Sam Signer-Smith"}'

The contact details of a signer can be updated via this API request. Note: The contract is not emailed automatically when updating signer.

Parameter	Required	Description
name	no	Name of the signer
email	no	Email to identify the signer
mobile	no	Mobile number to identify the signer

Response field	Description
status	‘queued’

Sending contract to signer

POST /api/contracts/<contract_id>/signers/<signer_id>/send_contract HTTP/1.1

JSON response

{
  "status": "queued"
}

Example request

curl -X POST https://<secret-token>:@esignatures.io/api/contracts/1contr11-2222-3333-4444-555555555555/signers/6signer6-9999-2222-4444-111111111111/send_contract

Response field	Description
status	'queued’

Embedded signing

Iframe code

<iframe src="EMBEDDED_URL" name="esignatures-io-iframe" width=800 height=600>
</iframe>

Example POST#contracts request to create the contract

curl -X POST https://<secret-token>:@esignatures.io/api/contracts -d '{"template_id": "4templ44-6666-3333-4444-555555555555","signers":[{"name":"Sam Signer","email":"sam@tenants.com","skip_signature_request_email":"yes"}]}'

The sign page can be embedded into an iframe. Steps:

1. Create a contract with POST#contracts, and specify embedded=yes
2. The response json will include a data:contract:signers:embedded_url for every signer
3. In the iframe html code, replace the EMBEDDED_URL with the embedded_url for each signer respectively

Optional:

• Specify the redirect_url when creating a contract, so the signers will be redirected to that given page. Please note that the redirect_url will only be loaded within the iframe.

Webhooks

Use webhooks to be notified about events that happen real-time. For example, when a contract gets signed, a request is triggered to the Webhook URL specified by you on the API dashboard page. Creating a webhoook endpoint on your server means simply accepting POST requests at a given URL. Webhook data is sent as JSON in the POST request body.

If a webhook is not successfully received (not 2xx response code), eSignatures.io will continue trying to send the webhook once an hour for up to six times.

All Webhook requests we trigger use BASIC auth. You can enforce or ignore that. The username is your API secret token, without password.

Contract sent to signer

JSON body

{
  "status": "contract-sent-to-signer",
  "data": {
    "contract_id": "1contr11-2222-3333-4444-555555555555",
    "signer_id": "6signer6-9999-2222-4444-111111111111",
    "name": "Sam Signer",
    "email": "sam@tenants.com",
    "mobile": "+12481234567",
    "timestamp": "2015-10-22T18:18:35.979"
  }
}

This webhook notification is triggered, when the contract is sent to the signer for signature.

Signer viewed the contract

JSON body

{
  "status": "signer-viewed-the-contract",
  "data": {
    "id": "6signer6-9999-2222-4444-111111111111",
    "name": "Sam Signer",
    "email": "sam@tenants.com",
    "mobile": "+12481234567",
    "auto_sign": "no",
    "redirect_url": "",
    "contract": {
      "id": "mobile1contr11-2222-3333-4444-555555555555",
      "template_name": "Sample NDA"
    },
    "events": [
      {
        "event": "contract_viewed",
        "timestamp": "2015-10-22T18:19:35.979"
      }
    ]
  }
}

This webhook notification is triggered, when the signer views the contract the first time.

Signer signed the contract

JSON body

{
  "status": "signer-signed",
  "data": {
    "contract_id": "1contr11-2222-3333-4444-555555555555",
    "timestamp": "2015-10-22T18:19:35.979",
    "signer": {
      "id": "6signer6-9999-2222-4444-111111111111",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "custom_fields": {
        "api_key": "address-line-1",
        "value": "26 Marble street"
      }
    }
  }
}

This webhook notification is triggered when a signer signs the contract. It includes the details of the signer, and the texts for the custom fields, if the signer entered any.

Field	Description
status	‘signer-signed’
contract_id	Id of the contract
timestamp	Time of the event
signer	Details of the signer
signer:id	Id of the signer
signer:name	Name of the signer
signer:email	Email of the signer
signer:mobile	Mobile of the signer
signer:custom_fields:api_key	The “api_key” specified by you in the template editor for the given field
signer:custom_fields:value	The value the signer entered for this field

Contract signed

JSON body

{
  "status": "contract-signed",
  "data": {
    "id": "1contr11-2222-3333-4444-555555555555",
    "template_name": "Sample NDA",
    "contract_pdf_url": "https://aws.com/contracts/1contr11-2222-3333-4444-555555555555?secret_token=x123y",
    "signers": [
      {
        "id": "6signer6-9999-2222-4444-111111111111",
        "name": "Sam Signer",
        "email": "sam@tenants.com",
        "mobile": "+12481234567",
        "embedded_url": "https://esignatures.io/sign_contracts/6signer6-9999-2222-4444-111111111111?embedded=yes",
        "events": [
          {
            "event": "sign_contract",
            "timestamp": "2015-10-22T18:19:35.979"
          }
        ],
        "custom_fields": [
          {
            "api_key": "city",
            "value": "Boston"
          }
        ]
      }
    ]
  }
}

This webhook notification is triggered once every signer has signed the contract. It returns the generatede PDF file.

Field	Description
status	'contract-signed’
id	Id of the contract
template_name	Name of the template
contract_pdf_url	The finalized PDF can be accessed via this url. Expires in 2 hours following the request. (as part of the json response, this string will be encoded)
signers	List of signers
signers:id	Id of the signer
signers:name	Name of the signer
signers:email	Email of the signer
signers:mobile	Mobile of the signer
signers:embedded_url	Url for the signer, that can be embedded in an iframe. Find more information at the Notes section of this document. (as part of the json response, this string might be encoded)
signers:events	Events of the signer
signers:events:event	'contract_sent’ / 'reminder_emailed’ / 'reminder_sms_sent’ / 'contract_viewed’ / 'delivering_contract_email_failure’ / 'email_spam_complaint’ / 'delivering_contract_sms_failure’ / 'sign_contract’ / 'final_contract_sent’/ 'signature_declined’ / 'disable_reminders’
signers:events:timestamp	Time of the event
signers:custom_fields:api_key	The “api_key” specified by you in the template editor for the given field
signers:custom_fields:value	The value the signer entered for this field

Contract withdrawn

JSON body

{
  "status": "contract-withdrawn",
  "data": {
    "contract_id": "1contr11-2222-3333-4444-555555555555"
  }
}

This webhook notification is triggered, when the contract is withdrawn.

Signer declined the signature

JSON body

{
  "status": "signer-declined",
  "data": {
    "id": "6signer6-9999-2222-4444-111111111111",
    "name": "Sam Signer",
    "email": "sam@tenants.com",
    "mobile": "+12481234567",
    "auto_sign": "no",
    "redirect_url": "",
    "contract": {
      "id": "1contr11-2222-3333-4444-555555555555",
      "template_name": "Sample NDA"
    },
    "events": [
      {
        "event": "signature_declined",
        "reason_for_decline": "Commencement date is 5th of June",
        "timestamp": "2015-10-22T18:19:35.979"
      }
    ]
  }
}

This webhook notification is triggered, when the signer declined signing the contract.

Webhook error notifications

JSON body

{
  "status": "error",
  "error_code": "email-delivery-failed"
}

error_code	Description
email-delivery-failed	Sending the contract to the signer has failed
sms-delivery-failed	Sending the sms to the signer has failed
invalid-redirect-url	The redirect_url settings or API parameter is invalid

Notes

Emails

The email subject/body sent to the signer can be specified using signature_request_subject, signature_request_text, final_contract_subject and final_contract_text.

signature_request_text

• __FULL_NAME__ is replaced by the full name of the signer
• <link>follow this link...</link> is replaced by the link to sign the contract

final_contract_text

• __FULL_NAME__ is replaced by the full name of the signer

Checkboxes

The checkbox custom fields have the string value of “1” when checked. This applies to the webhook notifications, and to the custom_fields data of the Send contract API call.

Have a question?

Contact us…