eSignatures.io API

Quick start: Send yourself test a contract

Replace the [email protected] 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":"[email protected]"}]}'

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":"[email protected]","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/esignaturesio-custom-webhook",
  "assigned_user_email": "[email protected]",
  "labels": ["MA", "Rental"],
  "test": "no",
  "save_as_draft": "no",
  "signers": [
    {
      "name": "Benny Bell",
      "email": "[email protected]",
      "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": ["[email protected]", "[email protected]"],
    "reply_to": "[email protected]"
  },
  "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": "[email protected]",
          "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.io 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": "[email protected]",
          "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":"[email protected]"}'

JSON request parameters

{
  "name": "Sam Signer",
  "email": "[email protected]",
  "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":"[email protected]", "name":"Sam Signer-Smith"}'

JSON request parameters

{
  "name": "Sam Signer",
  "email": "[email protected]",
  "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

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.

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

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.

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.

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	URL to access the template editor (can be embedded into an iframe using the `embedded=yes` parameter).

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	URL to access the template editor (can be embedded into an iframe using the `embedded=yes` parameter).

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.

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.io 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": "[email protected]",
      "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": "[email protected]",
          "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": "[email protected]",
          "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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": "[email protected]",
      "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://cdncf.esignatures.io/staticassets/iframeResizer.4.2.10.min.js"></script>
<iframe
    src="SIGN_PAGE_URL?embedded=yes"
    id="eSignaturesIOIframe"
    onload="iFrameResize({heightCalculationMethod: 'bodyScroll'}, '#eSignaturesIOIframe')"
    style="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":"[email protected]"}]}'

Example iframe code (replace the URL)

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

Steps to Embed the Sign Page:

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.
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 the sign_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 the SIGN_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

Click here to contact us...