eSignatures.io API

Quickstart - Send yourself test a contract

Replace the apitest@esignatures.io email to yours:

curl -X POST -H 'Content-type:application/json' \ 'https://esignatures.io/api/contracts?token=22222222-4444-2222-4444-222222222222' \ -d '{"template_id": "44444444-2222-4444-2222-444444444444","signers":[{"name":"Sam Signer","email":"apitest@esignatures.io"}]}'

Basics - REST API, Token auth, Rate limiting

POST https://esignatures.io/api/contracts HTTP/1.1

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/<action>?token=your-secret-token'

The API calls are organized around REST with JSON data. The authentication as based on a token parameter in the URL. You can find your Secret token on your API page after logging in to your eSignatures.io account. Please note that requests from browsers will result in CORS error, in order to safeguard your secret token.

Rate limiting: To protect against accidental requests and intentional attacks, our service uses an adaptive rate limiting technique. Adaptive rate limiting means that the rate limiting changes based on the usage patterns. Please note that it's discouraged to repetitively 'poll' contract information via the API, eg GET /api/contracts/<id>. Using Webhook notifications is the recommended way to keep the contract statuses updated.

Parameter	Description
token	Your API secret token

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.

Send a contract

POST /api/contracts HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/contracts?token=your-secret-token' -d '{"template_id": "4templ44-6666","signers":[{"name":"Sam Signer","email":"sam@tenants.com","mobile":"+12481234567"}],"placeholder_fields":[{"api_key":"preferred_term","value":"24 months"}], "test": "yes"}'

JSON request parameters

