API Reference NAV
 

eSignatures API

Basics - REST API, Token auth, Rate limiting

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. Alternatively, HTTP Basic Auth is also supported: simply use your Secret Token as the username, with no password required. 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, from creation and customization to signer management and finalization. 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 webhooks. In addition to core operations, you can dynamically manage contract content using Markdown-based edits and Placeholder fields. This allows flexible, post-creation updates while preserving the document’s structure and audit trail.

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":[{"placeholder_key":"preferred_term","replace_with_text":"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": [
    {
      "placeholder_key": "package_name",
      "replace_with_text": "Saver"
    },
    {
      "placeholder_key": "repayment_terms",
      "replace_with_markdown": "## Repayment terms\n\n- Payments due: monthly\n- Term: 15 years"
    },
    {
      "placeholder_key": "additional_conditions",
      "replace_with_template": "5templ55-7777"
    }
  ],
  "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 title if not specified). Visible in emails, documents, and dashboard pages.
locale no Language setting for the signer page and emails. Available locales are cz da de el en en-GB es fi fr hr hu id it ja nl no pl pt ro rs sk sl sv vi zh-CN
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', ''). Default is calculated. Note: Delivering the final document is legally required in most regions.
signers: multi_factor_authentications no Multi-factor authentication methods for signers (options: sms_verification_code, email_verification_code, photo_id). Requires corresponding email/mobile contact details. Configurable on the Settings page: require MFA before open or before signing.
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: placeholder_key no The key that corresponds to the placeholder text in the template, e.g., {{interest_rate}}.
placeholder_fields: replace_with_text no Text to replace the placeholder field.
placeholder_fields: replace_with_markdown no Markdown content to replace the placeholder field (see Extended markdown syntax for inserting Signer fields).
placeholder_fields: replace_with_template no Replace the Placeholder field with one of your template's full content.
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).
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 no Enables a fully branded signing flow, with a mandatory storage link retained in the PDF footer.
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 The unique URL for the signer's signing page. It can be embedded in an iframe by appending embedded=yes. The link remains active until the contract expires. For additional identity verification, a 6-digit verification code is recommended.

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",
          "signer_field_values": {
            "city": "Boston",
            "preferred_contact": "Phone"
          }
        }
      ]
    }
  }
}

Returns the contract details, including information about the signers 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 3 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: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'

PDF preview

Generates a PDF preview of the contract and sends a contract-pdf-generated Webhook notification with a direct URL to the PDF once it's ready.

POST /api/contracts/<contract_id>/generate_pdf_preview HTTP/1.1

Example request

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

JSON response

{
  "status": "queued"
}
Response field Description
status 'queued'

Content - Query

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

Example request

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

JSON response

{
  "data": {
    "contract_id": "1contr11-2222",
    "markdown": "# Terms\n\nThis document sets out the agreement between..."
  }
}

Returns the content of the contract.

Response field Description
contract_id The unique ID of the contract.
markdown Content of the contract in markdown format (see Extended markdown syntax below).

Content - Update

POST /api/contracts/<contract_id>/content HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts/1contr11-2222/content?token=your-secret-token' -d '{"edits":[{"find_markdown":" including weekends.","replace_with_markdown":" excluding weekends"}]}'

JSON request parameters

{
  "edits": [
    {
      "find_markdown": " including weekends.",
      "replace_with_markdown":" excluding weekends"
    },
    {
      "find_markdown": "# Additional clauses",
      "replace_with_markdown": "# Additional clauses\n\nThese will be the new additional conditions under the Additional clauses section."
    }
  ]
}

JSON response

{
  "status": "queued"
}

Updates the contract content.

