Integrate eSign’s API eSignature software into your website today for a smoother digital experience for you and your customers.
API connects your business processes.
An Application Programming Interface, or API, is a software intermediary that allows multiple applications to communicate with each other. An API connects your business processes, services, content, and data to channel partners, internal teams, and independent developers in an easy and secure way.
APIs are quickly becoming the de facto standard by which companies exchange data and build consistent cross-channel customer experiences. Make sure your business stays ahead of the curve with eSign’s API technology.
Greater flexibility and convenience.
An API provides customers with an assortment of well-integrated features, providing greater flexibility and convenience that’s ideal when requesting digital signatures.
APIs integrate a number of different application functions into one big software program, making these applications more accessible and user-friendly for you and your customers.
Compliant with all major eSignature laws.
When you choose an API service from eSign, you can be sure that your API is secure and compliant.
Our eSign platform and electronic signatures are compliant with all major eSignature laws and operate an encrypted client library for end-to-end encryption to protect the contents of your documents and your sensitive data.
Easy to use eSign.
We want to make using the API as easy as possible, to help you integrate we’ve created the developer hub for eSign customers.
Here you can find all the essential links to documentation and reference code as well as our latest SDK’s and Tools.
By using an API, you have the ability to integrate greater automation into your processes for a smoother, more efficient digital experience.
With an API, you can effortlessly integrate numerous applications into one, simplified software.
By integrating your applications, you can equip your customers with a user-friendly and joined up website experience.
Remove any barriers between your customers and business with an integrated API and encourage greater traffic through flexible and convenient functionality.
With the eSign platform, you can be sure all your data and communications are secure and compliant.
Using eSign’s API, you can create an integrated process on existing or new applications to innovate your current processes.
Use eSigns iframe functionality to generate envelopes from within your own system.
LEARN MOREThe healthcare industry clearly recognised the need to adopt a digital approach to prescription processing, giving operational advantages, regulatory compliance and improvements to patient safety.
LEARN MOREThere has been significant time and cost savings on the sign-up process for new tenants as there is no longer a requirement for officers or tenants to travel to meet in a location to sign the agreement.
LEARN MOREeSign provides cost-effective solutions to digitally process key legal documents, such as contracts, agreements and policy documents, enhancing customer satisfaction and increasing your brand reputation.
LEARN MOREEfficiently drive your business ahead with streamlined processes, effective transactions, and budget-friendly services.
LEARN MOREeSign provides holistic digital document solutions tailored for the education sector, driving your educational establishment ahead with efficient processes.
LEARN MOREeSign provides comprehensive digital document solutions designed for healthcare organisations, optimising processes, ensuring efficient transactions.
LEARN MOREeSign provides comprehensive digital document solutions designed for insurance firms, propelling your business with optimised processes.
LEARN MOREEnhance document processing speed, competitiveness, ensure higher compliance, and elevate contract review processes through the adoption of a digital document management solution.
LEARN MOREFurnish your Life Sciences company with a digital document platform that enables a seamless agreement process.
LEARN MOREeSign offers complete digital document solutions for logistics, powering your business forward with streamlined processes, efficient transactions, and cost-effective services.
LEARN MORE
An Application Programming Interface, or API, is a software intermediary that allows multiple applications to communicate with each other. An API connects your business processes, services, content, and data to channel partners, internal teams, and independent developers in an easy and secure way.
An API provides customers with an assortment of well-integrated features, providing greater flexibility and convenience that’s ideal when using digital signatures alongside other applications.
The E-Sign API enables developers to seamlessly incorporate E-Sign’s electronic signature features into their own applications. By utilising this API, developers gain the ability to effortlessly create, send, and oversee documents that necessitate electronic signatures. Furthermore, the API facilitates the tracking of document signing progress and provides the means to manage account settings and users.
The E-Sign API offers a fantastic solution for streamlining the management of signed agreements. Developers can effortlessly integrate their systems with the E-Sign API, which provides a dependable and user-friendly method to upload documents, initiate signing requests, send reminders, and gather e-signatures.
Here you will find some of the key definitions of words used throughout our API.
Documents are the files uploaded to E-Sign that form part of an envelope. Once a file has been uploaded it can be used to create templates, be sent as part of an envelope, or be added as an attachment to an envelope.
Envelopes are structures that contain data required for a successful E-Signature transaction. Each envelope contains one or more documents, signers, and meta data such as the envelope author and transaction information. Envelopes have unique ID’s that can be referenced to interact with the envelope.
Signers refer to the primary recipients of envelopes. They are specified during the creation of an envelope, and they are directed to view, agree, and sign envelopes. Each envelope must have one or more signers.
Templates are reusable blueprints that can be used to quickly send out envelopes using common information. Frequently used documents or signer groups can be set up easily.
Webhooks are automated messages sent from apps when something happens. They have a message—or payload—and are sent to a unique URL. Webhooks are almost always faster than polling and require less work on your end.
Use OAuth to securely get access to your users’ data without them sharing their E-Sign password.
OAuth, or open authorization, is a widely adopted authorization framework that allows you to consent to an application interacting with another on your behalf without having to reveal your password. It does this by providing access tokens to third-party services without exposing user credentials.
To use our API, you will require an api key, separate keys may be required to access the sandbox environment. API keys do not expire unless you revoke them. Requests are authenticated using the ‘Authorization: Token API_KEY’ header.
Example:
curl -X GET “https://sandbox.e-sign.co.uk/v3/accounts” -H “accept: application/json” -H “Authorization: Token API_KEY”
E-sign uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with E-signs servers (these are rare).
Code | Explaination |
---|---|
200 – OK | Everything worked as expected. |
201 – Created | The request succeeded, and a new resource was created as a result. |
204 – No Content | The server has successfully fulfilled the request and that there is no additional content to send in the response payload body. |
400 – Bad Access | The request was unacceptable, often due to missing a required parameter. |
401 – Unauthorized | No valid API key provided. |
402 – Request Failed | The parameters were valid but the request failed. |
403 – Forbidden | The API key doesn’t have permissions to perform the request. |
404 – Not Found | The server can not find the requested resource – the endpoint is valid but the resource itself does not exist. |
409 – Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
410 – Gone | This response is sent when the requested content has been permanently deleted from server, with no forwarding address. |
422 – Unprocessible Entity | The request was well-formed but was unable to be followed due to semantic errors. |
429 – Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
500, 502, 503, 504 – Server Errors | Something went wrong on E-sign’s end. These responses are very uncommon. |
This guide leads you through a typical implementation of the E-sign API.
This guide will go through the process of sending an envelope from document upload to envelope submission.
The first step is retrieving the document ID of any documents that will be included in the envelope.
Documents can be uploaded by passing them in base64 format to API, a document ID will be returned in the response.
POST https://sandbox.e-sign.co.uk/v3/uploads/
JSON Body
Example Response
The returned ID will be used in the body of then envelope request.
The next stage is the collection of relevant data for the envelope, for example, the signers name and email and any fields required on the document.
Fields are the essential building blocks that give envelopes their function, E-sign uses different fields for different purposes, fields include request signature, request text and many more.
For this example, we will just be adding one signature field to the document.
Fields are positioned and rendered over the top of the uploaded document by the server once the envelope has been signed and completed. The field positioning is done using percentages so the positioning can remain dynamic.
POST https://sandbox.e-sign.co.uk/v3/envelopes
Once the envelope request has been made the signer will receive an email with the information included in the body of the request, the email will also contain a link to open the signing page.
Documents are required for sending envelopes. Their IDs are specified in the body of the envelope request.
Documents can be uploaded by passing them in base64 format to the API, the documents ID will be returned in the body of the response.
POST https://sandbox.e-sign.co.uk/v3/uploads
JSON Body:
Example response:
This will add the document to the account connected to the API Key.
Envelopes contain documents that are sent to the end user to be signed, envelopes are created and completed all from within the API.
To send an envelope, you must first upload any documents required for sending. The create envelope request will use the ID of these documents.
Request URL
POST “https://sandbox.e-sign.co.uk/v3/envelopes”
Simple body
The primary requirements in the body are the documents with their document fields and signers. Together these form an envelope. There are additional parameters that can be added into an envelope request however they are not required as the API will provide default values for any values not specified.
The ID of each document should be specified in the documents object in the document array, each document that is in the array will be part of the envelope sent to the signer.
The document objects contain the identifying data for the document and the fields that are present on the document. All fields available on the web app are also available on the API.
Document Field example body
A document field can be any of the following:
These are also the identifiers for the field types defined as the “field_type” value.
The field required Boolean value defines if the user will be required to complete the field to continue. It defaults to false.
The field place holder value sets a text description of the field, this again is optional and only used for text fields.
The field amount value specifies the amount when using the payment field.
The field value is the value of the request field.
Field drop down options are used when using the drop-down field.
The document position specifies the location of the field relative to the top left corner of the document, percentages are used so that scalability can be allowed.
To see all the available values in the body of the request view the schema on the api reference, there you will find a brief description for each value.
Signing envelopes is a simple process that involves simply providing the field values for the fields on an envelope. The values are sent in the body of the request alongside an agree or decline value and some meta data for the envelope.
POST /v3/signers/signer_id/documents/document_id
In the request URL the id of the signer and id of the document should be specified, this can be found in the response on a create envelope call.
Once the data has been arranged correctly in this format the signature request can be submitted.
A request should be made for each document in the envelope.
This guide will follow the process required to complete a document inside an Iframe.
This is used when you would like to keep a customer in one environment and not require them to be redirected to e-sign. You can complete an entire process from within your own site.
The first part of this process is creating the envelope using the api. A shortened example of the body of the request is shown below:
Here the envelope should be created as normal but signing emails should be set to true so that an email is not sent to the signer, this is because the signer will be signing using an iframe instead.
The next step is to assign the correct URI to the iframe so that the envelope can be signed.
The URI is constructed as follows:
https://api.e-sign.co.uk/link?e=ENVELOPE_ID&s=SIGNER_ID
When assigned to an iframe this will redirect to app.e-sign.co.uk and show the signing page for the user.
If testing in sandbox use sandbox.e-sign.co.uk instead of api.e-sign.co.uk, this will redirect to xyz.e-sign.co.uk to test your process.
Example:
The URI can be assigned to the iframe src tag and displayed on a webpage.
E-sign can make POST requests to your URLs when events occur on your account.
The events that can be used as triggers:
[ document_signed, envelope_created, envelope_completed ]
The webhook will be triggered on the selected event and the POST request will follow to the selected URL defined in the body of the create webhook request.
Response:
The content of the post request made to the target url will contain data based on the event:
Document signed events:
Envelope created and completed:
Existing webhooks can be retrieved using the GET webhooks route.
Retrieve Webhook: GET /v3/webhooks
Response:
Webhooks can be deleted using their unique ID
Delete webhook: DELETE /v3/webhooks/ID
On successful request the server will respond with a 204 code – No content.
This feature is designed to allow users to add fields to documents within an Iframe utilising the existing E-Sign web app.
Creating your own interface to add fields to documents can be very time consuming but may be required if you wish to create custom workflows in your own environment.
This API call returns a URI that can be assigned to an iframe that will allow you to add fields to documents and send the envelope from within the Iframe.
The body of the request is similar to the body of a create envelope request just without the document field data on each document object.
POST ‘sandbox.e-sign.co.uk/v3/envelopes/redirect’
Example body:
Example response:
The API uses the document ids in the body to retrieve the relevant documents from the database.
The Iframe is an instance of the envelope creation process and has a simple to follow workflow.
The user can add fields then confirm and send their document with the same flow on the webapp.
Once the flow is completed and the envelope has been sent, the child page within the iframe emits a post message from the e-sign url that can be used as indication that the process has been complete.
In the demo on this site the post message is used as an indicator to close the iframe and redirect the user using host listeners in angular.
The click to sign on the demo site work by utilising E-signs templates.
The workflow is quite simple but makes effective use of the template using HTML forms to fill the fields before the envelope has been generated.
The data is collected on the web app before the envelope is generated.
A template request pulls in the template and the relevant fields are displayed. Once the user has filled in the fields and a submit action is triggered the envelope is generated from the template and then completed immediately following its creation using the pre collected data on the web page.
In our click to sign demo we use this same process.
The template has three fields, two request text boxes for Name and Email and a Signature field.
The request text fields have placeholder text ‘Name’ and ‘Email’. When the get template request returns the template, the placeholder text for each field can be used to assign HTML input fields to each request text field.
On the page the document Is then displayed inside an image tag and the HTML input fields can be absolutely positioned based on the position values returned in the template response.
The field position is a percentage relative to the top left corner of the document. This allows the field position to always be correct regardless of the size of the display.
To send any envelope, a signer’s name and email are required, therefore these two fields are included as they will be used for the envelope creation.
Note: in the body of the request dont_send_signing_emails is set to true so that the process is contained to the custom environment.
In the example, once the user has filled in the name and email inputs, the signature field automatically populates using the signers name, this is done to keep the signing process simple as completed document will have an autonomously generated signature anyway.
Once all the field data has been collected, the envelope can be created from the template and signed in sequence allowing the process to be complete instantly.
OAuth is an authentication protocol that allows you to approve one application interacting with another on your behalf without giving away your password.
OAuth doesn’t share password data but instead uses authorization tokens to prove an identity between consumers and service providers.
For example, you can tell E-sign that it’s OK for third-party-site.com to access your account without having to give third-party-site.com your E-sign password. This minimizes risk in a major way: In the event third-party-site.com suffers a breach, your E-sign password remains safe.
Oauth is available to API customers. It can be used to act on the users’ behalf without the user sharing their password, instead the third-party application receives an access token that is used as the Bearer Token to make calls to the E-Sign API on the users’ behalf.
An overview of the steps:
This can be done via the API.
Here is an example of an oauth app’s data once it has been created:
A link to E-signs authorization page can be constructed in the following format:
https://app.e-sign.co.uk/?response_type=code&client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]
Using our application data, the link would be:
https://app.e-sign.co.uk/?response_type=code&client_id=myid123&redirect_uri=http://demo-site.com
This link will redirect to the oauth authorization page prompting the user to log into their e-sign account and allow the application to use their data.
After the user has agreed they will be redirected to the redirect_uri with a code parameter attached e.g., http://demo-site.com?code=72837jzcks3rr
This code is important as it is required for the next step, getting a token for the user requests.
The endpoint to retrieve a user token is https://api.e-sign.co.uk/v3/oauth/token, as a POST request and takes the following body:
For a successful request you should expect to receive the following:
The access token can now be used as the bearer token for any requests for the users’ data