{
  "template_id": "4templ44-6666",
  "test": "no",
  "title": "Loan Agreement - Saver package",
  "locale": "en",
  "metadata": "ID0001",
  "expires_in_hours": "48",
  "custom_webhook_url": "https://your-website.com/esignaturesio-custom-webhook",
  "assigned_user_email": "colleague@your-business.com",
  "labels": ["MA", "Rental"],
  "signers": [
    {
      "name": "Benny Bell",
      "email": "benny@me.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "signature_request_delivery_methods": ["email"],
      "signed_document_delivery_method": "email",
      "multi_factor_authentications": ["sms_verification_code"],
      "redirect_url": "https://your-website.com/aftersign"
    }
  ],
  "placeholder_fields": [
      {
        "api_key": "interest_rate",
        "value": "3.2%"
      },
      {
        "api_key": "floor-plan",
        "document_elements": [{"type":  "image", "image_base64":  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIW2P4v5ThPwAG7wKklwQ/bwAAAABJRU5ErkJggg=="}]
      }
  ],
  "signer_fields": [
      {
        "signer_field_id": "preferred_term",
        "default_value": "15 years"
      }
  ],
  "emails": {
    "signature_request_subject": "Your document is ready to sign",
    "signature_request_text": "Hi __FULL_NAME__, \n\n To review and sign the contract please press the button below \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"],
    "reply_to": "support@customdomain.com"
  },
  "custom_branding": {
    "company_name": "WhiteLabel LLC",
    "logo_url": "https://online-logo-store.com/yourclient-logo.png"
  }
}

JSON response

{
  "status": "queued",
  "data": {
    "contract": {
      "id": "1contr11-2222",
      "status": "sent",
      "title": "Loan Agreement - Saver package",
      "metadata": "ID0001",
      "source": "api",
      "test": "no",
      "signers": [
        {
          "id": "6signer6-9999",
          "name": "Benny Bell",
          "email": "benny@me.com",
          "mobile": "+12481234567",
          "company_name": "ACME Corp",
          "sign_page_url": "https://esignatures.io/sign/6signer6-9999"
        }
      ]
    }
  }
}

This request creates the contract and sends the links (via email or SMS) to the signers to collect their signatures.

Parameter	Required	Description
template_id	yes	Specifies the template to be used for the contract (the template_id is shown when editing the template)
test	no	The sent contract is marked as 'demonstration only', and no fee is deducted for sending the contract.
title	no	The unique title of the contract (Template name when not specified). It appears in emails, generated documents, and on dashboard pages
locale	no	Setting the signer page/emails language. Currently available locales: `sk fr en ro en-GB cz no sl da hu es pl vi it hr zh-CN nl de ja id rs sv pt`
metadata	no	Custom information
expires_in_hours	no	The signature request links will expire after that given period of time
custom_webhook_url	no	The Custom webhook URL to be used for the webhook notifications, instead of the default one specified on your API page
assigned_user_email	no	Assign of of your users in eSignatures.io to the new contract, to manage it and receive notifications
labels	no	Assigns the given list of Labels to the contract. The Labels are shown on the Dashboard UI and they are searchable. They help with grouping the contracts.
signers	yes	List of signers
signers: name	yes	Name of the signer
signers: email	cond	Email address of the signer. (Can be blank when the mobile number is provided)
signers: mobile	cond	Mobile number of the signer. Non-US mobile numbers must start with the country code, eg +61.... (Can be blank when the email address is provided)
signers: company_name	no	Company name for the signer
signers: signing_order	no	A number that defines the order of signers. When the same number is used for two or more signers they will receive the signature request at the same time. By default the signers will receive the signature requests in order (not at the same time).
signers: auto_sign	no	When `yes`, the signer's signature will automatically be added to the contract. Please note that this feature can only be used to add your own electronic signature record to the document, and it can't be used to Auto-sign on behalf of your clients/3rd parties.
signers: signature_request_delivery_methods	no	The initial signature requests will be delivered via the given channels. The available options are `'email'`, `'sms'` or an empty list can be provided to skip any signature requests. By the default the value is calculated.
signers: signed_document_delivery_method	no	The preferred method to deliver the signed document to the signer. The available options are `'email'`, `'sms'`, `''` and by default the value is calculated. Note: Delivery of the signed document is a legal requirement in most countries. If the `signed_document_delivery_method` is disabled then you will need to deliver the documents to the signers.
signers: multi_factor_authentications	no	Multi factor authentication for signers. Supported MFAs: `sms_verification_code`, `email_verification_code`. (The given contact details must be provided for the signer, e.g. email or mobile number)
signers: redirect_url	no	The signer will be redirected to that URL after signing the contract.
placeholder_fields	no	Placeholder fields are the highlighted texts in the template between curly brackets, eg `{{interest_rate}}`. Replace the Placeholder fields with simple custom text using the `placeholder_fields:value` parameter, or with headers, paragraphs using the `placeholder_fields:document_elements` parameter.
placeholder_fields:api_key	no	The "api_key" is the text between the curly brackets in the contract templates. Eg: `{{interest_rate}}`
placeholder_fields:document_elements	no	Insert headers, formatted text, Signer fields or even templates into the given the Placeholder fields. Find the detailed documentation for the `document_elements` below.
placeholder_fields:value	no	Replace the Placeholder field with simple text.
signer_fields	no	Use `signer_fields` to pre-fill Signer input fields.
signer_fields:signer_field_id	no	The "Signer field ID" in the template editor for the given Signer input field.
signer_fields:default_value	no	The initial (default) value for the input field (Use '1' to tick checkboxes, and use 'YYYY-mm-dd' for dates)
signer_fields:select_position	no	For Select fields only - The index of the pre-selected 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 with the name of the signer.
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 with the name of the signer.
emails:cc_email_addresses	no	List of email addresses to CC the signed PDF contract
emails:reply_to	no	Custom reply_to email address (your API support email when not specified)
custom_branding:company_name	no	Custom sender company name
custom_branding:logo_url	no	Custom logo (PNG x400 recommended)

Response field	Description
status	queued
contract:id	Id of the contract
contract:title	The unique title of the contract
contract:metadata	The metadata provided in the original request
contract:source	The source of the contract being `api`, `ui` or `zapier`
contract:test	`yes` means test contract, `no` means live contract
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:company_name	Company name for the signer
contract:signers:sign_page_url	Unique sign page URL for the given signer. It can be embedded in an iframe by adding the `embedded=yes` URL parameter.

Contract - query

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

Example request

curl -X GET 'https://esignatures.io/api/contracts/1contr11-2222?token=your-secret-token'

JSON response

{
  "data": {
    "contract":{
      "id": "1contr11-2222",
      "status": "sent",
      "title": "Rental Agreement",
      "metadata": "ID0001",
      "source": "api",
      "test": "no",
      "contract_pdf_url": "https://aws.com/contracts/1contr11-2222?secret_token=x123y",
      "labels": ["MA", "Rental"],
      "signers": [
        {
          "id": "6signer6-9999",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "mobile": "+12481234567",
          "company_name": "ACME Corp",
          "sign_page_url": "https://esignatures.io/sign/6signer6-9999",
          "events": [
            {
              "event": "sign_contract",
              "timestamp": "2015-10-22T18:19:35.979"
            }
          ],
          "signer_field_values": {
            "city": "Boston",
            "preferred_contact": "Phone"
          }
        }
      ]
    }
  }
}

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

Rate limiting and limited data: Please note that it's discouraged to repetitively 'poll' contract information via the GET /api/contracts/<id> endpoint. Contracts older than 2 weeks might not return all the data in the response, and frequent polling of contracts can result in blocked requests. Using Webhook notifications is the recommended way to keep the contract statuses updated.

Response field	Description
id	Id of the contract
status	'sent' / 'signed' / 'withdrawn'
title	The unique title of the contract
metadata	The metadata provided in the original request
source	The source of the contract being `api`, `ui` or `zapier`
test	`yes` means test contract, `no` means live contract
contract_pdf_url	When the contract is signed, the finalized PDF can be accessed via this url. Expires in 7 days following the request. (As part of the json response, this string will be JSON encoded, and simple copy paste of the URL won't work)
labels	The Assigned list of labels. The Labels are shown on the Dashboard UI and they are searchable. They help with grouping the contracts.
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:company_name	Company name for the signer
signers:sign_page_url	Unique sign page URL for the given signer. It can be embedded in an iframe by adding the `embedded=yes` URL parameter.
signers:events	Events of the signer
signers:events:event	contract_viewed / disable_reminders / email_contract_sent / email_delivery_failed / email_final_contract_sent / email_spam_complaint / mobile_update_request / reminder_emailed / sign_contract / signature_declined / sms_contract_sent / sms_delivery_failed / sms_final_contract_sent
signers:events:timestamp	Time of the event
signers:signer_field_values	Information provided by the signer for the Signer input fields, eg: Text fields, Dropdowns, Uploaded files. (The signer fields need to have an API key added in the template editor)

Contract - withdraw

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

Example request

curl -X POST 'https://esignatures.io/api/contracts/1contr11-2222/withdraw?token=your-secret-token'

JSON response

{
  "status": "queued"
}

Response field	Description
status	'queued'

Signer - update

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

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/contracts/1contr11-2222/signers/6signer6-9999?token=your-secret-token' -d '{"email":"sam@tenants.com", "name":"Sam Signer-Smith"}'

JSON request parameters

{
  "name": "Sam Signer",
  "email": "sam@tenants.com",
  "mobile": "+1 541 754 3010",
  "signature_request_delivery_methods": ["email"],
  "signed_document_delivery_method": "email",
  "multi_factor_authentications": ["sms_verification_code"],
  "redirect_url": "https://your-website.com/aftersign"
}

JSON response

{
  "status": "queued"
}

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
signature_request_delivery_methods	no	The signature requests will be delivered via the given channels. The available options are `'email'`, `'sms'` or an empty list can be provided to skip any signature requests.
signed_document_delivery_method	no	The preferred method to deliver the signed document to the signer. The available options are `'email'`, `'sms'`, `''`. Note: Delivery of the signed document is a legal requirement in most countries. If the `signed_document_delivery_method` is disabled then you will need to deliver the documents to the signers.
multi_factor_authentications	no	Multi factor authentication for signers. Supported MFAs: `sms_verification_code`, `email_verification_code`. (The given contact details must be provided for the signer, e.g. email or mobile number)
redirect_url	no	The URL the signer will be redirected to after signing the contract

Response field	Description
status	'queued'

Signer - re/send sign request

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

Example request

curl -X POST 'https://esignatures.io/api/contracts/1contr11-2222/signers/6signer6-9999/send_contract?token=your-secret-token'

JSON response

{
  "status": "queued"
}

Response field	Description
status	'queued'

Templates

Create

POST /api/templates HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/templates?token=your-secret-token' -d '{"title":"Rental Agreement","document_elements":[{"type":"text_header_one","text":"Conditions"}]}'

JSON request parameters

{
  "title": "Rental Agreement",
  "labels": ["Generic templates", "Acme Client Corp"],
  "document_elements": [
    {
      "type": "text_header_one",
      "text": "Basic terms"
    },
    {
      "type": "text_normal",
      "text": "This agreement is between the rental provider/s and the renter/s."
    }
  ]
}

JSON response

{
  "data": [
    {
      "template_id": "4templ44-6666",
    }
  ]
}

Creates a new template.

Parameter	Required	Description
title	yes	Title of the new template
document_elements	yes	Define the content of the new template using a list of `document_element`-s. Document elements can be headers, formatted text, Signer fields, templates and more. Find the detailed documentation for the `document_elements` below.
labels	no	Labels to be assigned to the template and to its contracts. Labels can help to group your templates and contracts.

Copy (and customize)

POST /api/templates/<template_id>/copy HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/templates/<template-id>/copy?token=your-secret-token' -d '{"title":"Rental Agreement","placeholder_fields":[{"api_key":"business_name","value":"ACME Co"}]}'

JSON request parameters

{
  "title": "Rental Agreement",
  "placeholder_fields": [
    {
      "api_key": "business_name",
      "value": "ACME Co"
    },
    {
      "api_key": "custom_conditions",
      "document_elements": [{"type": "text_header_one", "text": "Special conditions"},{"type": "text_normal", "text": "Information related, but not limited to the development projects and assignments."}]
    }
  ],
  "target_api_key": "another-accounts-secret-token"
}

JSON response

{
  "data": [
    {
      "template_id": "4templ44-6666",
    }
  ]
}

Copy a template, and customize the content using Placeholder fields.

Parameter	Required	Description
title	yes	Title of the new template
placeholder_fields	no	Customize the content of the new template by replacing the Placeholder fields from the source template
placeholder_fields:api_key	no	The "api_key" is the text between the curly brackets in the source contract template. Eg: `{{business_name}}`
placeholder_fields:document_elements	no	Insert headers, formatted text, Signer fields or even templates into the given the Placeholder fields. Find the detailed documentation for the `document_elements` below.
placeholder_fields:value	no	Replace the Placeholder field with simple text.
target_api_key	no	The API Secret token of another account, if the new template should be assigned to that other account.

Query

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

Example request

curl -X GET 'https://esignatures.io/api/templates/4templ44-6666?token=your-secret-token'

JSON response

{
  "data": {
    "template_id": "4templ44-6666",
    "template_name": "Rental Agreement",
    "created_at": "2015-10-24T15:15:35.979",
    "placeholder_fields": ["interest_rate"],
    "signer_fields": ["preferred_term"]
  }
}

Returns the details of the template. The Placeholder keys are specified with the template editor between {{ }} double curly brackets.

Response field	Description
template_id	ID of the template
template_name	Name of the template
created_at	Date of creation
placeholder_fields	List of Placeholder fields in the template
signer_fields	List of the API keys assigned to Signer fields in the template

List

GET /api/templates HTTP/1.1

Example request

curl -X GET 'https://esignatures.io/api/templates?token=your-secret-token'

JSON response

{
  "data": [
    {
      "template_id": "4templ44-6666",
      "template_name": "Rental Agreement"
    }
  ]
}

Returns the list of templates you can send.

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

Collaborators - add

POST /api/templates/<template_id>/collaborators HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/templates/4templ44-6666/collaborators?token=your-secret-token' -d '{"name": "Chris Collaborator"}'

JSON request parameters

{
  "name": "Chris Colleague"
}

JSON response

{
  "data": [
    {
      "template_collaborator_id": "5templcoll5-7777",
      "template_id": "4templ44-6666",
      "name": "Chris Colleague",
      "template_collaborator_editor_url": "https://esignatures.io/contract_template_collaborators/5templcoll5-7777/editor"
    }
  ]
}

Adds a collaborator who can edit the template. The link to the editor can be used as a standalone page, or it can be embedded into an iframe by adding the embedded=yes URL parameter.

Parameter	Required	Description
name	no	The name of the collaborator

Response field	Description
template_collaborator_id	The ID of the collaborator
template_id	The ID of the template
name	The name of the collaborator
template_collaborator_editor_url	The link to edit the template. This URL to the editor can be embedded into an `iframe` by adding the `embedded=yes` URL parameter.

Collaborators - remove

POST /api/templates/<template_id>/collaborators/<template_collaborator_id>/remove HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/templates/4templ44-6666/collaborators/template-collaborator-id>/remove?token=your-secret-token'

JSON response

{
  "status": "queued"
}

Removes the collaborator's permission to edit the template.

Collaborators - list

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

Example request

curl -X GET 'https://esignatures.io/api/templates/4templ44-6666/collaborators?token=your-secret-token'

JSON response

{
  "data": [
    {
      "template_collaborator_id": "5templcoll5-7777",
      "template_id": "4templ44-6666",
      "name": "Chris Colleague",
      "template_collaborator_editor_url": "https://esignatures.io/contract_template_collaborators/5templcoll5-7777/editor"
    }
  ]
}

Returns the list of Collaborators.

Response field	Description
template_collaborator_id	The ID of the collaborator
template_id	The ID of the template
name	The name of the collaborator
template_collaborator_editor_url	The link to edit the template. This URL to the editor can be embedded into an `iframe` by adding the `embedded=yes` URL parameter.

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. The requests timeout is 5 seconds.

Contract sent to signer

JSON body

{
  "status": "contract-sent-to-signer",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "redirect_url": ""
    },
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no"
    }
  }
}

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

