EasySign API - Generate signature request link

The following article describes information about the Generate an EasySign signature request link API call.

URL

/api/sign/generate-request

Method

POST

Required URL Parameters

Customer-id (string)

Data Parameters

The following describe required and optional data parameters.

Name	Type	Description
apiVersion	string	The API version. This document specifies apiVersion 2.
apiKey	string	The API key for the provided environment.
participants	array	Describes the participants of the entire signature workflow. For a detailed description, see the Participants section below.
steps	array	Describes the steps of the signature workflow, which participants take part in each step, and which communication entries (SMS, Emails) are sent. For a detailed description, see the Steps section below.
documents	array	Describes the PDF documents to be filled or signed during the entire workflow. For a detailed description, see the Documents section below.

Name	Type	Description
requestId	string	Replaces EasySend’s auto generated requestId. This can be useful for using an ID from some existing organizational system, to make it easier to connect the EasySend signature session with the originating system session, or for making sure requests are idempotent. Subsequent calls using an already used request id will fail.
expiryDate	string	For Example: 2008-09-15T15:53:00.
customData	any	Any custom data provided by the API caller. This data is replied when EasySend is sending data to a callback API upon document submission.
consentPopup	object	Describes information about a consent popup that should be displayed before the form is presented for signature. If omitted, no consent popup is displayed. For a detailed description, see the Consent Dialog Section.
mailingPopup	object	Describes information about a mailing popup that should be displayed before the form is presented for signature. If omitted, no consent popup is displayed. For a detailed description, see the Mailing Dialog Section.
redirectUrl	string	Redirects the browser of the client’s browser will be to the set URL upon completion of the signing.
businessGroup	string	If provided, this will be used for filtering in agent dashboard screen. If not provided, the value will be ‘Signature Tool’.

Participants Section

This part of the request describes the participants of the signature workflow.
It is a JSON array, containing JSON objects. Each object corresponds to a specific participant (person) that takes part in the signature workflow and has the following structure:

Name	Type	Description
id	string	An internal identifier for this participant. This will be referenced by other areas of the API in order to refer to this participant. Please make sure to choose a unique identifier for each participant of a specific session.
name	string	The name of the participant (person). This will be used for embedding in communication messages (SMS/emails).
role	string	An internal name describing the role for this participant. Each role can be assigned with different permissions for editing different fields of the document/s. For a specific role, some fields can either be: Readable/Writable Read Only None/Omitted (no read or write).

Steps Section

This section describes the steps of the signature workflow, which participants take part in each step, and which communication entries (SMS/emails) are sent.
It is a JSON array, containing JSON objects. Each object corresponds to one step of a sequential workflow. Only once a specific step is completed, the next step is started.
Each entry of the array is a JSON object of the following structure:

Name	Type	Description
communication	object	Describes the set of communication messages (SMS/emails) to be sent for different participants of the workflow. For a detailed description, see the Communication Subsection.
id	string, optional	An internal identifier for this step. If omitted, EasySend will auto generate a random identifier.
authProvider	object, optional	Provided if this step requires authentication before showing the document signing experience. Common use cases are: This step requires a password. This step should be authenticated using a token provided as a URL parameter. This step requires a One Time Password (OTP) authentication. An OTP will be sent to the participant’s phone when opening the link. This step requires authentication with credentials validated via a web service. Contact EasySend for more information about your specific use case.

Communications Subsection

This subsection describes the set of communication messages (texts / emails) to be sent for different participants of the workflow. It is a JSON object with the following structure:

