{ "swagger": "2.0", "info": { "description": "This document describes how to send a document for signature to eSignTools.\nBased on REST principles, our Web API return data in JSON .\n\nSee https://github.com/legal-tools/est-java-api for an example of a Java implementation.\n\nA document which will be signed is also called \"agreement\".\n\nThe classic workflow is :\n- login : send the API credentials and get a token for the next API calls.\n- 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).\n\nThe document is now sent for signature to the recipients.\n\neSignTools will call the callback each time an event occurs.\n\nExample, if the callback is set to https://mysite.com/event :\n- https://mysite.com/event?id=1234&eventType=ESIGNED will be called when the document 1234 is signed by all recipients\n- https://mysite.com/event?id=1234&eventType=REJECTED will be called when the document 1234 has been rejected by a recipient\n- 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.\n\n## About signature fields\nThere 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.\n### Method 1 : Upload a PDF already containing signature fields :\n These fields shall have a name like SignatorySignature_X_Y, where X is the recipent position (set in CreateRecipientDTO) and Y the fields number.\n *Examples :*\n - A document with a single field for one recipient :\n - SignatorySignature_1_1\n - A document with 2 fields for one recipient :\n - SignatorySignature_1_1\n - SignatorySignature_1_2\n - A document for 2 recipients each with 2 fields :\n - SignatorySignature_1_1\n - SignatorySignature_1_2\n - SignatorySignature_2_1\n - SignatorySignature_2_2\n\n### Method 2 : Using tags\nYour PDF can have no signature field, but just text tags.\nAdd anywhere in your document a text *#signatureX#* to add a signature field linked to the recipient with position=X.\n\nExample :\n- Each *#signature1#* will be replaced by a signature field for the recipient with position=1.\n- Each *#signature2#* will be replaced by a signature field for the recipient with position=2.\n\nThe signature fields will have a default size.\nYou can customize the size in the API.\n\n### Method 3 : Upload a PDF without signature fields\nIf 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*\n\nA signature field is defined by :\n\n- \"page\" : The number of the page which will contain the field (starting at 1)\n- \"x\" : distance between the top left corner of the field and the left border of the page in points\n- \"y\" : distance between the top left corner of the field and the bottom border of the page in points\n- \"width\" : width of the field in points\n- \"height\" : height of the field in points\n\n## About document types\nInstead of uploading a PDF file, you can upload any file with one of the following extension : .rtf, .doc, .docx, .xls, .xlsx, .odt, .ods\nThe document will be converted by eSignTools into a PDF.\n\n## Embedded signing (v2.1.0)\nCreate a temporary signing session with POST /signing/v1/agreements/{id}/embedded-sessions for a client portal or in-person signing. Use autoSendMailsEnabled as the string \"false\" to disable invitation emails. API routes retain their /v1 prefixes. See https://doc.esign-tools.fr/#embedded-signing-v2-1-0 for the iframe/modal integration guide.\n", "version": "2.1.0", "title": "eSignTools API", "contact": {}, "license": {} }, "host": "secure.esign-tools.fr", "basePath": "/api", "securityDefinitions": { "JWT": { "type": "apiKey", "name": "Authorization", "in": "header" } }, "tags": [ { "name": "Authentication", "description": "" }, { "name": "Agreement Resource", "description": "Basic interactions necessarry to handle the agreement through it's lifetime" } ], "paths": { "/v1/authenticate": { "post": { "tags": [ "Authentication" ], "summary": "Authenticate", "description": "Authenticate with eSignTools API and returns a JWT Token.\nThis token must be sent to every other request in the Authorization bearer header. \n*Example* : \"Authorization: Bearer XXX\" where is the token returned by this method.", "operationId": "authorizeUsingPOST", "consumes": [ "application/json" ], "produces": [ "application/json" ], "parameters": [ { "in": "body", "name": "loginVM", "description": "eSignTools Credentials", "required": true, "schema": { "$ref": "#/definitions/Credentials" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/JWTToken" } }, "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } } } }, "/signing/v1/agreements": { "post": { "tags": [ "Agreement Resource" ], "summary": "Create a new agreement", "description": "Receives a FormData composed of a document and a CreateAgreementDTO object to create an agreement", "operationId": "createAgreementTextUsingPOST", "consumes": [ "multipart/form-data" ], "produces": [ "*/*" ], "parameters": [ { "name": "pdf", "in": "formData", "description": "The source document", "required": true, "type": "binary" }, { "name": "agreement", "in": "formData", "description": "String containing a CreateAgreementDTO in json format", "required": true, "type": "string" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/AgreementDTO" } }, "201": { "description": "Created" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "JWT": [] } ] } }, "/signing/v1/agreements/{agreementId}/send-mails": { "get": { "tags": [ "Agreement Resource" ], "summary": "Re-send the mail to the recipient", "operationId": "sendMailsUsingGET", "produces": [ "*/*" ], "parameters": [ { "name": "agreementId", "in": "path", "description": "ID of the document", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "OK", "schema": { "type": "boolean" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "JWT": [] } ] } }, "/signing/v1/agreements/{id}": { "get": { "tags": [ "Agreement Resource" ], "summary": "Agreements settings", "description": "Get information about the agreement in JSON format.", "operationId": "getAgreementUsingGET", "produces": [ "*/*" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the eSignTools agreement to get the settings.", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/AgreementDTO" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "JWT": [] } ] }, "delete": { "tags": [ "Agreement Resource" ], "summary": "Delete an agreement", "description": "The agreement must not be signed. It will be deleted and the recipient(s) will not be able to sign it.", "operationId": "deleteAgreementUsingDELETE", "produces": [ "*/*" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the eSignTools agreement to delete.", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "OK", "schema": { "type": "string" } }, "204": { "description": "No Content" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "JWT": [] } ] } }, "/signing/v1/agreements/{id}/current-file": { "get": { "tags": [ "Agreement Resource" ], "summary": "Download the document", "description": "The document can be downloaded at any point of the process. (Unsigned, Partially Signed, Signed)", "operationId": "getCurrentFileUsingGET", "produces": [ "*/*", "application/pdf" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the eSignTools document", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "OK", "schema": { "type": "byte" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "JWT": [] } ] } }, "/signing/v1/agreements/{id}/proof": { "get": { "tags": [ "Agreement Resource" ], "summary": "Downloads the proof PDF", "operationId": "getProofUsingGET", "produces": [ "*/*", "application/pdf" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the eSignTools document", "required": true, "type": "integer", "format": "int64" } ], "responses": { "200": { "description": "OK", "schema": { "type": "byte" } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Not Found" } }, "security": [ { "JWT": [] } ] } }, "/signing/v1/agreements/{id}/embedded-sessions": { "post": { "tags": [ "Agreement Resource" ], "summary": "Open an embedded signing session", "operationId": "createEmbeddedSessionUsingPOST", "description": "Call from your server with the EST JWT. Verify host user access to the agreement and recipient. The agreement must be OPEN and the recipient WAITING at its current step. Invalid input returns 400; incompatible state or an expired agreement returns 409. Using expired session access returns 410; unknown session access returns 404.", "consumes": [ "application/json" ], "produces": [ "application/json" ], "security": [ { "JWT": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "type": "integer", "format": "int64", "description": "Agreement ID" }, { "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/CreateEmbeddedSigningSessionDTO" } } ], "responses": { "201": { "description": "Created. Forward the session to the signer browser.", "headers": { "Cache-Control": { "type": "string", "description": "no-store" } }, "schema": { "$ref": "#/definitions/EmbeddedSigningSessionDTO" } }, "400": { "description": "Invalid request, origin or missing operatorReference for IN_PERSON" }, "401": { "description": "Missing or invalid JWT" }, "403": { "description": "Access forbidden" }, "404": { "description": "Agreement or recipient not found" }, "409": { "description": "Agreement not open, expired, or recipient not waiting at the current step" } } } } }, "definitions": { "Credentials": { "type": "object", "required": [ "password", "username" ], "properties": { "password": { "type": "string", "description": "Password of the API user", "allowEmptyValue": false, "minLength": 4, "maxLength": 100 }, "rememberMe": { "type": "boolean" }, "username": { "type": "string", "description": "Username of the API user", "allowEmptyValue": false, "minLength": 1, "maxLength": 50, "pattern": "^[_'.@A-Za-z0-9-]*$" } }, "title": "Credentials" }, "JWTToken": { "type": "object", "properties": { "authorities": { "type": "array", "items": { "type": "string" } }, "id_token": { "type": "string", "description": "JWT Token to pass to next API calls.", "allowEmptyValue": false } }, "title": "JWTToken", "description": "This object is returned during the authentication." }, "CreateAgreementDTO": { "type": "object", "required": [ "name", "recipients" ], "properties": { "autoSendMailsEnabled": { "type": "string", "default": "true", "example": "false", "description": "Set the string \"false\" to disable invitation emails for embedded signing. Defaults to \"true\". Existing confirmation emails and callbacks retain their behavior." }, "callbackUrl": { "type": "string", "example": "https://mysite.com/event", "description": "URL which will be called when an event occurs. See the Introduction to know how callback events works.", "allowEmptyValue": false }, "defaultFieldHeight": { "type": "integer", "format": "int32", "description": "Set the default height of signature fields when using tags.", "allowEmptyValue": false }, "defaultFieldWidth": { "type": "integer", "format": "int32", "description": "Set the default width of signature fields when using tags.", "allowEmptyValue": false }, "name": { "type": "string", "example": "Contract123", "description": "Name of the agreement", "allowEmptyValue": false }, "recipients": { "type": "array", "allowEmptyValue": false, "items": { "$ref": "#/definitions/CreateRecipientDTO" } }, "reminderDelay": { "type": "integer", "format": "int32", "example": "86 400", "description": "Set the delay of reminders in minutes. A reminder is sent when a recipient has not signed the document. If this parameter is not set, no reminder will be sent.", "allowEmptyValue": false }, "textTemplateName": { "type": "string", "example": "default", "description": "Template to use when a mail is sent to the recipient. If this parameter is not set, the default template is used.", "allowEmptyValue": false }, "durationUntilExpirationSeconds": { "type": "integer", "format": "int64", "minimum": 600, "description": "Duration in seconds before the agreement expires. If omitted, the account default is used." } }, "title": "CreateAgreementDTO", "description": "This object is passed in JSON with the PDF during the agreement creation process. It describes the agreement settings." }, "CreateRecipientDTO": { "type": "object", "required": [ "email", "firstname", "lastname" ], "properties": { "canRenew": { "type": "boolean" }, "email": { "type": "string" }, "fields": { "type": "array", "description": "List of the signature fields to add for this recipient. This list is mandatory if the PDF does not contain any signature fields.", "allowEmptyValue": false, "items": { "$ref": "#/definitions/CreateSignatureZoneDTO" } }, "firstname": { "type": "string" }, "lastname": { "type": "string" }, "phone": { "type": "string", "description": "Phone number of the recipient. If this propery is set, a SMS with a code will be sent to the recipient to validate its signature.", "allowEmptyValue": false, "pattern": "^\\+?([0-9]| |-)+$" }, "position": { "type": "integer", "format": "int32", "description": "Position of the concerned Signature Form in the PDF. Example : if the position is 1, every Signature Form with the name SignatorySignature_1_x will be bound to this recipient. This property is optional if you set the signature fields via the API. Default is 1", "allowEmptyValue": false }, "step": { "type": "integer", "format": "int32", "description": "Step of this recipient in the signature workflow. If every recipient has step=1, the document will be sent for signature simultaneously to every recipient. If step=1 for recipient A and step=2 for recipient B, eSignTools will wait A to sign before sending it to B. Default is 1", "allowEmptyValue": false } }, "title": "CreateRecipientDTO" }, "CreateSignatureZoneDTO": { "type": "object", "properties": { "height": { "type": "integer", "format": "int32", "description": "Height of the field in points", "allowEmptyValue": false }, "page": { "type": "integer", "format": "int32", "description": "Number of the page which will contain the field (starts with 1)", "allowEmptyValue": false }, "width": { "type": "integer", "format": "int32", "description": "Width of the field in points", "allowEmptyValue": false }, "x": { "type": "integer", "format": "int32", "description": "Horizontal position of the field, from the left of the page, in points", "allowEmptyValue": false }, "y": { "type": "integer", "format": "int32", "description": "Vertical position of the field, from the bottom of the page, in points", "allowEmptyValue": false } }, "title": "CreateSignatureZoneDTO" }, "AgreementDTO": { "type": "object", "properties": { "currentStep": { "type": "integer", "format": "int32", "description": "Current step of the document. See CreateAgreementDTO::step", "allowEmptyValue": false }, "estClientUrlAccess": { "type": "string" }, "id": { "type": "integer", "format": "int64", "description": "Agreement ID generated by eSignTools", "allowEmptyValue": false }, "name": { "type": "string", "description": "Name of the agreement (ex : \"Contract\")", "allowEmptyValue": false }, "pages": { "type": "integer", "format": "int32", "description": "Number of pages of the document", "allowEmptyValue": false }, "recipients": { "type": "array", "items": { "$ref": "#/definitions/RecipientStatusDTO" } }, "renewedDate": { "type": "string", "format": "date-time" }, "status": { "type": "string", "description": "Current status of the agreement. \n- OPEN : the document has not been signed by all recipients \n- CLOSED : the document is signed by every recipient and is archived\n- ABORTED : the document has been rejected by a recipient\n- DELETED : the document has been deleted with a DELETE API call\n- ABANDONED : the document is expired", "allowEmptyValue": false, "enum": [ "OPEN", "CLOSED", "ABORTED", "DELETED", "ABANDONED" ] } }, "title": "AgreementDTO", "description": "Describes an agreement stored in eSignTools" }, "RecipientStatusDTO": { "type": "object", "properties": { "canRenew": { "type": "boolean" }, "email": { "type": "string" }, "firstname": { "type": "string" }, "id": { "type": "integer", "format": "int64", "description": "ID of the recipient, generated by eSignTools", "allowEmptyValue": false }, "lastname": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING", "SIGNED", "REFUSED" ] }, "step": { "type": "integer", "format": "int32", "description": "See CreateRecipientDTO:step for more details.", "allowEmptyValue": false } }, "title": "RecipientStatusDTO", "description": "Information about the recipient and its status in the signature workflow." }, "CreateEmbeddedSigningSessionDTO": { "title": "CreateEmbeddedSigningSessionDTO", "type": "object", "required": [ "recipientId", "parentOrigin", "mode" ], "properties": { "recipientId": { "type": "integer", "format": "int64", "example": 456, "description": "Recipient ID from AgreementDTO.recipients; must be WAITING at the current signing step." }, "parentOrigin": { "type": "string", "maxLength": 255, "example": "https://app.example.com", "description": "Exact HTTPS origin of the host application, without path or trailing slash. HTTP allowed only for localhost and 127.0.0.1." }, "mode": { "type": "string", "enum": [ "CLIENT_SPACE", "IN_PERSON" ], "description": "Client portal or in-person signing. IN_PERSON requires operatorReference." }, "signatureScalePercent": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 100, "default": 100, "example": 70, "description": "Scale both dimensions of the complete signature block, centered in its field in the final PDF. Session-specific; defaults to 100 when omitted or null. Values other than 100 require BLOCKCHAIN; DOCAPOST returns HTTP 400." }, "operatorReference": { "type": "string", "maxLength": 255, "example": "technician-789", "description": "Required and non-blank for IN_PERSON. Reference of the authenticated professional, not the signer." } } }, "EmbeddedSigningSessionDTO": { "title": "EmbeddedSigningSessionDTO", "type": "object", "properties": { "signingUrl": { "type": "string", "format": "uri", "description": "Confidential temporary signing URL. Use the returned URL, including its deployment-specific language prefix." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Up to 30 minutes from creation, capped at the agreement expiration." }, "agreementId": { "type": "integer", "format": "int64", "example": 123 }, "recipientId": { "type": "integer", "format": "int64", "example": 456 } } } }, "schemes": [ "https" ] }