Contract signed

JSON body

{
  "status": "contract-signed",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no",
      "contract_pdf_url": "https://aws.com/contracts/1contr11-2222?secret_token=x123y",
      "signers": [
        {
          "id": "6signer6-9999",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "mobile": "+12481234567",
          "company_name": "ACME Corp",
          "sign_page_url": "https://esignatures.io/sign/6signer6-9999",
          "events": [
            {
              "event": "sign_contract",
              "timestamp": "2015-10-22T18:19:35.979"
            }
          ],
          "signer_field_values": {
            "city": "Boston",
            "preferred_contact": "Phone"
          }
        }
      ]
    }
  }
}

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

Field	Description
status	'contract-signed'
secret_token	Your secret token, to authenticate the Webhook notification
id	Id of the contract
title	The unique title of the contract
metadata	The metadata provided in the original request
source	The source of the contract being `api`, `ui` or `zapier`
test	`yes` means test contract, `no` means live contract
contract_pdf_url	The finalized PDF can be accessed via this url. Expires in 7 days following the request. (As part of the json response, this string will be encoded and simple copy paste of the URL won't work.)
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:company_name	Company name for the signer
signers:sign_page_url	Unique sign page URL for the given signer. It can be embedded in an iframe or used standalone. Note: As part of the json response, this string will be encoded and simple copy paste of the URL won't work.
signers:events	Events of the signer
signers:events:event	contract_viewed / disable_reminders / email_contract_sent / email_delivery_failed / email_final_contract_sent / email_spam_complaint / mobile_update_request / reminder_emailed / sign_contract / signature_declined / sms_contract_sent / sms_delivery_failed / sms_final_contract_sent
signers:events:timestamp	Time of the event
signers:signer_field_values	Information provided by the signer for the Signer input fields, eg: Text fields, Dropdowns, Uploaded files. (The signer fields need to have an API key added in the template editor)

Contract withdrawn

JSON body

{
  "status": "contract-withdrawn",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no",
      "signers": [
        {
          "id": "6signer6-9999",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "mobile": "+12481234567",
          "company_name": "ACME Corp"
        }
      ]
    }
  }
}

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