Name	Type	Description
start	array	An array of Communication Entry objects, to be sent at the beginning of the step (when sending a link to relevant participants at the beginning of the step. For a detailed description, see the Communication Entry.
finish	array	An array of Communication Entry objects, to be sent at the end of the step (when sending a summary of the current step to relevant participants after participants of a specific step have submitted the documents). For a detailed description, see the Communication Entry.

Communications Entry

All communication entries contain at least these common fields:

Name	Type	Description
participantId	string	The ID of the participant as specified in the Participants Section.
type	string	One of the following preset values: email - For sending an email sms - For sending a text message none - Will not send any message, only generate a link and return it via API.

Type "email"

For type “email” these additional fields need to be provided:

Name	Type	Description
email	string	The target email address. It is also supported to: use a comma separated list of emails in the string value. Reference a model field (entries not containing the “@” sign will be considered as references to model fields).
subject	string	The subject of the email. May include special field. For a detailed description, see the Escape Sequences for Communication Entries.
body	string	The content of the email as an HTML string. This may include special fields. For a detailed description, see the Escape Sequences for Communication Entries.
attachModelJson	boolean, optional	(Only relevant for the “finish” phase) Specifies whether an additional file should be attached to the email. Containing the data fields collected by the tool in a JSON format (in addition to the PDF document). This is used for cases where an integration expects to receive the data via email once the process is submitted.
customModelJsonFileName	string, optional	(Only relevant for the “finish” phase and only if attachModelJson is set to true). Customizes the file name of the attached model file.
encryptPDFwithPassword	string, optional	If provided, PDF will be protected with a password (when you open it, you’ll be prompted to type a password). This field’s content will be used as a password for the encrypted PDF.

Type "sms"

For type “sms” these additional fields need to be provided:

Name	Type	Description
phone	string	The phone number to deliver the SMS/text message to. This must include an international prefix (must start with the plus sign ‘+’). The content of the text message may include special fields. For a detailed description, see the Escape Sequences for Communication Entries.

Escape Sequences

Escape Sequences for Communication Entries:

Name	Type	Description
{{name}}	string	The name of the participant as described in the Participants Section.
{{link}}	string	The link used to start the signature process. (Only available in “start” of step).

Documents Section

This section describes the PDF documents to be filled or signed during the entire workflow.
It is a JSON array containing JSON objects, each object corresponds to a single document, and has the following structure:

Name	Type	Description
title	string	The title of the document
file	object	Describes the content of the PDF document to be signed. For additional description, see the File Descriptor Syntax section.
fieldsDetectionType	string	One of the following preset values: autoDetect whiteOnWhiteDetect selfAssignedDetect
id	string, optional	A unique string representing the document’s id. If omitted, EasySend will auto generate a random id.

Additional Information For Detection Modes

When using the White on White and Self Assigned modes additional fields are required as a part of the document object.

White on White

Name	Type	Description
linkedIds	array	An array of objects, containing an two fields: id - referencing the ID encoded for the field in the PDF document. value - specifying more information about the field. For a detailed description, see the Field Descriptor Syntax section.

Self Assigned

Name	Type	Description
docFields	array of arrays	An array containing an additional array for every page of the document. Each element of the inner array is structured according to Field Descriptor Syntax. For a detailed description, see the Field Descriptor Syntax section.

File Descriptor Syntax

All file descriptors contain at least the type field:

Name	Type	Description
type	string	One of the following preset values: url - used for sending the file using a publicly available URL. s3 - used for fetching the file from a public / private Amazon S3 bucket. base64 - used for providing the entire PDF document encoded in base64 as a part of the request.

URL

For type “url” these additional field must be provided:

Name	Type	Description
url	string	A publicly accessible url containing the PDF document.

s3

For type “s3” these additional fields must be provided:

Name	Type	Description
bucket	string	The name of the Amazon Web Services S3 Bucket containing the PDF document.
path	string	Path for the document inside this Amazon Web Services S3 Bucket.

📘

Note

If the bucket is not publicly accessible, EasySend will need to configure an AWS user account for accessing the bucket. Please contact EasySend’s support team for setting this up.

base64

For type “base64” these additional fields must be provided:

Name	Type	Description
data	string	The base64 encoded content of the PDF document.

Field Descriptor Syntax

The field descriptor syntax is used to describe fields on top of the PDF document (either
encoded inside the PDF itself, or under the “linkedIds” object).
The object may contain these fields:

Name	Type	Description
type	string	Can be one of these values: - signature - text - xMarker (used for checkboxes, or multiple choice fields) - signDate (used to show a read only date of another ‘bound’ signature field)
defaultValue	string	Allows the API call to provide an initial value for the field, that can later be edited by the user. The type of defaultValue is determined according to the type of the field: For “text” - defaultValue should be a string. For “xMarker” - defaultValue should be a string if the field is a multiple choice field, and boolean if the field is a checkbox field. For “signature” - defaultValue shouldn’t be used.
role	string, optional	Specifies the role of participant the should fill in this field. If no role is specified, any participant is allowed to fill this field.
validations	array of strings	Specifies a list of validations that need to be applied on top of the field. The list of validations available for usage is defined in the EasySend builder.
translateX	number, optional	Receives values between -100 to 100. Move the position of the field to the right (positive value) or left (negative value). The value is relative in percentages of the page width.
translateY	number, optional	Receives values between -100 to 100. Move the position of the field to the bottom (positive value) or top (negative value). The value is relative in percentages of the page height.
overrideWidth	number, optional	Receives values between 0 to 100. Override the field width with the provided value. The value is relative in percentages of the page width.
overrideHeight	number, optional	Receives values between 0 to 100. Override the field height with the provided value. The value is relative in percentages of the page height.
id	string, optional	The id of the field, EasySend will auto generate a random id if omitted.
required	boolean, optional	Specifies whether the field is required or not (defaults to false).

text Field

Additional option for “text” field:

Name	Type	Description
multiline	boolean, optional	If set to true, creates a multi line input field.

xMarker Field

Additional option for “xMarker” field:

Name	Type	Description
groupValue	string, optional	If provided, the field will be used as a multi option field (radio question). In this case separate fields should be defined for every option, each should be assigned with a different group value. The grouping is done according to the id of the field. If groupValue is omitted, the field will be used as a checkbox, and will have a boolean (true/false) value.

signDate Field

Additional option for “signDate” field:

Name	Type	Description
forField	string	The id of the bound signature field. The signDate field will display the date when the signature was actually filled.

Consent Dialog Section

Name	Type	Description
displayAt	string	One of these preset values: none - will not show a consent dialog, and ignore all other options linkOpen - opens the dialog when the link is opened, before the document signing begins.
title	string	The text to show in the title of the dialog.
body	string	The text to show in body of the dialog.
direction	string, optional	One of these preset values: ltr (left to right) - default rtl (right to left)
checkboxText	string	The text to show near the checkbox
consentId	string, optional	An id for identifying the status of consent for the current request. If omitted, EasySend will generate a random identifier.
buttonText	string, optional	Text for button in bottom of dialog.
additionalText	string, optional	Additional text paragraph next to the checkbox.

📘

Note

Both title, body and checkboxText support markdown text for embedding links, and styled text. (https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
Links always open in a new browser tab.

Mailing Dialog Section

Name	Type	Description
displayAt	string	One of these preset values: none - will not show a dialog, and ignore all other options linkOpen - opens the dialog when the link is opened, before the document signing begins.
title	string	The text to show in the title of the dialog.
body	string	The text to show in the body of the dialog.
direction	string, optional	One of these preset values: ltr (left to right) - default rtl (right to left)
checkboxText	string	The text to show near the checkbox.
buttonText	string	Text for button in bottom of dialog.
emailList	array of strings	the list of emails options that will be able to be selected in the popup.

Document Read Confirmation Section

Name	Type	Description
displayAt	string	One of these preset values: none - will not show a dialog, and ignore all other options linkOpen - opens the dialog when the link is opened, before document signing begins.
direction	string, optional	One of these preset values: ltr (left to right) - default rtl (right to left)
checkboxText	string, optional	The text to show near the checkbox, if not provided will use a default value.
buttonText	string, optional	Text for button in bottom of dialog, if not provided will use a default value.
readConfirmationId	string, optional	An id for identifying the status of read confirmation for the current request. If omitted, EasySend will generate a random identifier.

📘

Note

checkboxText supports markdown text for embedding links, and styled text. (https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
Links always open in a new browser tab.

Auto-Reminder

The Auto-Reminder is a feature that helps sends a reminder of the processes that have not yet been signed and sent back. The auto reminder is added under the “Start” area in the specific “Participant ID“ Communication.

📘

Note

Only support version 2 EasySend API

Name	Type	Description
type	string	The commination output channel for the auto reminder: email, SMS, or both.
countdownTrigger	string	The type of event that triggers the count down of sending the Auto-Reminder: linkSent or linkOpend
subject	string	The title of the email or SMS
body	string	The body of the email or SMS
whenToSend	object	The time trigger countdown in minutes or days, if minutes two fields are required: type - numOfMinutes, minutes - how many minutes to countdown, if days two fields are required: type - daysAndTime, days - how many days to countdown, time - what is the exact time to send the auto-reminder (configured by 24H UTC)

Sample Calls

The following call uses a White on White field detection mode, the type is url, and the Link to the document is sent via email.

JSON

{
    "version": "2",
    "title": "test10_v2",
    "apiKey": "easysend-test",
    "participants": [
        {
            "id": "agent",
            "name": "The agent",
            "role": "admin"
        },
        {
            "id": "customer1",
            "name": "test customer",
            "role": "signer"
        },
        {
            "id": "customer2",
            "name": "The customer",
            "role": "signer"
        }
    ],
    "steps": [
        {
            "communication": {
                "start": [
                    {
                        "participantId": "customer1",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Documents to sign for {{name}}",
                        "body": "hi customer: {{name}}, here is your link: {{link}}"
                    },
                    {
                        "participantId": "agent",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Documents to sign for {{name}}",
                        "body": "hi agent: {{name}}, here is your link: {{link}}"
                    }
                ],
                "finish": [
                    {
                        "participantId": "customer1",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Done",
                        "body": "hi {{name}}, Thanks for submitting!"
                    }
                ],
                "autoReminders": [
                    {
                        "participantId": "customer1",
                        "type": "email",
                        "countdownTrigger": "linkSent",
                        "subject": "A kind reminder for {{name}}",
                        "body": "hi customer: {{name}}, here is your link reminder: {{link}}",
                        "whenToSend": {
                            "type": "numOfMinutes",
                            "minutes": 1
                        },
                        "maxNumOfSends": 1
                    },
                    {
                        "participantId": "customer1",
                        "type": "email",
                        "countdownTrigger": "lastOpened",
                        "subject": "Another kind reminder for {{name}}",
                        "body": "hi customer: {{name}}, here is your link reminder: {{link}}",
                        "whenToSend": {
                            "type": "daysAndTime",
                            "days": 2,
                            "time": "10:00"
                        },
                        "maxNumOfSends": 1
                    }
                ]
            }
        },
        {
            "communication": {
                "start": [
                    {
                        "participantId": "customer2",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Documents to sign for {{name}}",
                        "body": "hi customer: {{name}}, here is your link: {{link}}"
                    }
                ],
                "finish": [
                    {
                        "participantId": "customer2",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Done",
                        "body": "hi {{name}}, Thanks for submitting!"
                    },
                    {
                        "participantId": "agent",
                        "type": "email",
                        "email": "[email protected]",
                        "subject": "Done",
                        "body": "hi {{name}}, Your client has submittied the PDF"
                    }
                ]
            }
        }
    ],
    "documents": [
        {
            "fieldsDetectionType": "whiteOnWhiteDetect",
            "file": {
                "type": "url",
                "url": "https://s3.amazonaws.com/easysend-signature-dev/a.pdf"
            }
        }
    ]
}

The following call uses a auto detect field detection mode, the type is url, and the Link to the document is sent via email.

JSON

{
    "version": "2",
    "apiKey": "ExampleEasySendDemoEnvApiKey",
    "customData": "Example Request 1",
    "participants": [
        {
            "id": "customer",
            "name": "John Smith",
            "role": "customer"
        }
    ],
    "communication": {
        "start": [
            {
                "participantId": "customer",
                "type": "email",
                "email": "{{email}}",
                "subject": "Your form is waiting for signature",
                "body": "Hello {{name}}, <br> Please find below the link to your form. <br><br> <a href='{{link}}'>Click here for your form</a><br><br> Please sign the form and submit it. <br> Thank You!"
            }
        ],
        "finish": [
            {
                "participantId": "customer",
                "type": "email",
                "email": "{{email}}",
                "subject": "You form has been submitted",
                "body": "Hello {{name}}, <br> Please find a copy of the signed form attached to this email."
            }
        ]
    },
    "documents": [
        {
            "id": "9a12f15c-f75b-4a53-b7d1-c2856ef3f036",
            "title": "test Document",
            "fieldsDetectionType": "autoDetect",
            "file": {
                "type": "url",
                "url": "https://easysend-static-assets.s3.us-east-1.amazonaws.com/demo-assets/signature-tool/Example%202%20-%20Field%20Annotations.pdf"
            }
        }
    ]
}

Success Responses

Success/ failure will be determined by the HTTP status code in the response.
200 means success in which case the body of the response is:

JSON

{
	"links": {
		// You’ll receive a link for every role according to the roleId in participants
    "agent": "the link for starting the form filling experience",
      "customer": "the link for starting the form filling experience"
},
	"requestId": "the request id as provided by request, or generated by EasySend if omitted in request"
}

Error Responses

A status code 400 means a failure has occurred. In this case, the body will contain:

JSON

{
	"errorCode": <a number representing the EasySend error code>
	"description": <a textual error description>
}

Code: 403 Forbidden
Content Example:

JSON

Error: An invalid api key was provided

📘

Note

EasySign has a download PDF capability. For additional information, please contact our support team.