Parameter Required Description
edits yes List of Markdown edit operations applied to the contract content. Each edit finds existing content and replaces it with new Markdown.
edits:find_markdown yes Markdown content to find and replace. Can be an exact snippet or a section heading (e.g. ## Payment Terms). When a heading is provided, the entire section is matched. Set to blank ("") to replace the entire contract content.
edits:replace_with_markdown yes Markdown content to insert in place of the matched content. Set to blank ("") to remove the matched content.

Placeholder fields - Query

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

Example request

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

JSON response

{
  "data": [
    {
      "placeholder_key": "package_name",
      "replace_with_text": "Saver"
    },
    {
      "placeholder_key": "repayment_terms",
      "replace_with_markdown": "## Repayment terms\n\n- Payments due: monthly\n- Term: 15 years"
    },
    {
      "placeholder_key": "additional_conditions",
      "replace_with_template": "[template content]"
    }
  ]
}

Returns the Placeholder field values currently assigned to the contract.

Response field Description
placeholder_fields: placeholder_key The placeholder key (without curly braces), e.g. interest_rate.
placeholder_fields: replace_with_text Plain text used to replace the Placeholder field.
placeholder_fields: replace_with_markdown Markdown content used to replace the Placeholder field.
placeholder_fields: replace_with_template When the placeholder field specifies a template this endpoint always returns [template content]

Placeholder fields - Update

POST /api/contracts/<contract_id>/placeholder_fields HTTP/1.1

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts/1contr11-2222/placeholder_fields?token=your-secret-token' -d '{"placeholder_key":"package_name","replace_with_text":"Premium"}'

JSON request parameters

{
  "placeholder_fields": [
    {
      "placeholder_key": "package_name",
      "replace_with_text": "Premium"
    },
    {
      "placeholder_key": "repayment_terms",
      "replace_with_markdown": "## Repayment terms\n\n- Payments due: monthly\n- Term: 24 months"
    },
    {
      "placeholder_key": "additional_conditions",
      "replace_with_template": "5templ55-7777"
    }
  ]
}

JSON response

{
  "status": "queued"
}

Updates the Placeholder field values for an unsigned contract. Only the Placeholder fields included in the request are updated. Each Placeholder field can be replaced with plain text, Markdown content, or the full content of one of your templates.

Parameter Required Description
placeholder_fields yes List of Placeholder fields to update.
placeholder_fields: placeholder_key yes The key that corresponds to the placeholder text in the template, e.g. {{interest_rate}}.
placeholder_fields: replace_with_text no Plain text to replace the Placeholder field.
placeholder_fields: replace_with_markdown no Markdown content to replace the Placeholder field.
placeholder_fields: replace_with_template no Template ID of the template whose full content should replace the Placeholder field.
Response field Description
status queued

Signers - 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
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, photo_id). Requires corresponding email/mobile contact details. Configurable on the Settings page: require MFA before open or before signing.
redirect_url no URL where the signer will be redirected after signing.
Response field Description
status 'queued'

Signers - 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
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, photo_id). Requires corresponding email/mobile contact details.
redirect_url no URL where the signer will be redirected after signing.
Response field Description
status 'queued'

Signers - Resend 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'

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

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","markdown":"## Terms\n\nThis document sets out the agreement between..."}'

JSON request parameters

{
  "title": "Rental Agreement",
  "labels": ["Generic Agreement", "Acme Client Corp"],
  "markdown": "# Terms\n\nThis document sets out the agreement between..."
}

JSON response

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

Creates a new template.

Parameter Required Description
title yes The title of the new template.
markdown yes Defines the content of the new template (see Extended markdown syntax for inserting Signer fields).
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.com/api/templates/4templ44-6666?token=your-secret-token'

JSON response

