eSignTools API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This document describes how to send a document for signature to eSignTools. Based on REST principles, our Web API return data in JSON .

See an example of a Java implementation.

A document which will be signed is also called "agreement".

The classic workflow is :

• login : send the API credentials and get a token for the next API calls.
  
• createAgreement : upload the PDF and set the agreements settings. These settings are : title, callback url and recipients. The callback URL is called when an event occurs (document signed or rejected).

The document is now sent for signature to the recipients.

eSignTools will call the callback each time an event occurs.

Example, if the callback is set to https://mysite.com/event :

• https://mysite.com/event?id=1234&eventType=ESIGNED will be called when the document 1234 is signed by all recipients
  
• https://mysite.com/event?id=1234&eventType=REJECTED will be called when the document 1234 has been rejected by a recipient
  
• https://mysite.com/event?id=1234&eventType=OUT_FOR_SIGNATURE will be called when the document 1234 has been signed by a recipient but eSignTools is still waiting for the signature of another recipient.

About signature fields

There are currently 3 ways to manage signature fields. You can either put it yourself in the PDF before uploading it to eSignTools, or you can add them dynamically at the upload.

Postman Collection detailing the 3 methods to create an agreement

Method 1 : Upload a PDF already containing signature fields :

These fields shall have a name like SignatorySignature_X_Y, where X is the recipent position (set in CreateRecipientDTO) and Y the fields number.
Examples :

• A document with a single field for one recipient :
  • SignatorySignature_1_1
• A document with 2 fields for one recipient :
  • SignatorySignature_1_1
  • SignatorySignature_1_2
• A document for 2 recipients each with 2 fields :
  • SignatorySignature_1_1
  • SignatorySignature_1_2
  • SignatorySignature_2_1
  • SignatorySignature_2_2

Example Document

Method 2 : Using tags

Your PDF can have no signature field, but just text tags. Add anywhere in your document a text #signatureX# to add a signature field linked to the recipient with position=X.

Example :

• Each #signature1# will be replaced by a signature field for the recipient with position=1.
• Each #signature2# will be replaced by a signature field for the recipient with position=2.

The signature fields will have a default size. You can customize the size in the API.

Example Document

Method 3 : Upload a PDF without signature fields

If your PDF does not contain any signature fields, you must define them in the call to the API. For each recipient, you must have at least one signature field. See CreateSignatureZoneDTO

A signature field is defined by :

• "page" : The number of the page which will contain the field (starting at 1)
• "x" : distance between the top left corner of the field and the left border of the page in points
• "y" : distance between the top left corner of the field and the bottom border of the page in points
• "width" : width of the field in points
• "height" : height of the field in points

Example Document

About document types

Instead of uploading a PDF file, you can upload any file with one of the following extension : .rtf, .doc, .docx, .xls, .xlsx, .odt, .ods The document will be converted by eSignTools into a PDF.

Base URLs:

• Test Environment: https://rec.esign-tools.fr/api
• Production Environment: https://secure.esign-tools.fr/api

Authentication

• API Key (JWT)
  • Parameter Name: Authorization, in: header.

Authentication

Authenticate

POST /v1/authenticate

Authenticate with eSignTools API and returns a JWT Token. This token must be sent to every other request in the Authorization bearer header. Example : "Authorization: Bearer XXX" where XXX is the token returned by this method.

Body parameter

{
  "password": "string",
  "rememberMe": true,
  "username": "string"
}

Parameters

Example responses

200 Response

{
  "authorities": [
    "string"
  ],
  "id_token": "string"
}

Responses

Agreement Resource

Basic interactions necessarry to handle the agreement through it's lifetime

Create a new agreement

POST /signing/v1/agreements

Body is a FormData composed of a document (sent in binary) and a CreateAgreementDTO object (serialized as a JSON) to create an agreement.
For examples, see the Postman collection in the introduction.

Body : composed of two multipart/form-data fields

pdf: binary data
agreement: JSON format data

Parameters

Example responses

200 Response

Responses

Re-send the mail to the recipient

GET /signing/v1/agreements/{agreementId}/send-mails

Parameters

Example responses

200 Response

Responses

Agreements settings

GET /signing/v1/agreements/{id}

Get information about the agreement in JSON format.

Parameters

Example responses

200 Response

Responses

Delete an agreement

DELETE /signing/v1/agreements/{id}

The agreement must not be signed. It will be deleted and the recipient(s) will not be able to sign it.

Parameters

Example responses

200 Response

Responses

Download the document

GET /signing/v1/agreements/{id}/current-file

The document can be downloaded at any point of the process. (Unsigned, Partially Signed, Signed)

Parameters

Example responses

200 Response

Responses

Downloads the proof PDF

GET /signing/v1/agreements/{id}/proof

Parameters

Example responses

200 Response

Responses

Schemas

Credentials

{
  "password": "string",
  "rememberMe": true,
  "username": "string"
}

Credentials

Properties

JWTToken

{
  "authorities": [
    "string"
  ],
  "id_token": "string"
}

JWTToken

Properties

CreateAgreementDTO

{
  "callbackUrl": "https://mysite.com/event",
  "defaultFieldHeight": 0,
  "defaultFieldWidth": 0,
  "name": "Contract123",
  "recipients": [
    {
      "canRenew": true,
      "email": "string",
      "fields": [
        {
          "height": 0,
          "page": 0,
          "width": 0,
          "x": 0,
          "y": 0
        }
      ],
      "firstname": "string",
      "lastname": "string",
      "phone": "string",
      "position": 0,
      "step": 0
    }
  ],
  "reminderDelay": "86 400",
  "textTemplateName": "default"
}

CreateAgreementDTO

Properties

CreateRecipientDTO

{
  "canRenew": true,
  "email": "string",
  "fields": [
    {
      "height": 0,
      "page": 0,
      "width": 0,
      "x": 0,
      "y": 0
    }
  ],
  "firstname": "string",
  "lastname": "string",
  "phone": "string",
  "position": 0,
  "step": 0
}

CreateRecipientDTO

Properties

CreateSignatureZoneDTO

{
  "height": 0,
  "page": 0,
  "width": 0,
  "x": 0,
  "y": 0
}

CreateSignatureZoneDTO

Properties

AgreementDTO

{
  "currentStep": 0,
  "estClientUrlAccess": "string",
  "id": 0,
  "name": "string",
  "pages": 0,
  "recipients": [
    {
      "canRenew": true,
      "email": "string",
      "firstname": "string",
      "id": 0,
      "lastname": "string",
      "status": "WAITING",
      "step": 0
    }
  ],
  "renewedDate": "2019-08-24T14:15:22Z",
  "status": "OPEN"
}

AgreementDTO

Properties

Enumerated Values

RecipientStatusDTO

{
  "canRenew": true,
  "email": "string",
  "firstname": "string",
  "id": 0,
  "lastname": "string",
  "status": "WAITING",
  "step": 0
}

RecipientStatusDTO

Properties

Enumerated Values