### Basic Embedded Signing Iframe
Source: https://esignatures.com/docs/api/index
This is a basic example of how to embed the eSignatures signing page into your application using an iframe.
```html
```
--------------------------------
### Advanced Placeholder Fields Example
Source: https://esignatures.com/docs/api/index
This JSON structure demonstrates the use of various advanced placeholder fields for document customization, including text, images, and tables.
```json
[{"type":"text_header_two","text":"Special conditions","auto_counter":"yes"},{"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"}]
```
--------------------------------
### Embedded Signing Iframe with Auto-Resize
Source: https://esignatures.com/docs/api/index
This example demonstrates embedding the eSignatures signing page with auto-resizing capabilities using jQuery and iframeResizer.
```html
```
--------------------------------
### Create Contract API Request
Source: https://esignatures.com/docs/api/index
Example of a POST request to the contracts API to create a contract, with options to prevent initial email/SMS delivery and specify signer details.
```curl
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"}]}'
```
--------------------------------
### Send a Test Contract
Source: https://esignatures.com/docs/api/index
Example of sending a test contract using the eSignatures API. This demonstrates a POST request to the contracts endpoint with a JSON payload containing template ID and signer information. Replace placeholder values with your actual data.
```curl
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts?token=11111111-2222-3333-4444-555555555555' -d '{"template_id": "44444444-5555-6666-7777-888888888888","signers":[{"name":"Sam Signer","email":"apitest@esignatures.com"}]}'
```
--------------------------------
### Query Template Details
Source: https://esignatures.com/docs/api/index
Retrieves the details of a specific template, including its ID, title, creation date, placeholder fields, and signer field IDs. This is useful for getting comprehensive information about a template before using it.
```APIDOC
GET /api/templates/ HTTP/1.1
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.
`document_elements` | List of document elements with their types and text.
```
```curl
curl -X GET 'https://esignatures.com/api/templates/4templ44-6666?token=your-secret-token'
```
--------------------------------
### Iframe Code with Specific Sign Page URL
Source: https://esignatures.com/docs/api/index
An example of an iframe code snippet where the SIGN_PAGE_URL should be replaced with the actual URL for a specific signing process.
```html
```
--------------------------------
### Get Contract Details
Source: https://esignatures.com/docs/api/index
Retrieves detailed information about a specific contract, including its status, title, metadata, and signer information. Contracts older than two weeks may have incomplete data. Avoid frequent polling; use Webhooks for status updates.
```APIDOC
GET /api/contracts/ HTTP/1.1
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.
```
```curl
curl -X GET 'https://esignatures.com/api/contracts/1contr11-2222?token=your-secret-token'
```
--------------------------------
### Create New Template
Source: https://esignatures.com/docs/api/index
Creates a new template in the system. This operation requires a title and can optionally include document elements and labels for organization.
```APIDOC
POST /api/templates HTTP/1.1
Parameters:
- 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.
- labels (no): Optional labels assigned to the template and its contracts. Labels help organize and group templates and contracts.
Example Request:
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/templates?token=your-secret-token' -d '{"title":"Rental Agreement","document_elements":[{"type":"text_header_one","text":"Conditions"}]}'
JSON Request Parameters:
{"title":"Rental Agreement","labels":["Generic templates","Acme Client Corp"],"document_elements":[{"type":"text_header_one","text":"Basic terms"},{"type":"text_normal","text":"This agreement is between the rental provider/s and the renter/s."}]}
JSON Response:
{"data":[{"template_id":"4templ44-6666",}]}
```
--------------------------------
### Generate PDF Preview
Source: https://esignatures.com/docs/api/index
Generates a PDF preview of a contract and triggers a `contract-pdf-generated` Webhook notification with a direct link to the PDF once it is ready.
```APIDOC
POST /api/contracts//generate_pdf_preview HTTP/1.1
Response field |
Description
---|---
status | 'queued'
```
```curl
curl -X POST 'https://esignatures.com/api/contracts/1contr11-2222/generate_pdf_preview?token=your-secret-token'
```
--------------------------------
### Placeholder Fields Configuration
Source: https://esignatures.com/docs/api/index
Defines how placeholder fields in templates are replaced with dynamic content. Supports text replacement and insertion of custom document elements.
```APIDOC
placeholder_fields | no | Used to replace text placeholders in the template, e.g., {{interest_rate}}. Can be replaced with text or formatted content.
api_key | no | The key that corresponds to the placeholder text in the template, e.g., {{interest_rate}}.
document_elements | no | Inserts custom elements such as headers, text, or images into placeholders.
value | no | Text to replace the placeholder field.
```
--------------------------------
### eSignatures API - Contracts and Signing
Source: https://esignatures.com/docs/api/index
This section details the eSignatures API endpoints for managing contracts and the signing process, including creating contracts, embedding signing pages, and handling redirects.
```APIDOC
POST /api/contracts
Creates a new contract.
Parameters:
token (string, required): Your secret API token.
signature_request_delivery_methods (array, optional): Methods to use for signature requests (e.g., 'email', 'sms'). Set to [] to prevent initial delivery.
signers (array of objects, required): Details of the signers.
- name (string, required): Signer's name.
- email (string, required): Signer's email address.
template_id (string, required): The ID of the template to use for the contract.
redirect_url (string, optional): URL to redirect the signer to after signing.
Returns:
Object containing contract details, including signer URLs.
- data.contract.signers.sign_page_url (string): The URL for the signer to access the signing page.
Embedded Signing:
To embed the signing page, use an iframe with the `sign_page_url` and append `?embedded=yes`.
For auto-resizing, include jQuery and iframeResizer scripts.
Redirects:
- `redirect_url` parameter during contract creation redirects the entire page after signing.
- Appending `?redirect_iframe=yes` to the `SIGN_PAGE_URL` redirects only the iframe content.
```
--------------------------------
### List Templates
Source: https://esignatures.com/docs/api/index
Retrieves a list of all available templates. This endpoint is useful for browsing or selecting templates to work with.
```APIDOC
GET /api/templates HTTP/1.1
Response field |
Description
---|---
`template_id` | The unique ID of the template.
`title` | The title of the template.
```
```curl
curl -X GET 'https://esignatures.com/api/templates?token=your-secret-token'
```
--------------------------------
### Copy and Customize Template
Source: https://esignatures.com/docs/api/index
Copies an existing template and allows for content customization using placeholder fields. This is useful for creating variations of a base template.
```APIDOC
POST /api/templates//copy HTTP/1.1
Parameters:
- 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.
- 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.
Example Request:
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/templates//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",}]}
```
--------------------------------
### Signer Configuration
Source: https://esignatures.com/docs/api/index
Configures multi-factor authentication and redirect URLs for signers. Multi-factor authentication requires corresponding contact details.
```APIDOC
signers:
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.
```
--------------------------------
### Create Contract
Source: https://esignatures.com/docs/api/index
Creates a new contract using a specified template and collects signatures from designated signers. Supports various configurations for delivery methods, custom branding, and testing.
```APIDOC
POST /api/contracts HTTP/1.1
Request Body Parameters:
- template_id (string, required): Specifies which template to use for the contract. The `template_id` is displayed when editing the template.
- title (string, optional): Unique title for the contract (defaults to template title if not specified). Visible in emails, documents, and dashboard pages.
- locale (string, optional): 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 (string, optional): Custom data that can be attached to the contract.
- expires_in_hours (string, optional): Sets the expiry time (in hours) for the contract.
- custom_webhook_url (string, optional): Custom URL for webhook notifications, overrides the default URL specified in your API settings.
- assigned_user_email (string, optional): Assigns one of your eSignatures users to manage the contract and receive notifications.
- labels (array of strings, optional): Assigns specific labels to the contract. Labels are displayed on the dashboard and are searchable, making it easier to group contracts.
- test (string, optional): When `yes`, it marks the contract as a 'demo' with no fees charged for sending it.
- save_as_draft (string, optional): When `yes`, it saves the contract as a draft for further editing via the UI, instead of sending it.
- signers (array of objects, required): List of individuals required to sign the contract.
- name (string, required): Name of the signer.
- email (string, conditional): Email address of the signer.
- mobile (string, conditional): Mobile number of the signer. Non-US numbers must start with the country code, e.g., +61....
- company_name (string, optional): Signer's company name.
- signing_order (string, optional): Defines the sequence in which signers will receive the contract. Signers with the same number will be notified simultaneously.
- auto_sign (string, optional): 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 (array of strings, optional): 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 (string, optional): Preferred delivery method for the signed document (`'email'`, `'sms'`, `''`). Default is calculated. Note: Delivering the final document is legally required in most regions.
- placeholder_fields (array of objects, optional): Fields to populate in the contract template.
- api_key (string): The API key for the placeholder.
- value (string): The value to populate.
- document_elements (array of objects, optional): Elements to embed in the document.
- type (string): Type of document element (e.g., 'image').
- image_base64 (string): Base64 encoded image data.
- signer_fields (array of objects, optional): Fields associated with a specific signer.
- signer_field_id (string): The ID of the signer field.
- default_value (string): The default value for the signer field.
- emails (object, optional): Custom email settings for the contract.
- signature_request_subject (string): Subject for the signature request email.
- signature_request_text (string): Body text for the signature request email.
- final_contract_subject (string): Subject for the final contract email.
- final_contract_text (string): Body text for the final contract email.
- cc_email_addresses (array of strings): Email addresses to CC on contract emails.
- reply_to (string): Reply-to email address for contract emails.
- custom_branding (object, optional): Custom branding settings for the contract.
- company_name (string): Company name to display.
- logo_url (string): URL of the company logo.
Response Body:
- status (string): The status of the contract creation request (e.g., 'queued').
- data (object): Contains details about the created contract.
- contract (object): Information about the contract.
- id (string): Unique identifier for the contract.
- status (string): Current status of the contract (e.g., 'sent').
- title (string): Title of the contract.
- metadata (string): Custom metadata attached to the contract.
- source (string): The source of the contract (e.g., 'api').
- test (string): Indicates if the contract was created in test mode.
- signers (array of objects): List of signers for the contract.
- id (string): Unique identifier for the signer.
- name (string): Name of the signer.
- email (string): Email address of the signer.
- mobile (string): Mobile number of the signer.
- company_name (string): Company name of the signer.
- sign_page_url (string): URL where the signer can access the document to sign.
```
```curl
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/contracts?token=your-secret-token' -d '{"template_id": "4templ44-6666","signers":[{"name":"Sam Signer","email":"sam@tenants.com","mobile":"+12481234567"}],"placeholder_fields":[{"api_key":"preferred_term","value":"24 months"}], "test": "yes"}'
```
```json
{
"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%",
"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
{
"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"
}
]
}
}
}
```
--------------------------------
### eSignatures API - General Usage
Source: https://esignatures.com/docs/api/index
Provides general information on interacting with the eSignatures REST API. It covers the use of POST requests for actions, token-based authentication, and the JSON data format. It also warns about CORS errors for browser-based requests and explains the rate limiting policy.
```APIDOC
POST https://esignatures.com/api/?token=your-secret-token
---
**Description:**
General guidelines for using the eSignatures API. API calls follow REST principles and use JSON data. Authentication is handled via a token parameter in the URL. Browser requests may trigger CORS errors.
**Authentication:**
Token auth via URL parameter (`token=your-secret-token`). Locate your Secret Token on the API page after logging in.
**Data Format:**
JSON data is used for API requests and responses.
**Rate Limiting:**
Adaptive rate limiting is employed to prevent overuse and malicious attacks. Avoid repeatedly polling contract information (e.g., GET /api/contracts/). Use Webhook notifications for status updates.
**CORS Policy:**
API requests made from browsers will trigger a CORS error to protect your Secret Token.
```
--------------------------------
### Image Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for image elements. Supports base64 encoded images, alignment, height, and download enablement.
```APIDOC
Image:
type: required, string. Value: `image`.
image_base64: required, string. The base64-encoded `png` or `jpg` image (max 0.5MB).
image_alignment: optional, string. The alignment of the image. Options: `center`, `right`. Defaults to: `left`.
image_height_rem: optional, integer. Height of the image in rem units (range: 2 to 38).
image_download_enabled: optional, string. Allow signers to download the original image. Options: `yes`, `no`. Default is `no`.
```
--------------------------------
### Template Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for inserting templates into a document. Requires a template ID.
```APIDOC
Template:
type: required, string. Value: `template`.
template_id: required, string. The ID of the template to be inserted.
```
--------------------------------
### eSignatures API - Contracts Endpoint
Source: https://esignatures.com/docs/api/index
This section details the Contracts API, explaining how to manage contracts through API calls. It highlights that sending a contract requires a single API call and that signature collection and notifications are handled automatically. Webhook notifications are recommended for status updates.
```APIDOC
POST https://esignatures.com/api/contracts HTTP/1.1
---
**Description:**
Manages contracts through the API. Sending a contract requires a single API call, after which signatures are collected, and notifications are sent at each stage of the contract's lifecycle via Webhook notifications.
**Authentication:**
Token auth via URL parameter.
**Rate Limiting:**
Adaptive rate limiting based on usage patterns. Avoid polling contract information; use Webhook notifications instead.
**Parameters:**
- `token`: Your API secret token (URL parameter).
**Example Request Body:**
```json
{
"template_id": "your-template-id",
"signers": [
{
"name": "Signer Name",
"email": "signer@example.com"
}
]
}
```
**Related Endpoints:**
- Webhooks (for status updates)
- Templates (for template management)
```
--------------------------------
### List Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for list items, supporting ordered and unordered lists. Specifies text content and nesting depth.
```APIDOC
List:
type: required, string. Options: `ordered_list_item` or `unordered_list_item`.
text: required, string. The text of the list item.
depth: optional, integer. Specifies the nesting level for the list. Default is 0.
```
--------------------------------
### Text Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for normal text elements. Supports text content, alignment, text styling for ranges, and indentation depth.
```APIDOC
Text:
type: required, string. Value: `text_normal`.
text: required, string. The content for the text element.
text_alignment: optional, string. Options: `center`, `right`, `justify`. Defaults to: `left`.
text_styles: optional, array. Specifies styles for ranges of text within the element.
text_styles:style:offset: integer. Starting position of the styled text (0-based index).
text_styles:style:length: integer. Length of the styled text range.
text_styles:style:style: string. The style to apply. Options: `bold`, `italic`, `underline`.
depth: optional, integer. Specifies the indentation level for the text. Default is 0.
```
--------------------------------
### Contract Signed Webhook
Source: https://esignatures.com/docs/api/index
This webhook is triggered once all signers have signed the contract. It provides a link to download the signed PDF and details about the signers and their actions.
```APIDOC
Webhook Event: contract-signed
Description: Triggered once all signers have signed the contract. Includes a link to download the signed PDF.
Fields:
- status: 'contract-signed'
- secret_token: Your secret token for authenticating the webhook.
- data.contract.id: ID of the contract.
- data.contract.title: The unique title of the contract.
- data.contract.metadata: Metadata included in the original request.
- data.contract.source: Source of the contract: `api`, `ui` or `zapier`
- data.contract.test: Indicates whether it's a test contract (`yes`).
- data.contract.contract_pdf_url: URL to access the signed PDF (expires after 7 days). URL is encoded in the JSON response.
- data.contract.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.
JSON Body:
```json
{
"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"
}
}
]
}
}
}
```
```
--------------------------------
### Table Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for table elements. Supports defining cells with text, styles, and alignment.
```APIDOC
Table:
type: required, string. Value: `table`.
table_cells: required, nested list. Defines the rows and cells. Each cell can contain text and optional styles.
table_cells:text: optional, string. The content of the cell.
table_cells:styles: optional, list. The list of styles for the cell. Options: `bold`, `italic`.
table_cells:alignment: optional, string. Cell alignment. Options: `center`, `right`. Defaults to: `left`.
```
--------------------------------
### eSignatures API - Contracts Management
Source: https://esignatures.com/docs/api/index
Details the management of contracts via the eSignatures API. Sending a contract is a single API call, with subsequent signature collection and notifications handled automatically. Webhooks are used for lifecycle event notifications.
```APIDOC
# 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.
```
--------------------------------
### Header Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines the structure for header elements in a document. Supports different header levels, text content, alignment, and automatic counters.
```APIDOC
Header:
type: required, string. Options: `text_header_one`, `text_header_two` or `text_header_three`.
text: required, string. The content for the header.
text_alignment: optional, string. Options: `center`, `right`, `justify`. Defaults to: `left`.
auto_counter: optional, string. If set to "yes", a counter will be prepended to the header text.
```
--------------------------------
### Signer Viewed Contract Webhook
Source: https://esignatures.com/docs/api/index
This webhook is triggered when a signer views the contract for the first time. It contains signer and contract details.
```APIDOC
Webhook Event: signer-viewed-the-contract
Description: Triggered when a signer views the contract for the first time.
JSON Body:
```json
{
"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"
}
}
}
```
```
--------------------------------
### Email Configuration
Source: https://esignatures.com/docs/api/index
Customizes the subject and body text for signature request and final contract emails. Supports dynamic insertion of signer names and CC addresses.
```APIDOC
emails:
signature_request_subject | no | The subject line of the email sent to collect signatures.
signature_request_text | no | The body text of the email sent to signers. Use __FULL_NAME__ to insert the signer's name dynamically.
final_contract_subject | no | The subject of the email sent with the final signed contract.
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.
cc_email_addresses | no | Email addresses to CC when sending the signed PDF contract.
reply_to | no | Custom 'reply-to' address for emails (defaults to your support email if not specified).
```
--------------------------------
### Signer Fields Configuration
Source: https://esignatures.com/docs/api/index
Pre-fills fields that the signer needs to complete within the contract. Requires the 'Signer field ID' from the template editor.
```APIDOC
signer_fields | no | Pre-fills fields that the signer must complete.
signer_field_id | no | The "Signer field ID" in the template editor for the given Signer input field.
default_value | no | Default value for the input field (Use `1` to tick checkboxes, `YYYY-mm-dd` for dates).
```
--------------------------------
### List Template Collaborators
Source: https://esignatures.com/docs/api/index
Retrieves a list of all collaborators associated with a specific template. This helps in managing access and permissions for template editing.
```APIDOC
GET /api/templates//collaborators HTTP/1.1
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).
```
```curl
curl -X GET 'https://esignatures.com/api/templates/4templ44-6666/collaborators?token=your-secret-token'
```
--------------------------------
### Custom Branding Configuration
Source: https://esignatures.com/docs/api/index
Applies custom branding elements such as company name and logo URL to outgoing communications.
```APIDOC
custom_branding:
company_name | no | Custom company name displayed as the sender.
logo_url | no | Custom logo URL (recommended PNG size: 400px).
```
--------------------------------
### Signer Field Descriptions
Source: https://esignatures.com/docs/api/index
Defines various types of signer fields, including text, text areas, dates, dropdowns, checkboxes, radio buttons, and file uploads. Specifies assignment, requirements, options, default values, placeholders, masking, and IDs.
```APIDOC
Signer field:
type: required, string. Options: `signer_field_text`, `signer_field_text_area`, `signer_field_date`, `signer_field_dropdown`, `signer_field_checkbox`, `signer_field_radiobutton`, `signer_field_file_upload`.
text: required, string. The label for the Signer field.
signer_field_assigned_to: required, string. Specifies which signer(s) can fill in the field. Options: `first_signer`, `second_signer`, `last_signer`, `every_signer`.
signer_field_required: optional, string. Indicates if the signer field is required. Options: `yes`, `no`.
signer_field_dropdown_options: optional, string. Possible options for `signer_field_dropdown`, separated by the `\n` character.
signer_field_default_value: optional, string. The default text that will appear in the field when the signer opens the document.
signer_field_placeholder_text: optional, string. The placeholder text that appears in the background of the field, guiding the signer on what information to enter.
signer_field_masked: optional, string. Ensures that the information entered by signers remains confidential and masked in the final PDF. Options: `yes`, `no`.
signer_field_id: optional, string. Unique identifier for the field, used in Webhook notifications to include the field’s value.
```
--------------------------------
### Contract Response Fields
Source: https://esignatures.com/docs/api/index
Details the fields returned in a contract response, including status, unique identifiers, metadata, source, test status, and signer information.
```APIDOC
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`.
```
--------------------------------
### Add Template Collaborator
Source: https://esignatures.com/docs/api/index
Adds a collaborator to a template, granting them editing permissions. The collaborator can be invited via email if an email address is provided. The response includes a URL to the editor, which can be embedded.
```APIDOC
POST /api/templates//collaborators HTTP/1.1
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).
```
```curl
curl -X POST -H 'Content-type:application/json' 'https://esignatures.com/api/templates/4templ44-6666/collaborators?token=your-secret-token' -d '{"name": "Chris Collaborator"}'
```
--------------------------------
### Delete Template
Source: https://esignatures.com/docs/api/index
Deletes a specified template from the system. This action is irreversible and should be used with caution.
```APIDOC
POST /api/templates//delete HTTP/1.1
```
```curl
curl -X POST 'https://esignatures.com/api/templates/4templ44-6666/delete?token=your-secret-token'
```
--------------------------------
### Signer Signed Contract Webhook
Source: https://esignatures.com/docs/api/index
This webhook is triggered when a signer signs the contract. It includes signer details and the values entered by the signer for input fields.
```APIDOC
Webhook Event: signer-signed
Description: Triggered when a signer signs the contract. Includes signer details and values entered for input fields.
JSON Body:
```json
{
"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"
}
}
}
```
```
--------------------------------
### Update Template
Source: https://esignatures.com/docs/api/index
Updates an existing template identified by its template ID. You can modify the title, document elements, and labels.
```APIDOC
POST /api/templates/ HTTP/1.1
Parameters:
- title (no): The title the new template.
- document_elements (no): Defines the content of the template using a list of `document_elements`. These can include headers, formatted text, signer fields, and more.
- labels (no): Optional labels assigned to the template and its contracts. Labels help organize and group templates and contracts.
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","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:
{"status":"queued"}
```