Introduction to the eversign Electronic Signature API

Continued from page 5. 

If you're using PHP, eversign provides a PHP SDK. It's especially helpful for providing an object-oriented way to structure requests. For example:

$signer = new Signer();
$signer->setName("John Doe");
$signer->setEmail("john.doe@eversign.com");
$signer->setRequired(true);
$document->appendSigner($signer);

Typically, detailed data for API calls is transmitted within POST fields. This is another area where the eversign SDK is helpful.

The eversign API is very well designed. In fact,the process that I went through above manually is accomplished with one automated API method, Use Template:

However, eversign offers a full-suite of API methods and it's well documented. Depending on how broad an automation system you want to build, you may need to use only a few of these or all of them.

For example, gathering documents and status from a variety of accounts is done with these:

Delivering documents of signatures and reminding signers is done with these:

Managing files is done with these:

Occasionally, you will need these:

It's comprehensive but not at all overwhelming.

Using a Template with the eversign API

In this scenario, we'll use the template we created through the visual interface, and upload all of the data for a specific document signature request. Then, eversign will deliver requests for signatures to each recipient which we can specify through the API.

Let's begin by reviewing the UseTemplate documentation and all of the information required for a Use Template operation. While just this one method launches an entire new document request and can do nearly everything, it does require detailed sets of data input.

The Template

Here's the template details for the new document request:

Name Description
Name Description
template_id Set to the Template ID of the template you would like to use.
title This parameter is used in order to specify a document title.
message This parameter is used in order to specify a document message.
redirect This parameter is used to specify a custom completion redirect URL. If empty, the default Post-Sign Completion URL specified in your eversign Business or the eversign signature completion page will be used.
client This parameter is used to specify an internal reference for your application, such as an identification string of the server or client making the API request.
expires This parameter is used to specify a custom expiration date for your document. (Required format: Unix Time Stamp) If empty, the default document expiration period specified in your business settings will be used.

The Document Signers

From your database, you can identify the signers for the eversign service through the signers objects.

This object must contain a sub-array for each signing role of your template. Each sub-array must contain the role name, signer name and signer email address. At this point, an optional Signer PIN and message can be specified as well. Only the role is required.

Name Description
role The name of this signing role.
name This parameter is used to specify the full name of the current signer.
email This parameter is used to specify the email address of the current signer.
pin This parameter is used to specify a Signer PIN for the current signer.
message This parameter can be used to specify a custom message (upon document delivery) for the current signer. Please note that for the current signer the general document message will be overridden by this parameter.

All required roles must be specified. If you specified cc: fields for your signers, there is a recipient object for these:

Name Description
role The name of this CC role.
name This parameter is used to specify the full name of the current CC.
email This parameter is used to specify the email address of the current CC.

The No Signer Fields

For merge fields, such as our examples of HourlyPricing and MaxPricing, you can specify a fieldsObject:

Name Description
identifier The field's Field Identifier.
value The field's value. Click here to see a list of allowed field values per field.

Making the Use Template Request

For our API requests, we POST all our data to the endpoint below:

https://api.eversign.com/api/document
    & access_key = YOUR_ACCESS_KEY
    & access_key = YOUR_ACCESS_KEY
    & business_id = ####

Below is all of the information put together in a multi-level array that we'll submit to the use template method.

If you visit the templates menu, you can right click the links of the template names to see the template_ids. You can also open a template and get the template_id from the URL.

{
    "template_id": "j6yMcaF4gQBIIQ",
    "title": "My New Document",
    "message": "This is my message.",
    "redirect": "https://myredirect.com",
    "client": "",
    "expires": 1494276966,
    "signers": [{
        "role": "Sales Rep",
        "name": "Paul McSign",
        "email": "paul@mcsign.com",
        "pin": "1234",
        "message": "This is my custom message to Paul."
    }, {
        "role": "Client",
        "name": "Julian McSign",
        "email": "julian@mcsign.com",
        "pin": "4321",
        "message": ""
    }],
    "recipients": [{
        "role": "Assistant",
        "name": "Jane McSign",
        "email": "jane@mcsign.com"
    }, {
        "role": "Finance Department",
        "name": "Frank McSign",
        "email": "frank@mcsign.com"
    }],
    "fields": [{
        "identifier": "unique_field_identifier_1",
        "value": "Merge Field Content"
    }, {
        "identifier": "unique_field_identifier_2",
        "value": "Other Merge Field Content"
    }]
}

eversign supports signing order. For example, you might first send a real estate document to the seller and then afterwards to the buyer.

Managing and Monitoring the Status of Templates

With a large automated API implementation, you'll likely regularly be checking on identified templates to see their status, send reminders and complete transactions.

Likely, your solution will call Get Document/Template to determine the status of signatures on a template and which users it should be sent to.

Using the Get Template Method

Likely, your solution will call Get Document/Template to update to determine the status of signatures on a template and which users it should be sent to. Requests look like this:


https://api.eversign.com/api/document
    ? access_key = YOUR_ACCESS_KEY
    & business_id = 1
    & document_hash = j6yMcaF2gQAIIQ

If you don't yet have the document_hash, you can use the List Documents request to get them for all documents and store them locally in your system.

In general, it's probably helpful for your system to cache the document hash id after the use template operation.

Jeff Reifman is a technologist and freelance writer, founder of Lookahead Consulting. He’s also the creator of startup Meeting Planner, a simpler way to schedule meetups of all kinds.
 

Comments (0)