{
  "data": {
    "template_id": "4templ44-6666",
    "title": "Rental Agreement",
    "created_at": "2015-10-24T15:15:35.979",
    "placeholder_fields": ["interest_rate"],
    "signer_field_ids": ["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.
title The title of the template.
created_at The date and time the template was created.
placeholder_fields List of Placeholder fields in the template.
signer_field_ids List of the Signer field ID-s assigned to Signer fields in the template.

Update 

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

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/templates/4templ44-6666?token=your-secret-token' -d '{"title":"Rental Agreement"}'

JSON request parameters

{
  "title": "Rental Agreement",
  "labels": ["Generic templates", "Acme Client Corp"]
}

JSON response

{
  "status": "queued"
}

Updates the template.

Parameter Required Description
title no The title the new template.
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":[{"placeholder_key":"business_name","replace_with_text":"ACME Co"}]}'

JSON request parameters

{
  "title": "Rental Agreement",
  "placeholder_fields": [
    {
      "placeholder_key": "business_name",
      "replace_with_text": "ACME Co"
    },
    {
      "placeholder_key": "special_conditions",
      "replace_with_markdown": "# Special conditions\n\nInformation related, but not limited to the development projects and assignments."
    },
    {
      "placeholder_key": "additional_conditions",
      "replace_with_template": "5templ55-7777"
    }
  ],
  "target_secret_token": "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: placeholder_key no The placeholder_key is the text between the curly brackets in the source contract template. Eg: {{business_name}}
placeholder_fields: replace_with_text no Replace the Placeholder field in the new template with simple text.
placeholder_fields: replace_with_markdown no Markdown content to replace the placeholder field within the original template (see Extended markdown syntax for inserting Signer fields).
placeholder_fields: replace_with_template no Replace the Placeholder field in the new template with one of your existing template's full content.
target_secret_token no The API Secret token of another account, if the new template should be assigned to that other account.

Delete 

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

Example request

curl -X POST 'https://esignatures.com/api/templates/4templ44-6666/delete?token=your-secret-token'

JSON response

{
  "status": "queued"
}

Deletes the template.

List 

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",
      "title": "Rental Agreement"
    }
  ]
}

Returns a list of available templates.

Response field Description
template_id The unique ID of the template.
title The title of the template.

Collaborators - Add

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

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.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",
      "email": "chris@acme.com",
      "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
email no The email of the collaborator. Email invitation is sent when provided.
Response field Description
template_collaborator_id The ID of the collaborator
template_id The ID of the template
name The name of the collaborator
email The email of the collaborator
template_collaborator_editor_url URL to access the template editor (can be embedded into an iframe using the embedded=yes parameter).

Collaborators - List

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",
      "email": "chris@acme.com",
      "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
email The email address of the collaborator
template_collaborator_editor_url URL to access the template editor (can be embedded into an iframe using the embedded=yes parameter).

Collaborators - Remove

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

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.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.

Content - Query 

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

Example request

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

JSON response

{
  "data": {
    "template_id": "4templ44-6666",
    "markdown": "# Terms\n\nThis document sets out the agreement between..."
  }
}

Returns the content of the template.

Response field Description
template_id The unique ID of the template.
markdown Content of the template in markdown format (see Extended markdown syntax below).

Content - Update 

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

Example request

curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/templates/4templ44-6666/content?token=your-secret-token' -d '{"edits":[{"find_markdown":" including weekends.","replace_with_markdown":" excluding weekends"}]}'

JSON request parameters

{
  "edits": [
    {
      "find_markdown": " including weekends.",
      "replace_with_markdown":" excluding weekends"
    },
    {
      "find_markdown": "# Additional clauses",
      "replace_with_markdown": "# Additional clauses\n\nThese will be the new additional conditions under the Additional clauses section."
    }
  ]
}

JSON response

{
  "status": "queued"
}

Updates the template content.

Parameter Required Description
edits yes List of Markdown edit operations applied to the template content. Each edit finds existing content and replaces it with new Markdown.
edits:find_markdown yes Markdown content to find and replace. Can be an exact snippet or a section heading (e.g. ## Payment Terms). When a heading is provided, the entire section is matched. Set to blank ("") to replace the entire template content.
edits:replace_with_markdown yes Markdown content to insert in place of the matched content. Set to blank ("") to remove the matched content.

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.

Each request includes an X-Signature-SHA256 header with an HMAC-SHA256 signature of the request body, generated using your secret token, for secure verification.

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 15 seconds.

Whitelisting: The Webhook notifications are triggered from one of these IP addresses: 100.26.156.173, 3.223.86.53, 34.234.34.248, 52.6.7.167, 54.80.221.23, 54.88.203.251, 98.85.113.207, 98.88.182.139

Contract sent to signer

JSON body

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

This webhook is triggered when a contract is sent to a signer for signature.

Contract reminder sent to signer

JSON body

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

This webhook is triggered when a contract reminder is sent to a signer.

Contract signed

JSON body

{
  "status": "contract-signed",
  "data": {
    "contract": {
      "id": "1contr11-2222",
      "title": "Sample NDA",
      "metadata": "ID0001",
      "source": "api",
      "test": "no",
      "contract_pdf_url": "https://aws.com/contracts/1contr11-2222?secret_token=x123y",
      "signers": [
        {
          "id": "6signer6-9999",
          "name": "Sam Signer",
          "email": "sam@tenants.com",
          "mobile": "+12481234567",
          "company_name": "ACME Corp",
          "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'
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 3 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: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",
  "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 triggers whenever a contract is withdrawn or a signer declines to sign.

Signer viewed the contract

JSON body

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

This webhook is triggered when a signer views the contract for the first time.

Signer signed the contract

JSON body

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

This webhook 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",
  "data": {
    "reason_for_decline": "Commencement date is 5th of June",
    "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 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",
  "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",
  "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",
  "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:

  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:

Markdown syntax

Examples

# Rental Agreement

This agreement is between the rental provider/s and the renter/s.

- The renter agrees to pay rent on the 1st of each month.
- The rental provider agrees to maintain the property in good condition.

## Special conditions `{"header_counter": "yes"}`

I agree to the above **terms and conditions**. `{"alignment": "center"}`

Parent name `{"line_type": "text-input", "input_type": "only_first_signer", "input_required": "yes", "signer_field_id": "parent-name"}`

Preferred device `{"line_type": "select-input", "input_type": "only_first_signer", "select_values": ["Desktop", "Tablet", "Mobile"]}`

I accept the privacy policy `{"line_type": "checkbox", "input_type": "every_signer", "input_required": "yes"}`

| Header 1 | Header 2 |
| -------- | -------- |
| cell 1   | cell 2   |

Use the standard markdown syntax to write the document content, and apply the extended syntax to add Signer fields and customize generic content (alignment, header counters). The extended syntax is a JSON-formatted string appended to the end of a markdown line, surrounded by backticks.

Standard markdown is used for headers, paragraphs, bold (**bold**), italic (*italic*), ordered and unordered lists, tables, and images. The extended JSON config is optional on any line, and required to define Signer fields.

Param descriptions
alignment Alignment of the line. Options: center, right, justify. Defaults to left. Applicable to headers and paragraphs.
default_value The value pre-filled into the field when the signer opens the document. Applicable to text-input, select-input, checkbox, radiobutton.
header_counter Prepends an auto-incremented counter to the header text. Value: yes. Applicable to headers.
input_type Specifies which signer(s) can fill in the field. Options: only_first_signer, only_second_signer, only_last_signer, every_signer. Required for Signer fields.
input_required Whether the signer must fill in the field. Options: yes, no. Applicable to all Signer fields.
line_type Specifies the type of Signer field. Required for Signer fields. Options: text-input, text-area, date, select-input, checkbox, radiobutton, file-upload.
masked Ensures the value entered by the signer remains confidential — hidden from other signers and masked in the final PDF. Options: yes, no. Applicable to text-input.
placeholder_text Hint text shown in the background of the field, guiding the signer on what to enter. Applicable to text-input.
select_values List of options for a dropdown, e.g. ["Desktop", "Tablet", "Mobile"]. Applicable to select-input.
signer_field_id Unique identifier for the field, used in Webhook notifications and the signer_fields API parameter to include or pre-fill the field's value. Applicable to all Signer fields.

Testing

You can create a free eSignatures account for testing and development. All features work exactly the same as on paid, production accounts (including API calls, template creation, contract sending, and webhook notifications).

Test contracts are automatically marked with a “demo” stamp, making it easy to distinguish them from live agreements. For best practice, we recommend keeping separate accounts for production and test environments.

Templates can be copied between accounts manually (simply select all and use Ctrl + C / Ctrl + V), allowing you to replicate your setup quickly.

Support

Click here to contact us...