eSignatures API
Quick start: Send yourself test a contract
Replace the apitest@esignatures.com
to yours:
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts?token=c21bc7' -d '{"template_id": "20ac76c9","signers":[{"name":"Sam Signer","email":"apitest@esignatures.com"}]}'
Basics - REST API, Token auth, Rate limiting
POST https://esignatures.com/api/contracts HTTP/1.1
curl -X POST 'https://esignatures.com/api/<action>?token=your-secret-token'
The API calls follow REST principles and use JSON data. Authentication is handled via a token parameter in the URL. You can locate your Secret Token on the API page after logging into your eSignatures account. Please note that API requests made from browsers will trigger a CORS error to protect your Secret Token.
Rate Limiting: To prevent accidental overuse and guard against malicious attacks, our service employs adaptive rate limiting. This means the rate limits adjust based on usage patterns. It is important to avoid repeatedly 'polling' contract information through the API, such as with GET /api/contracts/
Parameter | Description |
---|---|
token | Your API secret token |
Contracts
Contracts can be fully managed through the API. Sending a contract requires just a single API call, after which signatures are collected, and notifications are sent at each stage of the contract's lifecycle via Webhook notifications.
New
POST /api/contracts HTTP/1.1
Example request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/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",
"title": "Loan Agreement - Saver package",
"locale": "en",
"metadata": "ID0001",
"expires_in_hours": "48",
"custom_webhook_url": "https://your-website.com/esignatures-custom-webhook",
"assigned_user_email": "colleague@your-business.com",
"labels": ["MA", "Rental"],
"test": "no",
"save_as_draft": "no",
"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.com/sign/6signer6-9999"
}
]
}
}
}
This request generates a contract and, by default, sends it to the signers via the chosen communication channels to collect their signatures.
Parameter | Required | Description |
---|---|---|
template_id | yes | Specifies which template to use for the contract. The template_id is displayed when editing the template. |
title | no | Unique title for the contract (defaults to template name if not specified). Visible in emails, documents, and dashboard pages. |
locale | no | Language setting for the signer page and emails. Available locales are hu hr ro id zh-CN fr cz sk no pt pl rs en-GB de da it ja es vi nl en sv sl |
metadata | no | Custom data that can be attached to the contract. |
expires_in_hours | no | Sets the expiry time (in hours) for the contract. |
custom_webhook_url | no | Custom URL for webhook notifications, overrides the default URL specified in your API settings. |
assigned_user_email | no | Assigns one of your eSignatures users to manage the contract and receive notifications. |
labels | no | Assigns specific labels to the contract. Labels are displayed on the dashboard and are searchable, making it easier to group contracts. |
test | no | When yes , it marks the contract as a 'demo' with no fees charged for sending it. |
save_as_draft | no | When yes , it saves the contract as a draft for further editing via the UI, instead of sending it. |
signers | yes | List of individuals required to sign the contract. |
signers: name | yes | Name of the signer. |
signers: email | cond | Email address of the signer. |
signers: mobile | cond | Mobile number of the signer. Non-US numbers must start with the country code, e.g., +61.... |
signers: company_name | no | Signer's company name. |
signers: signing_order | no | Defines the sequence in which signers will receive the contract. Signers with the same number will be notified simultaneously. |
signers: auto_sign | no | When yes , automatically adds the signer's signature to the document when set to yes . Only applicable for your own signature, not for clients. |
signers: signature_request_delivery_methods | no | Defines how the signature request will be delivered (options: email , sms ). An empty list skips sending the request. Default is calculated. |
signers: signed_document_delivery_method | no | Preferred delivery method for the signed document (email , sms ). Delivery is legally required in most regions. Default is calculated. |
signers: multi_factor_authentications | no | Multi-factor authentication methods for signers (options: sms_verification_code , email_verification_code ). Requires corresponding contact details. |
signers: redirect_url | no | URL where the signer will be redirected after signing. |
placeholder_fields | no | Used to replace text placeholders in the template, e.g., {{interest_rate}}. Can be replaced with text or formatted content (see the Advanced placeholder fields section below). |
placeholder_fields: api_key | no | The key that corresponds to the placeholder text in the template, e.g., {{interest_rate}}. |
placeholder_fields: document_elements | no | Inserts custom elements such as headers, text, or images into placeholders (see the Advanced placeholder fields section below). |
placeholder_fields: value | no | Text to replace the placeholder field. |
signer_fields | no | Pre-fills fields that the signer must complete. |
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 | Default value for the input field (Use 1 to tick checkboxes, YYYY-mm-dd for dates). |
signer_fields: select_position | no | For select fields, the position of the pre-selected option (starting from 0). |
emails: signature_request_subject | no | The subject line of the email sent to collect signatures. |
emails: signature_request_text | no | The body text of the email sent to signers. Use __FULL_NAME__ to insert the signer's name dynamically. |
emails: final_contract_subject | no | The subject of the email sent with the final signed contract. |
emails: final_contract_text | no | The body text of the email sent with the final signed contract. Use __FULL_NAME__ to insert the signer's name dynamically. |
emails: cc_email_addresses | no | Email addresses to CC when sending the signed PDF contract. |
emails: reply_to | no | Custom 'reply-to' address for emails (defaults to your support email if not specified). |
custom_branding: company_name | no | Custom company name displayed as the sender. |
custom_branding: logo_url | no | Custom logo URL (recommended PNG size: 400px). |
Response field | Description |
---|---|
status | queued |
contract:id | The unique ID for the contract. |
contract:title | The unique title assigned to the contract. |
contract:metadata | Custom metadata attached to the contract request. |
contract:source | The origin of the contract, e.g., api , ui or zapier |
contract:test | Whether the contract is a test (yes ) or a live contract (no ). |
contract:signers:id | Unique ID for the signer. |
contract:signers:name | Name of the signer. |
contract:signers:email | Signer's email address. |
contract:signers:mobile | Signer's mobile number. |
contract:signers:company_name | Company name of the signer. |
contract:signers:sign_page_url | UniqueThe unique URL for the signer's signing page. This can be embedded in an iframe using embedded=yes . |
Query
GET /api/contracts/<contract_id> HTTP/1.1
Example request
curl -X GET 'https://esignatures.com/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.com/sign/6signer6-9999",
"events": [
{
"event": "sign_contract",
"timestamp": "2015-10-22T18:19:35.979"
}
],
"signer_field_values": {
"city": "Boston",
"preferred_contact": "Phone"
}
}
]
}
}
}
Returns the contract details, including information about the signers, contract events, signer events, and any values entered by the signers.
Rate Limiting and Limited Data: It is important to avoid repeatedly 'polling' contract information through the API. We recommend using Webhook notifications to stay updated on contract statuses instead." Contracts older than two weeks may not return complete data in the response, and frequent polling can lead to blocked requests. To stay updated on contract statuses, we recommend using Webhook notifications.
Response field | Description |
---|---|
id | The unique ID for the contract. |
status | Status of the contract: sent , signed or withdrawn . |
title | The unique title of the contract |
metadata | Custom metadata attached to the contract request. |
source | The origin of the contract, e.g., api , ui or zapier |
test | Whether the contract is a test (yes ) |
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 | Unique ID for the signer. |
signers:name | Name of the signer. |
signers:email | Signer's email address. |
signers:mobile | Signer's mobile number. |
signers:company_name | Company name of the signer. |
signers:sign_page_url | UniqueThe unique URL for the signer's signing page. This can be embedded in an iframe using embedded=yes . |
signers:events | Events related to the signer’s actions, such as signing the contract. |
signers:events:event | Describes the type of event that occurred, such as 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 | Timestamp when the event occurred. |
signers:signer_field_values | Values provided by the signer for Signer fields, like Text fields, Dropdowns, or file uploads. These fields must be defined in the template editor. |
Withdraw
Withdrawn contracts can no longer be signed, and signed contracts cannot be withdrawn.
Withdrawing a contract does not delete any 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.com/api/contracts/1contr11-2222/withdraw?token=your-secret-token'
JSON response
{
"status": "queued"
}
Response field | Description |
---|---|
status | 'queued' |
Contract signers
This section handles all individuals assigned as signers for a contract.
Add
POST /api/contracts/<contract_id>/signers/<signer_id> HTTP/1.1
Example request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts/1contr11-2222/signers?token=your-secret-token' -d '{"name":"Sam Signer-Smith","email":"sam@tenants.com"}'
JSON request parameters
{
"name": "Sam Signer",
"email": "sam@tenants.com",
"mobile": "+1 541 754 3010",
"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"
}
JSON response
{
"status": "queued"
}
Signers can be added to contracts using this API endpoint. Note: Adding a new signer does not automatically send an email with the contract.
Parameter | Required | Description |
---|---|---|
name | no | Name of the signer |
no | Email address of the signer | |
mobile | no | Mobile number of the signer. Non-US mobile numbers must start with the country code, eg +44.... |
company_name | no | Company name for the signer |
signing_order | no | Defines the sequence in which signers will receive the contract. Signers with the same number will be notified simultaneously. |
auto_sign | no | When yes , automatically adds the signer's signature to the document when set to yes . Only applicable for your own signature, not for clients. |
signature_request_delivery_methods | no | Defines how the signature request will be delivered (options: email , sms ). An empty list skips sending the request. Default is calculated. |
signed_document_delivery_method | no | Preferred delivery method for the signed document (email , sms ). Delivery is legally required in most regions. Default is calculated. |
multi_factor_authentications | no | Multi-factor authentication methods for signers (options: sms_verification_code , email_verification_code ). Requires corresponding contact details. |
redirect_url | no | URL where the signer will be redirected after signing. |
Response field | Description |
---|---|
status | 'queued' |
Update
POST /api/contracts/<contract_id>/signers/<signer_id> HTTP/1.1
Example request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/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 through this API request. Note: The contract is not automatically emailed when the signer's information is updated.
Parameter | Required | Description |
---|---|---|
name | no | Name of the signer |
no | Email address of the signer | |
mobile | no | Mobile number of the signer. Non-US mobile numbers must start with the country code, eg +44.... |
company_name | no | Company name for the signer |
signature_request_delivery_methods | no | Defines how the signature request will be delivered (options: email , sms ). An empty list skips sending the request. Default is calculated. |
signed_document_delivery_method | no | Preferred delivery method for the signed document (email , sms ). Delivery is legally required in most regions. Default is calculated. |
multi_factor_authentications | no | Multi-factor authentication methods for signers (options: sms_verification_code , email_verification_code ). Requires corresponding contact details. |
redirect_url | no | URL where the signer will be redirected after signing. |
Response field | Description |
---|---|
status | 'queued' |
Re/send sign request
POST /api/contracts/<contract_id>/signers/<signer_id>/send_contract HTTP/1.1
Example request
curl -X POST 'https://esignatures.com/api/contracts/1contr11-2222/signers/6signer6-9999/send_contract?token=your-secret-token'
JSON response
{
"status": "queued"
}
Response field | Description |
---|---|
status | 'queued' |
Delete
POST /api/contracts/<contract_id>/signers/<signer_id>/delete HTTP/1.1
Example request
curl -X POST 'https://esignatures.com/api/contracts/1contr11-2222/signers/6signer6-9999delete?token=your-secret-token'
JSON response
{
"status": "queued"
}
Response field | Description |
---|---|
status | 'queued' |
Templates
New template
POST /api/templates HTTP/1.1
Example request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/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 | The title of the new template. |
document_elements | yes | Defines the content of the new template using a list of document_elements . These can include headers, formatted text, signer fields, and more. Find the detailed documentation abount the document_elements below. |
labels | no | Optional labels assigned to the template and its contracts. Labels help organize and group 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.com/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",
}
]
}
Copies an existing template and allows for content customization using Placeholder fields.
Parameter | Required | Description |
---|---|---|
title | yes | The title for the new template. |
placeholder_fields | no | Customizes the content of the new template by replacing 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 template
GET /api/templates/<template_id> HTTP/1.1
Example request
curl -X GET 'https://esignatures.com/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 a specific template, including the Placeholder fields and signer fields.
Response field | Description |
---|---|
template_id | The unique ID of the template. |
template_name | The name of the template. |
created_at | The date and time the template was created. |
placeholder_fields | List of Placeholder fields in the template. |
signer_fields | List of the API keys assigned to Signer fields in the template |
List templates
GET /api/templates HTTP/1.1
Example request
curl -X GET 'https://esignatures.com/api/templates?token=your-secret-token'
JSON response
{
"data": [
{
"template_id": "4templ44-6666",
"template_name": "Rental Agreement"
}
]
}
Returns a list of available templates.
Response field | Description |
---|---|
template_id | The unique ID of the template. |
template_name | The name of the template. |
Template collaborators
Add collaborator
POST /api/templates/<template_id>/collaborators HTTP/1.1
Example request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/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.com/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 | URL to access the template editor (can be embedded into an iframe using the embedded=yes parameter). |
List collaborators
GET /api/templates/<template_id>/collaborators HTTP/1.1
Example request
curl -X GET 'https://esignatures.com/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.com/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 | URL to access the template editor (can be embedded into an iframe using the embedded=yes parameter). |
Remove collaborator
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.com/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.
Webhooks
Webhooks allow you to receive real-time notifications for specific events, such as when a contract is signed. When an event occurs, a POST request is sent to the Webhook URL specified in your API dashboard. To set up a webhook, simply configure your server to accept POST requests at a designated URL. Webhook data is sent as JSON in the body of the POST request.
If a webhook request fails (i.e., does not return a 2xx response), eSignatures will retry the webhook every hour, up to six times. The timeout for each request is 20 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 is triggered when a contract is sent to a 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",
"events": [
{
"event": "sign_contract",
"timestamp": "2015-10-22T18:19:35.979"
}
],
"signer_field_values": {
"city": "Boston",
"preferred_contact": "Phone"
}
}
]
}
}
}
This webhook is triggered once all signers have signed the contract. It includes a link to download the signed PDF.
Field | Description |
---|---|
status | 'contract-signed' |
secret_token | Your secret token for authenticating the webhook. |
id | ID of the contract. |
title | The unique title of the contract. |
metadata | Metadata included in the original request. |
source | Source of the contract: api , ui or zapier |
test | Indicates whether it's a test contract (yes ). |
contract_pdf_url | URL to access the signed PDF (expires after 7 days). URL is encoded in the JSON response. |
signers | List of signers added to the contract. |
signers:id | ID of the signer. |
signers:name | Name of the signer |
signers:email | Email of the signer |
signers:mobile | Mobile number of the signer. |
signers:company_name | Company name of the signer |
signers:events | List of events related to the signer. |
signers:events:event | Type of event, e.g., 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 | Timestamp of the event. |
signers:signer_field_values | Values provided by the signer for the Signer fields, such as Text fields, Dropdowns, or Uploaded files. |
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 is triggered when a 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 is triggered when a signer views the contract for 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 is triggered when a signer signs the contract. It includes signer details and the values entered by the signer for the input fields.
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 is triggered when a signer declines to sign the contract. It includes the reason for declining, if provided.
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 is triggered when a signer requests to update their mobile number.
Field | Description |
---|---|
id | The ID of the signer |
mobile | Mobile of the signer |
mobile_new | The new mobile number requested by the signer. |
contract:id | The 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 is triggered when the signer replies to a text message from eSignatures.
Field | Description |
---|---|
id | The ID of the signer |
contract:id | ID of the contract |
sms:mobile_from | The mobile number the SMS was sent from. |
sms:sms_text | The content of 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, email-delivery-failed or sms-delivery-failed |
error_message | Additional information about the error, if available. |
metadata | 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://cdn.jsdelivr.net/npm/iframe-resizer@4.2.10/js/iframeResizer.min.js"></script>
<iframe
src="SIGN_PAGE_URL?embedded=yes"
id="eSignaturesIframe"
onload="iFrameResize({heightCalculationMethod: 'bodyScroll'}, '#eSignaturesIframe')"
style="min-width: 100%; border: none;">
</iframe>
Example POST request
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts?token=your-secret-token' -d '{"template_id": "4templ44-6666","signers":[{"name":"Sam Signer","email":"sam@tenants.com"}]}'
Example iframe code (replace the URL)
<iframe src="https://esignatures.com/sign/11111111-222222-333333?embedded=yes"></iframe>
Steps to Embed the Sign Page:
- Create a Contract: Use the
POST#contracts
API and include the parametersignature_request_delivery_methods=[]
to prevent sending the initial signature request email or SMS. - Get the Signer URL: The API response will include the signer's URL in the field
data:contract:signers:sign_page_url
. - Embed the Iframe: Copy the example iframe code and replace
SIGN_PAGE_URL
with thesign_page_url
, appending?embedded=yes
to the URL.
Recommended Settings:
- Signer Identification: Include the
multi_factor_authentications
parameter when creating the contract, such as['sms_verification_code']
, to meet legal requirements for verifying each signer’s identity.
Optional Settings:
- Redirect After Signing: Specify a
redirect_url
when creating the contract, and the signer will be redirected to that URL after signing the document. - Redirect After Signing: If you only want the iframe to redirect (without affecting the entire page), append the
redirect_iframe=yes
parameter to theSIGN_PAGE_URL
.
Advanced Placeholder fields
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_cells": [
[{"text": "Header1", "styles": ["bold"]}, {"text": "Header2", "styles": ["bold"]}],
[{"text": "cell1", "alignment": "right"}, {"text": "cell2"}]
]
},
{
"type": "template",
"template_id": "5templ5-777"
}
]
You can insert various types of content into documents using document_elements
, such as text, headers, signer fields, images, and more.
Field descriptions
Text | ||
type | required | The type of text element. Options: text_header_one or text_header_two , text_header_three , text_normal . |
text | required | The content for the text element. |
text_alignment | The alignment of the text. Options: center , right , justified . Defaults to: left |
|
text_styles | An array specifying styles for ranges of text within the element. | |
text_styles:style:offset | Starting position of the styled text (0-based index). | |
text_styles:style:length | Length of the styled text range. | |
text_styles:style:style | The style to apply. Options: bold , italic , underline . |
|
List | ||
type | required | The type of list item. Options: ordered_list_item or unordered_list_item |
text | required | The text of the list item. |
depth | Specifies the nesting level for the list. Default is 0. | |
Signer field | ||
type | required | The type of Signer field. Options: 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 Signer field. |
signer_field_assigned_to | required | Specifies which signer(s) can fill in the field. Options: first_signer , second_signer , last_signer , every_signer |
signer_field_required | Indicates if the signer field is required. Options: yes , no |
|
signer_field_dropdown_options | Possible options for signer_field_dropdown , separated by the \n character |
|
signer_field_id | Unique identifier for the field, used in Webhook notifications to include the field’s value. | |
Image | ||
type | required | image |
image_base64 | required | The base64-encoded png or jpg image (max 0.5MB). |
image_alignment | The alignment of the image. Options: center , right . Defaults to: left |
|
image_height_rem | Height of the image in rem units (range: 2 to 38). | |
Table | ||
type | required | table |
table_cells | required | A nested list defining the rows and cells. Each cell can contain text and optional styles. |
table_cells:text | The content of the cell. | |
table_cells:styles | The list of styles for the cell. Options: bold , italic |
|
table_cells:alignment | Cell alignment. Options: center , right . Defaults to: left |
|
Template | ||
type | required | template |
template_id | required | The ID of the template to be inserted. |
Support