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.

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
auth_email account user email (optional)

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.
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","id":"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 Information

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",
  "current":false,
  "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

Update a Signer

PUT /signers/:id
{
  "id": "9ai6uGMwtKg7z3FuvdjY-WZf39-LA",
  "agreed": true,
  "required_fields": [
    {
      "id": 7,
      "slug": "passport",
      "label": "Passport",
      "field_type": "checkbox"
    },
    {
      "id": 8,
      "slug": "driving_licence",
      "label": "Driving Licence",
      "field_type": "checkbox"
    },
    {
      "id": 9,
      "slug": "utility_bill",
      "label": "Utility Bill",
      "field_type": "checkbox"
    }
   ],
   "system": {
     "os": "Mac",
     "browser": "Chrome",
     "browser_version": 39
   },
   "required_additional_fields": [
      {
        "field_name": "Favourite Food",
        "field_value": "Pancakes"
      }
   ],
   "passport_check": true,
   "driving_licence_check": true,
   "utility_bill_check": true
}

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_fields Array[Object] True the answers to the required fields requested when the document was created, if no fields were requested a blank array should be supplied eg [].
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”

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 inbox documents to retrieve.
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
[
  {
    "title": "Example document title",
    "desc": "This is an optional description",
    "additional_info": "More information",
    "file": "8pkJ-pHg_bW1vksyVeDSibyu9GzA-Q",
    "append_signatures": false,
    "signers": [
      {
        "name": "Tom Jones",
        "email": "tom@example.com",
        "additional_signer_fields": [
          {
            "field_name": "test field",
            "field_required": true,
            "field_type": "text",
            "positions" : [
              {
                "x": 438,
                "y": 377,
                "page": "1"
              }
            ]
          },
          {
            "field_name": "checkbox-1",
            "field_required": true,
            "field_type": "checkbox",
            "positions" : [
              {
                "x": 331,
                "y": 433,
                "page": "1"
              }
            ]
          },
          {
            "field_name": "signature0",
            "field_required": true,
            "field_type": "signature",
            "positions" : [
              {
                "x": 507,
                "y": 241,
                "page": "2"
              }
            ]
          },
          {
            "field_name": "Date Stamp",
            "field_required": true,
            "field_type": "date",
            "positions" : [
              {
                "x": 438,
                "y": 377,
                "page": "3"
              }
            ]
          }
        ]
       },
       {
         "name": "John Doe",
         "email": "john@example.com"
       }
     ],
     "attachment_files": [
       "ct_XnYDJE0Irr7OB2-74cW8jM8Nv2g"
     ],
     "stop_api_email": true,
     "synchronous": true
  }  
]

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": [
        {
          "field_name": "test field",
          "field_required": true,
          "field_type": "text",
          "field_value": "",
          "id": 1111,
          "positions" : [
            {
              "x": 438,
              "y": 377,
              "page": "1"
            }
          ]
        },
        {
          "field_name": "checkbox-1",
          "field_required": true,
          "field_type": "checkbox",
          "field_value": "",
          "id": 1112,
          "positions" : [
            {
              "x": 331,
              "y": 433,
              "page": "1"
            }
          ]
        },
        {
          "field_name": "signature0",
          "field_required": true,
          "field_type": "signature",
          "field_value": "",
          "id": 1113,
          "positions" : [
            {
              "x": 507,
              "y": 241,
              "page": "2"
            }
          ]
        },
        {
          "field_name": "Date Stamp",
          "field_required": true,
          "field_type": "date",
          "field_value": "",
          "id": 1114,
          "positions" : [
            {
              "x": 438,
              "y": 377,
              "page": "3"
            }
          ]
        }
      ]
    },
    {
      "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": null
  },
  "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
  },
  "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.

Parameters

Parameter Type Required Description
title String True Document Title
desc String False An optional document description
file 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
[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
signers
[additional_signer_fields]
[field_name]
String True The unique name of the field
signers
[additional_signer_fields]
[field_required]
Boolean True (true
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
signers
[additional_signer_fields]
[positions]
[y]
Integer True y-axis coordinate position from the top edge of the document
signers
[additional_signer_fields]
[positions]
[page]
Integer True The page number of the document.
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 'false’ and the signature sheet is created as the first page of the document. If set to true to append the signature sheet to the bottom 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.

Show A Document

GET /documents/:id
{
  "id": "EPFbIXZXF0c2tRdbl1vDnY4upjcd7A",
  "images": false
}

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
  },
  "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":false,
      "registered":false
    }
  ],
  "labels":[]
}

If the document is not found, you may receive a response like this:

{
  "error": true,
  "errors": [
    "Entity/Record not found"
  ]
}

Description

Request and receive a document object

Parameters

Parameter Type Required Description
id String True Document UUID
images Boolean False An optional boolean parameter that appends the image URLs of each processed page/slide from the document to the JSON response.

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. This is created and then used for new documents afterwards.

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 Information

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

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

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

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

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

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