Signer viewed the contract

JSON body

{
  "status": "signer-viewed-the-contract",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "redirect_url": ""
    },
    "contract": {
      "id": "mobile1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no"
    }
  }
}

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

Signer signed the contract

JSON body

{
  "status": "signer-signed",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "redirect_url": "",
      "signer_field_values": {
        "city": "Boston",
        "preferred_contact": "Phone"
      }
    },
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no"
    }
  }
}

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

Signer declined the signature

JSON body

{
  "status": "signer-declined",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "redirect_url": ""
      "events": [
        {
          "event": "signature_declined",
          "reason_for_decline": "Commencement date is 5th of June",
          "timestamp": "2015-10-22T18:19:35.979"
        }
      ]
    },
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no"
    }
  }
}

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

Signer requested a mobile number update

JSON body

{
  "status": "signer-mobile-update-request",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "mobile_new": "+16789123456",
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp",
      "signing_order": "1",
      "auto_sign": "no",
      "redirect_url": ""
    },
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001"
    }
  }
}

This webhook notification is triggered, when the signer requested a Mobile Number update.

Field	Description
id	Id of the signer
mobile	Mobile of the signer
mobile_new	The requested Mobile number
contract:id	Id of the contract

Signer SMS received

JSON body

{
  "status": "sms-incoming",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "signer": {
      "id": "6signer6-9999",
      "name": "Sam Signer",
      "email": "sam@tenants.com",
      "mobile": "+12481234567",
      "company_name": "ACME Corp"
    },
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001"
    },
    "sms": {
      "mobile_from": "+12481234567",
      "sms_text": "Just signed, thank you"
    }
  }
}

