Introducing the E-Sign API
These docs are intended for developers who wish to integrate our digital signature API to build new or expand upon existing systems
- To start using this API you will require an Authentication token. Please request one from info@e-sign.co.uk
- You can interact with our staging server at https://xyz.e-sign.co.uk/api/{version}
- Once ready you can switch to our live server at https://app.e-sign.co.uk/api/{version}
Overview
API endpoints
To use the E-sign API you will need to send a JSON formatted request to one of the following endpoints.
- Sandbox:
https://xyz.e-sign.co.uk/api/v1
- Live:
https://app.e-sign.co.uk/api/v1
The resources and http methods required for each request are listed in the sections below.
Please note: The databases for both endpoints are separate so you will need to create an account on both the staging sandbox and live servers.
Authentication
E-sign offer two levels of API access. Basic account level, which is a single, standard E-sign account or master account level which can control many standard accounts, reffered to as sub accounts.
Authorization
To access the API, from all types of API access, each call must contain an Authorization header which contains your unique API token:
Authorization: Token token=“YOUR_AUTHORIZATION_TOKEN”
The token may differ between the live and sandbox environments.
You will also need to pass a Content-Type
header (e.g. application/json
), with each request.
Each token is unique to an account. See an example connection below.
Basic Account Access
A basic account can have many users, with the main user being the admin user (required on sign up). You can supply the parameter user_token
with each API call to act and interact with the API as a different account user. If no user_token
parameter is supplied the API will default to calls as the admin user. A list of account users and their user_token
can be found by Retrieving and account - as the default admin user.
Parameter | Description |
---|---|
auth_email | account user email (optional) |
Master Account API Access
If you have been granted master account API access you are required to send an additional sub_account_id
parameter with each API call containing the ID of the sub account you wish to make API calls from. Account IDs can be found within your reseller admin area. You can also optionally send an additional user_token
parameter containing the user_token
of one of the account users (see Basic Account Access above).
Parameter | Description |
---|---|
sub_account_id | required ID of the sub account |
user_token | account user’s token (optional - found in the account call) |
Creating Documents
Documents are created by first uploading an ‘Original File’ and then using the file ID (file[“id”])
of the created 'Original File’ to create the Document.
One Original File can be used to create many Documents.
Please see the diagram below for further clarification.
HTTP response codes
The following response codes are sent with the server’s response:
Code | Description |
---|---|
200 | The request has succeeded |
201 | The request has been fulfilled and resulted in a new resource being created. |
400 | The request could not be understood by the server, usually due to malformed syntax. The response body will contain more details in the form of an array. |
401 | Unauthorized. The client has not provided a valid Authorization HTTP header. |
403 | Forbidden. The client does not have permission to access this resource. |
404 | Not Found. The requested resource was not found. |
422 | Unprocessable Entity. Could not process a POST request because the request is invalid. The response body will contain more details in the form of an array. |
423 | The resource is locked and requires extra verification |
500 | Internal Server Error. The server encountered an error while processing your request and failed. Please report this to the eSign support team. |
Request format
Requests to the E-Sign API should be sent in JSON format within the request body.
Response format
Responses from the E-Sign API are sent in JSON format.
Account
An e-Sign account is an account which can have multiple users. The account is required to have one account admin user on creation.
Retrieve an account
GET /users/account
The above request returns JSON structured like this:
{
"name":"test company",
"id":1063,
"credits":2,
"credits_empty_at":null,
"master_account_id":1,
"documents_count":0,
"is_grace_period":false,
"subscription":{
"card_number":null,
"next_renewal_at":"2015-02-16T18:09:16+00:00",
"state":"trial",
"payQueryment_type":"stripe",
"gocardless_pre_authorization_id":null,
"amount":"1.50",
"limits":{
"documents":null,
"users":null
},
"currency":{
"label":"GBP",
"symbol":"£",
"location":"United Kingdom"
},
"payment_update_required":null,
"plan_id":58,
"name":"PAYG"
},
"users":[
{
"name":"Admin name",
"email":"admin@testaccount.com",
"admin":true,
"avatar":null,
"user_token":"4ptUrbjfMMNXAgVAwNCe"
},{
"name":"Another User",
"email":"another_user@testaccount.com",
"admin":false,
"avatar":null,
"user_token":"ynmHx6bmqJpHAgGYQ1JG"
}]
}
Returns the full details of the account including the current subscription and all users associated with the account.
A user’s user_token
can be used later to send specific requests relating to that user, e.g updating the user’s details.
Create An Account (Not available yet)
POST /account
Description
Creates an account with an admin user (required) with profile information. The account needs to be associated to a plan.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | String | True | Account name |
String | True | Admin user email (unique) | |
password | String | True | Admin user’s password. |
password_confirmation | String | True | confirmation of the Admin user’s password |
currency | String | True | The currency used for billing (gbp/usd/eur) |
plan_id | Integer | True | The plan the account will be associated with |
master_account_id | Integer | True | The master account ID this account belongs to (defaults to e-Sign) |
profile | Object | False | A profile object. |
profile [job_title] |
String | False | Name of the company (Also used as account name) |
profile [contact_number] |
String | False | Contact number of the Admin user |
profile [address] |
String | False | Address of the Admin user |
profile [dob] |
String | False | Date of bith of the Admin User |
Attachment File
An attachment file. This is created and then attached to a document.
Listing Attachment Files
GET /attachment_files
The above request returns JSON structured like this:
{
"total": 1,
"entries": [
{
"id": "id",
"date": "2015-01-21T14:10:36+00:00",
"processing": true,
"filename": "pdf-sample.pdf",
"file_size": "1337",
"url": ".../pdf-sample.pdf",
"href": "http://app.e-sign.co.uk/api/v1/original_files/id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
]
}
Description
Returns the full details of all attachment file entries.
Retrieving Attachment
GET /attachment_files/:id
The above request returns JSON structured like this:
{
"id": "id",
"date": "2015-01-21T14:10:36+00:00",
"processing": true,
"filename": "pdf-sample.pdf",
"file_size": "1337",
"url": "../pdf-sample.pdf",
"href": "../id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
Description
Retrieves an information about a specific attachment file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | Attachment File UUID |
Creating A File
POST /attachment_files
{
"base64_title": "a test title",
"base64_doc": "XJ0eHJlZgoyMTYKJSVFT0YK....",
"base64_ext": ".pdf"
}
The above request returns JSON structured like this:
{
"success": true,
"src": "../test_file.pdf",
"file": {
"id": "id",
"date": "2015-01-21T14:54:43+00:00",
"processing": true,
"filename": "test_file.pdf",
"file_size": 1337,
"url": "../test_file.pdf",
"href": "../id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
}
Description
Add a new attachment file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
base64_title | String | True | Title of the file. e.g. 'E-Sign Documentation’, in plain-text. |
base64_doc | String | True | The raw file, encoded as Base64. |
base64_ext | String | True | The extension of the file, e.g. “pdf”, in plain-text |
Deleting A File
Description
Delete an attachment file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | UUID of the attachment file. Multiple IDs can be specified, delimited using a comma (,) |
Archive A File
PUT /attachment_files/:id
{
"ids": [1337, 1338],
"archive": true
}
The above request returns JSON structured like this:
{
"success":true
}
Description
Archive an attachment file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ids | Array[String] | True | An array of Attachment File UUIDs |
archive | Boolean | True | Should always be true to archive. |
Document Signer
A signer associated with a document and with the ability to sign a document.
Show A Document Signer
GET /signers/:id
When successful, the above request returns JSON structured like this:
{
"name":"John Doe",
"email_address":"john@doe.com",
"last_viewed":null,
"response_ip":null,
"response_os":null,
"response_browser":null,
"response_browser_version":null,
"passport_check":null,
"driving_licence_check":null,
"utility_bill_check":null,
"signed_at":null,
"status":"Pending",
"id":"9ai6uGMwtKJg7z3FuvdjY-WZf39-LA",
"document_id": "LjLiF8V0GWrhOubvNuII9KwIZJ3Jig",
"current":false,
"custom_signature":{
"creation_method":"drawn",
"text":null,
"image":"https://esign-development.s3-eu-west-1.amazonaws.com/custom_sig.jpg"
},
"registered":false
}
If the signer is not found, you will get a 404 response like this:
{
"error":"not found"
}
Description
Use the Signer’s ID to show a document signer.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | The Signer’s UUID |
Sign a document
PUT /signers/:id
{
"agreed": true,
"system": {
"os": "Mac",
"browser": "Chrome",
"browser_version": 39
},
"required_additional_fields": [
{
"field_name": "Favourite Food",
"field_value": "Pancakes"
}
],
"pin": "1234", (optional)
}
The above request returns JSON structured like this:
{
"success":true,
"document": {
"title":"Example document title",
"description":"This is an optional description",
"status":"Pending",
"id":"EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
"date":"2015-01-21T19:00:21+00:00",
"href":"http://esign.dev/api/documents/
EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
"signed_file":{
"url":"https://esign.s3-eu-west-1.amazonaws.com/
uploads/document/file/000/011/880/
example-document-title-NFYrgxB8zTA.pdf?
AWSAccessKeyId=AKAQ2Q&Signature=
41ZVirW7FtO2lqqsLB0%3D&Expires=1421877272"
},
"original_file":{
"id":"8pkJ-pHg_bW1vksyVeDSibyu9GzA-Q",
"url":"https://esign.s3-eu-west-1.amazonaws.com/
uploads/original_file/Estimate__1_.pdf?
AWSAccessKeyId=AKIAIJMAQ&Signature=nB%2BDlD7t
&Expires=1421867422",
"filename":"Estimate_94_Dragons_Design_Ltd__1_.pdf",
"processing":null
},
"attachment_file":{
"id":"ct_XnYDJE0Irr7OB2-74cW8jM8Nv2g",
"url":"https://esign.s3-eu-west-1.amazonaws.com/
uploads/attachment_file/file/000/000/038/
Invoice45.pdf?AWSAccessKeyId=AKIAIJH7DQ2
&Signature=UPMl8WEoBWznI%3D&Expires=1421822",
"filename":null,
"processing":null
},
"author":{
"current":true,
"name":"Test User",
"email":"test@test.com"
},
"signer_id":null,
"additional_info":"More information for all to read",
"signers":[
{
"name":"tom jones",
"email_address":"tom@example.com",
"last_viewed":null,
"response_ip":"127.0.0.1",
"response_os":"Mac",
"response_browser":"Chrome",
"response_browser_version":39,
"passport_check":null,
"driving_licence_check":null,
"utility_bill_check":null,
"signed_at":"2015-01-21T21:42:14+00:00",
"status":"Signed",
"id":"2kTC7ESKGkeukhcRfpA27tyKHZV2JQ",
"current":false,
"registered":false,
"required_fields":[]
},
{
"id":"9ai6uGMwtKJg7z3FuvdjY-WZf39-LA",
"name":"John Doe",
"email_address":"john@doe.com",
"last_viewed":null,
"response_ip":null,
"response_os":null,
"response_browser":null,
"response_browser_version":null,
"passport_check":null,
"driving_licence_check":null,
"utility_bill_check":null,
"signed_at":null,
"status":"Pending",
"current":false,
"registered":false
}
],
"labels":[]
}
}
Description
Update a document’s signer to reflect the signing of a document
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | The Signer’s UUID. |
agreed | Boolean | True | Agreement to sign the document, 'true’ signs the document. 'false’ is treated as a decline. |
required_additional_fields | Array[Object] | Depends | The answers to the additional required fields requested when the document was created. Only required if any additional fields were requested. |
system | Object | True | System Information to bind the user to the signature |
system [os] |
String | True | Signers’s Operating System, e.g “Windows 10” |
system [browser] |
String | True | Signers’s Browser, e.g. “Microsoft Edge” |
string [browser_version] |
String | True | Signer’s Browser’s Version, e.g. “25.10586.0.0” |
pin | String | False | Access pin code if document has been restricted by sender |
Response Details
Success if signed successful, errors if unsuccessful. The document object is returned with the response and shows the url of the signed document with the new signature.
Document
A document created from an originally uploaded document (Original File) which becomes the document for all parties to sign. This document will be modified to include the signature of all signers.
List Documents
GET /documents
{
"inbox": true,
"limit": 10,
"status": "pending",
"label": "NDA"
}
The above request returns JSON structured like this (More information about the document will be contained within the response. This is just an example)
{
"entries": [
{
"name": "foo",
"description": "bar"
},
{
"name": "foo",
"description": "bar"
}
],
"total": 2
}
Description
Returns a list of documents within a specified criteria.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
inbox | Boolean | False | If true then retrieve current user’s document inbox. |
limit | Integer | False | Maximum amount of document objects to retrieve (Default 10, Max 100). |
offset | Integer | False | Where to start listing inbox documents. |
status | String | False | List only documents with specified status. |
label | String | False | List only documents with specified label name. |
Create A Document
POST /documents
{
"documents": [
{
"title": "Example document title",
"desc": "This is an optional description",
"additional_info": "More information",
"file": {
"id": "ECbl-z6oRGokeiPCTb1beNBeTrr6Ow"
},
"append_signatures": true,
"signers": [
{
"name": "Tom Jones",
"email": "tom@example.com",
"country_code": "+44",
"phone": "0123456789",
"additional_signer_fields": [
{
"field_name": "add text-0",
"field_placeholder":"signer prompt",
"field_required": true,
"field_type": "text",
"positions" : [
{
"x": 50.7,
"y": 50.8,
"page": "1",
"email": "tom@example.com"
}
]
},
{
"field_name": "checkbox-1",
"field_required": true,
"field_type": "checkbox",
"positions" : [
{
"x": 12.6,
"y": 28.6,
"page": "2",
"email": "tom@example.com"
}
]
},
{
"field_name": "Initials",
"field_required": true,
"field_type": "initials",
"positions" : [
{
"x": 22.8,
"y": 27.6,
"page": "2",
"email": "tom@example.com"
}
]
},
{
"field_name": "signature-0",
"field_required": true,
"field_type": "signature",
"positions" : [
{
"x": 40.0,
"y": 40.0,
"page": "1",
"email": "tom@example.com"
}
]
},
{
"field_name": "Date Stamp",
"field_required": true,
"field_type": "date",
"positions" : [
{
"x": 10.3,
"y": 10.9,
"page": "5",
"email": "tom@example.com"
}
]
},
{
"field_name":"qrcode",
"field_required": false,
"field_type":"qrcode",
"positions":[
{
"x":43.94,
"y":50.39,
"page":1,
"email": "tom@example.com"
}
]
},
{
"field_name":"text to be rendered",
"field_required":false,
"field_type":"embossed-text",
"positions":[
{
"x":64.21,
"y":54.37,
"page":4,
"email": "tom@example.com"
}
]
}
]
},
{
"name": "John Doe",
"email": "john@example.com"
}
],
"attachment_files": [
"HJywldp77kkvqnS-j0JmmxP4qMHBEw"
],
"stop_api_email": false,
"synchronous": false,
"placeholders":[
{
"x":40.0,
"y":40.0,
"page":"1",
"email":"tom@example.com"
}
]
}
]
}
The above request returns JSON structured like this
{
"title": "Example document title",
"description": "This is an optional description",
"status": "Pending",
"last_interaction": "2016-05-16T11:40:55+01:00",
"attachment_files": [
{
"id": 872,
"filename": "pdf-sample.pdf",
"processing": null,
"url": "https://esign-production.s3-eu-west-1.amazonaws.com/uploads/attachment_file/../pdf-sample.pdf"
}
],
"signers": [
{
"name": "John Doe",
"email_address": "john@example.com",
"last_viewed": null,
"response_ip": null,
"response_os": null,
"response_browser": null,
"response_browser_version": null,
"passport_check": null,
"driving_licence_check": null,
"utility_bill_check": null,
"verification_check": false,
"signed_at": null,
"verified": false,
"document_id": "Ry0KwggO22w4YvgQ",
"id": "wK3WMtWPR241mnqg",
"status": "Pending",
"current": false,
"synchronous_current": true,
"registered": false,
"aml_document": null,
"placeholder": false,
"required_additional_fields": [
{
"id":246850,
"field_name": "add text-0",
"field_required": true,
"field_type": "text",
"field_value": "",
"id": 1111,
"positions" : [
{
"x": 50.7,
"y": 50.8,
"page": "1"
}
]
},
{
"id":246853,
"field_name": "checkbox-1",
"field_required": true,
"field_type": "checkbox",
"field_value": "",
"id": 1112,
"positions" : [
{
"x": 12.6,
"y": 28.6,
"page": "2"
}
]
},
{
"field_name": "signature-0",
"field_required": true,
"field_type": "signature",
"field_value": "",
"id": 1113,
"positions" : [
{
"x": 40.0,
"y": 40.0,
"page": "1"
}
]
},
{
"id":246852,
"field_name": "Date Stamp",
"field_required": true,
"field_type": "date",
"field_value": "",
"id": 1114,
"positions" : [
{
"x":40.0,
"y":40.0,
"page":"1"
}
]
},
{
"id":246851,
"field_name":"Initials",
"field_type":"initials",
"field_required":true,
"field_placeholder":null,
"field_value":"",
"positions":[
{
"page":1,
"x":48.1314,
"y":27.0341
}
]
},
{
"id":246854,
"field_name":"option 1-option 2-5",
"field_type":"dropdown",
"field_required":true,
"field_placeholder":null,
"field_value":"",
"positions":[
{
"page":1,
"x":55.3794,
"y":39.2388
}
]
},
{
"id":246855,
"field_name":"qrcode",
"field_type":"qrcode",
"field_required":false,
"field_placeholder":null,
"field_value":"",
"positions":[
{
"page":1,
"x":43.9411,
"y":50.3937
}
]
},
{
"id":246856,
"field_name":"text to be rendered",
"field_type":"embossed-text",
"field_required":false,
"field_placeholder":null,
"field_value":"",
"positions":[
{
"page":1,
"x":64.2129,
"y":54.3745
}
]
}
]
},
{
"name": "Tom Jones",
"email_address": "tom@example.com",
"last_viewed": null,
"response_ip": null,
"response_os": null,
"response_browser": null,
"response_browser_version": null,
"passport_check": null,
"driving_licence_check": null,
"utility_bill_check": null,
"verification_check": false,
"signed_at": null,
"verified": false,
"document_id": "Ry0KwggOwqNonK4yCm4Xly22w4YvgQ",
"id": "wK3WMtWPR241mnqg",
"status": "Pending",
"current": false,
"synchronous_current": false,
"registered": false,
"aml_document": null,
"placeholder": false
}
],
"labels": [
],
"multiple_documents": [
],
"id": "Ry0KwggO22w4YvgQ",
"synchronous": true,
"date": "2016-05-16T11:40:55+01:00",
"is_master": true,
"parent": null,
"href": "https://app.e-sign.co.uk/api/documents/Ry0KwggOwqNonK4yCm4Xly22w4YvgQ",
"signed_file": {
"url":"https://esign.s3-eu-west-1.amazonaws.com/uploads/document/file/000/011/880/example-document.pdf"
},
"original_file": {
"id": "u6brUspqX-fCNYqBxFQ",
"url": "https://esign-production.s3-eu-west-1.amazonaws.com/uploads/../pdf-sample.pdf",
"filename": "pdf-sample.pdf",
"processing": null
},
"images":[
{
"url":"https://esign-production.s3-eu-west-1.amazonaws.com/uploads/document_image/image1.png"
},
{
"url":"https://esign-production.s3-eu-west-1.amazonaws.com/uploads/document_image/image2.png"
}
],
"author": {
"current": true,
"shared": true,
"name": "E-Sign Support",
"email": "info@e-sign.co.uk"
},
"signer_id": null,
"additional_info": null
}
Description
Creates one or more documents from an original file with the requested signers. note: All field positions are in percentage units from the [top,left] corner.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
documents | Array | True | Array of documents to be created |
title | String | True | Document Title |
desc | String | False | An optional document description |
file | Object | True | File Object |
file [uuid] |
String | True | Original File UUID |
signers | Array[Object] | True | An array of Document Signers who will each receive a notification. |
signers [name] |
String | True | Full name of the Signer |
signers [email] |
String | True | Email address of the signer |
signers [phone] |
String | False | Signer’s Phone number when using PIN code protection (requires SMS credits) |
signers [country_code] |
String | False | Signer’s country calling code (eg +44) when using PIN code protection (requires SMS credits) |
signers [additional_signer_fields] |
Array[Object] | False | An array of fields the signer is required to supply the corresponding information for when signing. The values entered for these fields during signing are rendered onto the document in the place of the supplied positions. |
signers [additional_signer_fields] [field_type] |
String | True | (text, checkbox, signature, initials, date, checkbox, dropdown, qrcode, embossed-text) see below for corrosponding field-name example |
signers [additional_signer_fields] [field_name] |
String | True | (add text-[n], checkbox-[n], signature-[n], Initials, Date stamp, checkbox-[n], option 1-option 2-etc, qrcode, “your render text”, replace [n] for a digit to make the field name unique where shown. |
signers [additional_signer_fields] [field_required] |
Boolean | True | (true - false) if the field value is required for the field during signing |
signers [additional_signer_fields] [positions] |
Array[Object] | True | An array of field positions relative to the document. The supplied field value during signing will be rendered on the document at these positions. |
signers [additional_signer_fields] [positions] [x] |
Integer | True | x-axis coordinate position from the left edge of the document (unit: %) |
signers [additional_signer_fields] [positions] [y] |
Integer | True | y-axis coordinate position from the top edge of the document (unit: %) |
signers [additional_signer_fields] [positions] [page] |
Integer | True | The page number of the document. |
signers [additional_signer_fields] [positions] [email] |
String | True | Signer’s email. |
additional_info | String | False | Additional information sent to the signer regarding the document. |
append_signatures | Boolean | True | Append the signature sheet to the bottom of the document. By default this is 'true’ and the signature sheet is created as the last page of the document. Set to false to prepend the signature sheet to the first page of the document |
attachment_files | Array[String] | False | An array of Attachment File UUID to be attached to the document. |
stop_api_email | Boolean | False | If true, this will mean that E-Sign won’t send it’s own emails. This is useful if you want to manage all email sending yourself. |
synchronous | Boolean | False | Use the new synchronous signing feature. |
Placeholders | Array | False | All required signature fields need repeating within this Array |
placeholders[x] | Float | True | Position from X-axis (%) |
placeholders[y] | Float | True | Position from Y-axis (%) |
placeholders [page] |
Integer | True | Document page of signature |
placeholders [email] |
String | True | Email of Signer who’s signature will be placed |
Show A Document
GET /documents/:id[?s=(signers_id)&images=true&pin=(sms_pin_code)]
{
"id": "EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
"images": true, (optional)
"signer": "tRdbl1vDnY4upjc", (optional)
"pin": "1234" (optional)
}
The above request returns JSON structured like this
{
"title":"Example document title",
"description":"This is an optional description",
"status":"Pending",
"id":"EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
"date":"2015-01-21T19:00:21+00:00",
"href":"http://esign.dev/api/documents/
EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
"signed_file":{
"url":null
},
"original_file":{
"id":"8pkJ-pHg_bW1vksyVeDSibyu9GzA-Q",
"url":"https://esign.s3-eu-west-1.amazonaws.com/
uploads/original_file/Estimate__1_.pdf?
AWSAccessKeyId=AKIAIJMAQ&Signature=nB%2BDlD7t
&Expires=1421867422",
"filename":"Estimate_94_Dragons_Design_Ltd__1_.pdf",
"processing":null
},
"attachment_file":{
"id":"ct_XnYDJE0Irr7OB2-74cW8jM8Nv2g",
"url":"https://esign.s3-eu-west-1.amazonaws.com/
uploads/attachment_file/file/000/000/038/
Invoice45.pdf?AWSAccessKeyId=AKIAIJH7DQ2
&Signature=UPMl8WEoBWznI%3D&Expires=1421822",
"filename":null,
"processing":null
},
"images":[
{
"url":"https://esign-production.s3-eu-west-1.amazonaws.com/uploads/document_image/image1.png"
},
{
"url":"https://esign-production.s3-eu-west-1.amazonaws.com/uploads/document_image/image2.png"
}
],
"author":{
"current":true,
"name":"Test User",
"email":"test@test.com"
},
"signer_id":null,
"additional_info":"More information for all to read",
"signers":[
{
"id":"mWK16JaOVl6LVpVrOcNtDYmPPUubYQ",
"name":"tom jones",
"email_address":"tom@example.com",
"last_viewed":null,
"response_ip":null,
"response_os":null,
"response_browser":null,
"response_browser_version":null,
"passport_check":null,
"driving_licence_check":null,
"utility_bill_check":null,
"signed_at":null,
"status":"Pending",
"current":false,
"registered":false
},{
"id":"9ai6uGMwtKJg7z3FuvdjY-WZf39-LA",
"name":"John Doe",
"email_address":"john@doe.com",
"last_viewed":null,
"response_ip":null,
"response_os":null,
"response_browser":null,
"response_browser_version":null,
"passport_check":null,
"driving_licence_check":null,
"utility_bill_check":null,
"signed_at":null,
"status":"Pending",
"current":true,
"custom_signature":{
"creation_method":"drawn",
"text":null,
"image":"https://esign-development.s3-eu-west-1.amazonaws.com/custom_sig.jpg"
},
"registered":false
}
],
"labels":[]
}
If the document is not found, you may receive a response like this:
{
"error": true,
"errors": [
"Entity/Record not found"
]
}
If the document requires a pin code (status code 423 :locked) :
{
"error": true,
"errors": [
"Document requires PIN code"
]
}
Description
Request and receive a document object.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | Document UUID |
images | Boolean | False | An optional parameter that returns the url of png screenshots of each page from the document, used for displaying the document. |
signer | String | False | Signer’s ID |
pin | String | False | Signer’s pin code when the sender requires pin verification. |
Send Reminder
POST /documents/:id/reminder
{
"message": "Please sign me!",
"recipients": [
"john@smith.com",
"joe@bloggs.com"
]
}
If successful, you may receive a response like this:
{
"success": true
}
Description
Send a reminder via email for a document.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | Document UUID |
message | String | True | Message to send with reminder. For no message just pass an empty string. |
recipients | Array[String] | True | An array of email addresses to remind. |
View Document Activity
GET /documents/:id/activity
[
{
"type": "create",
"datetime": "2015-01-24T12:35:18+00:00",
"action": "Created",
"concern": {
"name": "John Smith",
"id": "john@smith.com"
},
"resource": {
"instance": "Document",
"name": "Example document title",
"id": "ptPT4sm3uH_9TDDZCm4HyvjP33g2_g"
}
}
]
Description
View the document activity (also known as the 'audit trail’) of a document.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | Document UUID |
Archive A Document
PUT /documents
{
"archive": "true",
"ids": [
"uqnKs94ZPt80_8hK_6Q2_pWtAyzhAA",
"asdfdafasdfADSad_adf213213_FDS"
]
}
If successful, the above request returns JSON structured like this:
{
"success":true
}
Description
Archive a document.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ids | Array[String] | True | An array of Document UUIDs |
archive | Boolean | True | Should always be true to archive. |
Labels
Used to label documents. (Also known on the main E-Sign front-end as 'Folders’)
List All Labels
GET /labels
[
{
"name": "NDAs"
},
{
"name": "Misc"
}
]
Description
Gives an array of all the available labels for the current account.
Create a Label
POST /labels
{
"label": "NDAs"
}
If successful, the above request returns JSON structured like this:
{
"success": true
}
Description
Create a new label
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
label | String | True | Label name |
Delete a Label
DELETE /labels
{
"name": "Your Label Name"
}
If successful, the above request returns JSON structured like this:
{
"success": true
}
Description
Deletes a label
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
label | String | True | Label name |
Original File
An original file. A file is first uploaded to our system which is then used as a template to create documents from. This allows multiple documents to be created from one file. The Original File will be standardised to PDF A4 size on upload, which is 595x842 PDF points. This is important as rendering measurements are calculated based on this size.
Listing Original Files
GET /original_files
The above request returns JSON structured like this:
{
"total": 1,
"entries": [
{
"id": "id",
"date": "2015-01-21T14:10:36+00:00",
"processing": true,
"filename": "pdf-sample.pdf",
"file_size": "1337",
"url": ".../pdf-sample.pdf",
"href": "http://app.e-sign.co.uk/api/v1/original_files/id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
]
}
Description
Returns the full details of all attachment file entries.
Retrieving an OriginalFile
GET /original_files/:id
The above request returns JSON structured like this:
{
"id": "id",
"date": "2015-01-21T14:10:36+00:00",
"processing": true,
"filename": "pdf-sample.pdf",
"file_size": "1337",
"url": "../pdf-sample.pdf",
"href": "../id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
Description
Retrieves an information about a specific attachment file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | Original File UUID |
Creating an OriginalFile
POST /original_files
{
"base64_title": "a test title",
"base64_doc": "XJ0eHJlZgoyMTYKJSVFT0YK....",
"base64_ext": ".pdf"
}
The above request returns JSON structured like this:
{
"success": true,
"src": "../test_file.pdf",
"file": {
"id": "id",
"date": "2015-01-21T14:54:43+00:00",
"processing": true,
"filename": "test_file.pdf",
"file_size": 1337,
"url": "../test_file.pdf",
"href": "../id",
"author": {
"name": "Joe Bloggs",
"email": "joe@bloggs.com"
}
}
}
Description
Add a new original file. This can either be a document file (e.g. PDF/DOCX) or a HTML template.
Parameters (If uploading a file)
Parameter | Type | Required | Description |
---|---|---|---|
base64_title | String | True | Title of the file. e.g. 'E-Sign Documentation’, in plain-text. |
base64_doc | String | True | The raw file, encoded as Base64. |
base64_ext | String | True | The extension of the file, e.g. “pdf”, in plain-text |
Parameters (If using a HTML template)
Parameter | Type | Required | Description |
---|---|---|---|
template_title | String | True | Title of the file. e.g. “E-Sign Documentation”, in plain-text. |
tempate_html | String | True | HTML code of the document. Since you’ll be sending this through JSON, you will want to escape this properly. |
Deleting an OriginalFile
Description
Delete an original file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
id | String | True | UUID of the original file. Multiple IDs can be specified, delimited using a comma (,) |
Archive an OriginalFile
PUT /original_files/:id
{
"ids": [1337, 1338],
"archive": true
}
The above request returns JSON structured like this:
{
"success":true
}
Description
Archive an original file.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
ids | Array[String] | True | An array of Original File UUIDs |
archive | Boolean | True | Should always be true to archive. |
Field Templates
Field templates let you save the configuration of document fields and positions and easily apply then to new documents that use the same original file.
Listing Field Templates
GET /field_templates
{
"entries": [
{
"id": 10,
"name": "Example",
"no_of_signers": 2,
"type_of_signature": "co-sign",
"created_at": "2017-03-16T00:46:45+00:00"
}
]
}
Description
Lists all Field Templates for a given authorised user.
Parameters
Parameter | Type | Required | Description |
---|
Creating Field Templates
POST /field_templates
{
"name": "Example",
"no_of_signers": 2,
"type_of_signature": "co-sign",
"original_file_ids": [:original_file_ids],
"saved_fields_attributes": [
{
"file": :original_file_id,
"field_name": "Something",
"field_type": "text",
"signer_idx": 0,
"field_required": false,
"additional_field_positions_attributes": [
{
"x": 5.6,
"y": 10,
"page": 5
}
]
}
],
"saved_field_file_signers_attributes":[
{
"signer_idx":0,
"email":"test@test.com",
"name":"tester"
}
]
}
Response:
{
"id": 10,
"name": "Example",
"no_of_signers": 2,
"type_of_signature": "co-sign",
"created_at": "2017-03-16T00:46:45+00:00"
}
Description
Creates a Field Template for the authorised user with multiple Saved Fields.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | String | True | Name of the Field Template |
no_of_signers | Integer | True | Number of signers used for the template |
type_of_signature | String | True | The chosen method of signing (co-sign, myself, others) |
original_file_ids | Array | True | Array of Original File IDs of the files used in the template |
saved_fields_attributes | Array[Object] | True | An array of fields to save |
saved_fields_attributes [field_name] |
String | True | The field name |
saved_fields_attributes [field_type] |
String | True | The field type (text, date, checkbox, signature) |
saved_fields_attributes [field_required] |
Boolean | True | If the fields value is required to be sent by the signer |
saved_fields_attributes [signer_idx] |
Integer | True | The array index of the signer the fields belong to. |
saved_fields_attributes [additional_field_positions_attributes] |
Array[Object] | True | An array of positions the field’s value will be rendered on the document at. |
additional_field_positions_attributes [x] |
Float | True | X-coord of the field |
additional_field_positions_attributes [y] |
Float | True | Y-coord of the field |
additional_field_positions_attributes [page] |
Integer | True | Page of the document the field’s value will be rendered |
Retrieving a Field Template
POST /field_templates/:id
{
"signers": [
{
"name": "John Doe",
"email": "john@doe.co.uk"
},
{
"name": "Foo Bar",
"email": "foo@bar.co.uk"
}
]
}
Response:
{
"documents": [
{
"additional_info": null,
"append_signatures": false,
"attachment_files": [
],
"desc": "",
"file": {
"author": {
"email": "john@doe.co.uk",
"name": "John Doe"
},
"date": "2016-08-02T13:51:02+01:00",
"file_size": "17155",
"filename": "MobilePinQuote.pdf",
"href": "http://esign.dev/api/original_files/VFeCp70537ZlkjQZjdQmFLyxyYK8mw",
"id": "VFeCp70537ZlkjQZjdQmFLyxyYK8mw",
"processing": null,
"thumbnail": "https://esign-development.s3-eu-west-1.amazonaws.com/uploads/document_image/000/500/830/thumb_VFeCp70537ZlkjQZjdQmFLyxyYK8mw_1.png?X-Amz-Expires=600&X-Amz-Date=20170404T125012Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJLGLLV6CP7FXUFRA/20170404/eu-west-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=c8f0e1ec940b38e3d4f349e546e27adef6bc5f6a9e9fb5d9183f1dae9d1e0203",
"url": "https://esign-development.s3-eu-west-1.amazonaws.com/uploads/original_file/file/000/043/665/MobilePinQuote.pdf?X-Amz-Expires=600&X-Amz-Date=20170404T125012Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJLGLLV6CP7FXUFRA/20170404/eu-west-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=de863307f474825891e9904d1a9aa3e2a39299c624de635ced269f470ae9435f"
},
"placeholders": [
{
"email": "john@doe.co.uk",
"field_required": true,
"name": "John Doe",
"page": 5,
"placeholder": true,
"x": 5.6,
"y": 10
},
{
"email": "foo@bar.co.uk",
"field_required": true,
"name": "Foo Bar",
"page": 5,
"placeholder": true,
"x": 5.6,
"y": 10
}
],
"signers": [
{
"additional_signer_fields": [
{
"field_name": "Something new once again",
"field_required": false,
"field_type": "text",
"positions": [
{
"email": "john@doe.co.uk",
"name": "John Doe",
"page": "5",
"x": 5.6,
"y": 10
}
]
},
{
"field_name": "signature0",
"field_required": true,
"field_type": "signature",
"positions": [
{
"email": "john@doe.co.uk",
"name": "John Doe",
"page": "5",
"x": 5.6,
"y": 10
}
]
}
],
"email": "john@doe.co.uk",
"name": "John Doe"
},
{
"additional_signer_fields": [
{
"field_name": "signature1",
"field_required": true,
"field_type": "signature",
"positions": [
{
"email": "foo@bar.co.uk",
"name": "Foo Bar",
"page": "5",
"x": 5.6,
"y": 10
}
]
}
],
"email": "foo@bar.co.uk",
"name": "Foo Bar"
}
],
"synchronous": false,
"title": "MobilePinQuote",
"useExisitingCertificate": false,
"verify_signers": false
}
]
}
Description
Retrieves a Field Template JSON that’s ready to use to create a document.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
:id | Integer | True | Field Template id |
:signers | Array | True | An Array of signers required for the template |
:signers[:name] | String | True | Signers name |
:signers[:email] | String | True | Signers email |
Deleting a File Template
DELETE /field_templates/:id
{
"success": true
}
Description
Deletes a Field Template.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
:id | Integer | True | The Filed Template ID |
User
An account user. Can be either the administrator or a standard user of the account.
Retrieve a User
GET /users
{
"name":"Admin name",
"email":"admin@testaccount.com",
"admin":true,
"avatar":null
}
Description
Retrieves the admin user’s account details. An auth token can be used to indentify the user, if one isn’t supplied the admin user is returned. Individual auth tokens are shown with each user in the Account - retrieve an account call.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
user_token | String | False | User token to identify the user (Default to Admin) |
Update a User
POST /users/account
{
"name": "Admin name",
"email": "admin@test.com",
"currency": "gbp",
"plan_id": 58,
"signer_id": "",
"password": "test123",
"password_confirmation": "test123",
"master_id": 1,
"profile": {
"company_name": "test company",
"job_title": "web developer",
"contact_number": "00000000000",
"address": "1 test street",
"dob": "14/05/1980"
}
}
When successful, the above request returns JSON structured like this:
{
"success":true,
"user":{
"email":"admin@test.com",
"auth_token":""
}
}
If any errors occur, the above request returns JSON structured like this:
{
"errors":[
"Admin email has already been taken",
"Admin is invalid"
]
}
Description
Updates an account users details
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
name | String | True | Account name |
String | True | Admin user email (unique) | |
password | String | True | Admin user’s password. |
password_confirmation | String | True | confirmation of the Admin user’s password |
currency | String | True | The currency used for billing (gbp/usd/eur) |
plan_id | Integer | True | The plan the account will be associated with |
master_account_id | Integer | True | The master account ID this account belongs to (defaults to e-Sign) |
profile | Object | False | A profile object. |
profile [job_title] |
String | False | Name of the company (Also used as account name) |
profile [contact_number] |
String | False | Contact number of the Admin user |
profile [address] |
String | False | Address of the Admin user |
profile [dob] |
String | False | Date of bith of the Admin User |
Signatures
Custom signatures are a user’s custom created signature that is rendered on a document when signing.
Retrieving signature
GET /users/signatures
{
"creation_method": "text",
"text": "John Doe",
"image": "http://www.example.com/signature/signature.png"
}
Description
Gets information about the user’s signature.
Creating a signature
POST /users/signatures
{
"text": "John Doe",
"base64": "XJ0eHJlZgoyMTYKJSVFT0YK....",
"creation_method": "drawn",
"email_address": "foo@bar.co.uk",
"signer": "O3r0TqguFqpjcPHMMqEIvj_aFb2jTQ"
}
When successful, the above request returns JSON structured like this:
{
"creation_method": "text",
"text": "John Doe",
"image": "http://www.example.com/signature/signature.png"
}
If any errors occur, the above request returns JSON structured like this:
{
"errors":[
"No base64 or text parameter provided"
]
}
Description
Replaces the current user’s signature for use when rendering documents.
Parameters
Only 'text’ or 'base64’ should be passed with the creation_method.
Parameter | Type | Required | Description |
---|---|---|---|
auth_token | String | No | The auth token of the user (must be associated with email_address) |
signer | String | No | The document signer id associated with the email address |
email_address | String | Yes | The signature creator’s email address |
creation_method | String | Yes | Either text , upload or drawn . Doesn’t affect creation process |
base64 | String | If no text parameter provided |
Base64 of the signature PNG image |
text | String | If no base64 parameter provided |
Text (e.g. User’s name) to use for default signature template. |
Deleting signature
DELETE /users/signatures
{
"success": true
}
Description
Deletes the user’s signature
Webhooks
On request we can set up the following webhooks to notify your script with a POST request and payload when an action happens within our system. Please note there is currently no user interface to add Webhooks, contact us to set these up.
Document Signed - Hook
POST [user URI]
{
"event_name": "document_signed",
"document_uuid": "bghkOzbEmJhWERwj7A2N90x7qsPRkA",
"document_status": "Signed",
"signer": {
"name": "test name",
"email_address": "test@e-sign.co.uk",
"signed_at": "Sat, 22 Jun 2019 13:16:30 BST +01:00",
"uuid": "FttRYEoIIpXjsXhWERwj7A",
"declined_at": "Sat, 22 Jun 2019 13:16:30 BST +01:00",
"declined_reason": "Reason for declining",
"required_additional_fields": [
{
"field_value": "1",
"field_name": "signature0",
"id": 23106,
"field_type": "signature"
},
{
"field_value": "TN",
"field_name": "Initials",
"id": 23190,
"field_type": "Initials"
}
],
"response_os": "Mac",
"response_ip": "10.100.10.10",
"response_browser_version": "43.0.0",
"response_browser": "Chrome"
}
}
Description
Sends a POST notification to a client endpoint when a signee signs a document.
Return values
Parameter | Type | Description |
---|---|---|
signer | Object | Current signer object |
document_status | String | Overall document status based on if all signees have signed [Pending / Signed] |
event_name | String | Webhook event name |
document_uuid | String | UUID of the document signed |
Creating a webhook
POST /webhooks
{
"target_url": "https://www.example.com/hook12345",
"event": "document_signed"
}
When successful, the above request returns JSON structured like this:
{
"success": "true",
"id": "22"
}
If any errors occur, the above request returns an error:
{
"error": true,
"errors": ["Target url is invalid"]
}
Description
Creates a new webhook.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
target_url | String | Yes | URL webhook will send a POST request too (must be https) |
event | String | Yes | Webhook event [document_signed] |
Deleting a webhook
POST /webhooks/delete
{
"target_url": "https://www.example.com/hook12345"
}
When successful, the above request returns JSON structured like this:
{
"success": "true"
}
If any errors occur, the above request returns an error:
{
"error": true,
"errors": ["Please check the Webhook target_url is correct"]
}
Description
Deletes a webhook.
Parameters
Parameter | Type | Required | Description |
---|---|---|---|
target_url | String | Yes | URL of the webhook you want to delete |