eSignatures.io API
Quickstart - Send yourself test a contract
Replace the apitest@esignatures.io
to yours:
curl -X POST -H 'Content-type:application/json' 'https://esignatures.io/api/contracts?token=c21bc7' -d '{"template_id": "20ac76c9","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_method": "email",
"signed_document_delivery_method": "email",
"required_identification_methods": ["email", "sms"],
"redirect_url": "https://your-website.com/aftersign",
"embedded_redirect_iframe_only": "no",
}
],
"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: es it ja pl vi id fr zh-CN hu ro hr en-GB sk pt en sl no cz nl sv de rs da |
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_method | no | The preferred method to deliver the initial request to the signer. The available options are 'email' , 'sms' , 'embedded' , '' and 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:required_identification_methods | no | Ensures that the signer's contact details get verified via secret links or 6 digit verification codes. This parameter is automatically set, when not specified. The required_identification_methods list can include email and/or sms , or none of them. Adding multiple methods will result in 2Factor identification. You can switch off any verification by providing an empty list [] , but note that sufficient signer identification is a legal requirement in most jurisdictions. |
signers:redirect_url | no | The signer will be redirected to that URL after signing the contract. |
signers:embedded_redirect_iframe_only | no | When the signing page is embedded within an iframe, setting this flag to yes prevents redirecting the entire page. |
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 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. |
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 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 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 - 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",
"required_identification_methods": ["email", "sms"],
"signature_request_delivery_method": "email",
"signed_document_delivery_method": "email",
"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 |
no | Email to identify the signer | |
mobile | no | Mobile number to identify the signer |
required_identification_methods | no | A list which can include email and/or sms , or none of them. To identify the signer, a secret link or a 6 digit code will be delivered via the given channel. You can remove the identification methods with an empty list [] . Note: Identification is a legal requirement in most countries. You will need to sufficiently identify the signers when our identifications are disabled. |
signature_request_delivery_method | no | The preferred method to deliver the initial request to the signer. The available options are 'email' , 'sms' , 'embedded' , '' . |
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. |
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.
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": {
"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",
"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 generatede PDF file.
Field | Description |
---|---|
status | 'contract-signed' |
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",
"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",
"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",
"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",
"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",
"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 |
Webhook error notifications
JSON body
{
"status": "error",
"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">
</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"
id="eSignaturesIOIframe"
onload="iFrameResize({heightCalculationMethod: 'bodyScroll'}, '#eSignaturesIOIframe')"
style="width: 1px;min-width: 100%;">
</iframe>
Example POST#contracts request to create the contract
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_method":"embedded"}]}'
The sign page can be embedded into an iframe. Steps:
- Create a contract with
POST#contracts
, and specifysignature_request_delivery_method=embedded
for the signer. - The response json will include a
data:contract:signers:sign_page_url
for that signer. - In the 'iframe code' (see example), replace the
SIGN_PAGE_URL
with thesign_page_url
.
Optional:
- Specify the
redirect_url
when creating a contract, and the signers will be redirected to that URL after signing the docuemnt. - Set the
required_identification_methods
to[]
to skip the identification process. Note: it is a legal requirement to identify the signers. If therequired_identification_methods
is[]
you will need to identify the signer via email, SMS or other means to form legally binding contracts. - Set the
embedded_redirect_iframe_only
toyes
to prevent the entire page being redirected. Only the iframe will load the redirect page when set toyes
.
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 , 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