This webhook notification is triggered when the signer responds to one of our previous text messages.

Field	Description
id	Id of the signer
contract:id	Id of the contract
sms:mobile_from	The mobile number the message was sent from
sms:sms_text	The text message

Webhook error notifications

JSON body

{
  "status": "error",
  "secret_token": "1234-1234-1234-1234",
  "data": {
    "error_code": "email-delivery-failed",
    "error_message": "Additional error details",
    "contract_id": "1contr11-2222",
    "metadata": "ID0001"
  }
}

Field	Description
error_code	Error code, one of these values: `email-delivery-failed`, `sms-delivery-failed`
error_message	Additional details about the error, when available
metadata	The metadata provided in the original request

Embedded signing

Iframe code

<iframe src="SIGN_PAGE_URL?embedded=yes">
</iframe>

Iframe code with auto-resize

<script src="https://code.jquery.com/jquery-3.4.1.min.js"></script>
<script src="https://cdncf.esignatures.io/staticassets/iframeResizer.4.2.10.min.js"></script>
<iframe
    src="SIGN_PAGE_URL?embedded=yes"
    id="eSignaturesIOIframe"
    onload="iFrameResize({heightCalculationMethod: 'bodyScroll'}, '#eSignaturesIOIframe')"
    style="width: 1px;min-width: 70%;">
