NAV

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

  1. To start using this API you will require an Authentication token. Please request one from info@e-sign.co.uk
  2. You can interact with our staging server at https://xyz.e-sign.co.uk/api/{version}
  3. 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.

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.

Connection example

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.

Original File Diagram

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