API Reference NAV
 

eSignatures API

Quick start: 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 'https://esignatures.io/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.io 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/. We recommend using Webhook notifications to stay updated on contract statuses instead.

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.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",
  "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.io/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.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 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.io/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.io/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
email 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.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 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
email 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.io/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.io/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.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 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.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",
    }
  ]
}

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.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 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.io/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.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 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.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 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.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.

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.io.

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, such as 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.io/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.io/sign/11111111-222222-333333?embedded=yes"></iframe>

Steps to Embed the Sign Page:

  1. Create a Contract: Use the POST#contracts API and include the parameter signature_request_delivery_methods=[] to prevent sending the initial signature request email or SMS.
  2. Get the Signer URL: The API response will include the signer's URL in the field data:contract:signers:sign_page_url.
  3. Embed the Iframe: Copy the example iframe code and replace SIGN_PAGE_URL with the sign_page_url, appending ?embedded=yes to the URL.

Optional Settings:

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

Click here to contact us...