</iframe>

Example POST request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/contracts?token=your-secret-token' -d '{"template_id": "4templ44-6666","signers":[{"name":"Sam Signer","email":"sam@tenants.com","signature_request_delivery_methods":[]}]}'

Example iframe code (replace the URL)

<iframe src="https://esignatures.io/sign/11111111-222222-333333?embedded=yes"></iframe>

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

Create a contract with POST#contracts, using the parameter signature_request_delivery_methods=[] to stop sending the initial signature request email (or SMS).
The response json will include a data:contract:signers:sign_page_url for that signer.
Copy the example code and replace the SIGN_PAGE_URL with the sign_page_url, and append the embedded=yes parameter to that URL.

Recommended:

Identification: Specify a multi_factor_authentications parameter when creating the contract, e.g. ['sms_verification_code'], as it is a legal requirement to sufficiently identify each signer.

Optional:

Redirect: Specify the redirect_url when creating the contract, and the signers will be redirected to that URL after signing the docuemnt.
Redirect: Add the redirect_iframe=yes URL parameter to the SIGN_PAGE_URL, to redirect the iframe only, instead of redirecting the full page.

Advanced Placeholder fields

Document elements

Examples

[
  {
    "type": "text_header_two",
    "text": "Special conditions"
  },
  {
    "type": "text_normal",
    "text": "I agree to the above terms and conditions.",
    "text_alignment": "right",
    "text_styles": [
      {
        "offset": 2,
        "length": 6,
        "style": "bold"
      }
    ]
  },
  {
    "type": "signer_field_text",
    "text": "Parent name",
    "signer_field_assigned_to": "first_signer",
    "signer_field_id": "parent-name"
  },
  {
    "type": "signer_field_dropdown",
    "text": "Preferred device",
    "signer_field_assigned_to": "every_signer",
    "signer_field_dropdown_options": "Desktop\nTablet\nMobile"
  },
  {
    "type": "image",
    "image_base64": "PD94bW...yc2lvbj0iM=",
    "image_alignment": "center",
    "image_height_rem": 8
  },
  {
    "type": "table",
    "table_column_styles": [{"align": "center"}, {"align": "right"}],
    "table_cells": [
      [{"text": "Header1", "styles": ["bold"]}, {"text": "Header2", "styles": ["bold"]}],
      [{"text": "cell1"}, {"text": "cell2"}]
    ]
  },
  {
    "type": "template",
    "template_id": "5templ5-777"
  }
]

Insert ad hoc content into the documents using document_elements: text lines, headers, signer fields and more.


Text
type	required	`text_header_one` or `text_header_two`, `text_header_three`, `text_normal`
text	required	The text for the given line.
text_alignment		The alignment of the given line. Options: `center`, `right`, `justified`. By default: `left`
text_styles		Ranges of styles
text_styles:style:offset		The beginning of the range (starting with 0)
text_styles:style:length		The length of the range
text_styles:style:style		The style to apply. Options: `bold`, `italic`, `underline`

List
type	required	`ordered_list_item` or `unordered_list_item`
text	required	The text for the given line.

Signer field
type	required	`signer_field_text` or `signer_field_text_area`, `signer_field_date`, `signer_field_dropdown`, `signer_field_checkbox`, `signer_field_radiobutton`, `signer_field_file_upload`
text	required	The label for the given Signer field.
signer_field_assigned_to	required	Which signer/s can type in the information. Options: `first_signer`, `second_signer`, `last_signer`, `every_signer`
signer_field_required		Whether the Signer field is required. Options: `yes`, `no`
signer_field_dropdown_options		Possible options for the `signer_field_dropdown`, separated by `\n` character
signer_field_id		When provided, the Webhook notifications will include the value typed in for the given Signer field

Image
type	required	`image`
image_base64	required	Base64 encoded `png` or `jpg` image, max 0.5MB
image_alignment		The horizontal position of the image. Options: `center`, `right`. By default: `left`
image_height_rem		Image height (2-38)

Table
type	required	`table`
table_cells	required	A nested list of rows/cells.
table_cells:text		The text in the given cell.
table_cells:styles		The list of styles for the given cell. Options: `bold`, `italic`
table_cells:alignment		Alignment within the cell. Options: `center`, `right`. By default: `left`

Template
type	required	`template`
template_id	required	The ID of the template, when the type is `template`

Support

Click here to contact us...