How to use the everSign eSignature SAAS Document Management PHP API - everSign PHP Document Signing package blog

Introduction

Once you have an account, you will need to enter your specific API credentials into the eversign.class.php file. You can find your credentials by selecting developer from the drop down menu on the left of your dashboard.

protected $apiKey = 'YOUR KEY HERE';
protected $busID = 'BUSINESS ID HERE';

Replace the capitalized text with your credentials for each property. If you have set up more than one business, just use your primary business ID here, you will be able to change the business later if you need to.

Instantiating and Basic Usage Example

You will need to place the class file in a web accessible location and then include and instantiate it in your script file.

include('eversign.class.php');
$eSign = new everSign(true);

The parameter which is being set to true, is whether we will be using the API through SSL (secure) or just standard HTTP (not secure). In this case we are using the secure mode, however you can change that value to false to use the not secure mode.

The API has several endpoints which perform different actions, we will be looking at all of them as we progress through this article. They are:

business or b as a shorthand
document or d
send_reminder or s
download_raw_document or rd
download_final_document or fd
file or f

Getting a list of your businesses

We use the setEndPoint method to tell the class which endpoint we will be using. For the first example we will be using the business endpoint which returns a response containing all the businesses associated with our account.

<?php

include('eversign.class.php');
$eSign = new everSign( true );
$eSign->setEndPoint( 'b' );
$eSign->getResponseCurl( false );
if( !empty($eSign->errorCode) ){
    echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
    die;
}
echo '<pre>';
var_dump($eSign->response);
echo '</pre>';
?>

Notice that we are using the shorthand 'b' for the endpoint, we could also use the complete 'business' endpoint name if we wanted.

On the next line, we are using the getResponseCurl method to store the response from the API. There is a similar method named getResponse, the difference between the two is that one will use CURL and the other will use a file handler to get the response.

I am using the CURL method because it works better over a secure connection. If you use the standard method and you are getting security notices and errors, use CURL instead.

The parameter in the getResponseCurl and getResponse methods is to include the business ID or not. In this case it is set to false since this endpoint does not require the business ID, it is returning all businesses.

If there was an error, it will be displayed, otherwise you should see an object containing information on all of your businesses.

Getting a list of your documents and templates

We use the 'document' endpoint to get details on our documents, which will include all of the settings for each document retrieved. Please note that you will need to have documents already stored to retrieve information on them.

<?php

include('eversign.class.php');
$eSign = new everSign( true );
$eSign->setEndPoint('d');
$eSign->setParam( 'type', 'all');
$eSign->getResponseCurl( false );
if( !empty($eSign->errorCode) ){
    echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
    die;
}
echo '<pre>';
var_dump($eSign->response);
echo '</pre>';
?>

After setting our endpoint, we have introduced a new method, setParam. This is used to set parameters which will be sent with our request to the API. We are setting the 'type' parameter to a value of 'all'. There are several values which can be sent:

all = all documents
my_action_required = documents requiring your action
waiting_for_others = documents waiting for other signer action
completed = completed documents
drafts = documents still in the draft stage
canceled = canceled documents

If you have a premium account which supports templates, you can also use the 'type' parameter to retrieve those using the following values:

templates = all active templates
templates_archived = archived templates
template_drafts = templates still in the draft stage

Working with a single document or template

If you ran the request to get your documents, you will notice a document hash which is basically the ID for that document.

If you are looking at a document in your everSign dashboard, the hash can be found as the last part of the url. To get the details for the single document, we will use the 'document' endpoint and set the document_hash parameter instead of the 'type' parameter we used earlier.

$eSign->setParam( 'document_hash', 'your-document-hash-here');

The response will contain everything you need to know about a document from its settings, associated files, signers, recipients, status, fields, and log entries.

If you want to cancel a document, you would include the document_hash parameter and a 'cancel' parameter set to a value of '1' in the same request.

$eSign->setParam('cancel','1');

Creating a new document

The process to create a document through the API can range from simple to extremely elaborate.

The associated files and all the settings are posted to the 'document' endpoint. I recommend that you become familiar with the section for creating documents at https://eversign.com/api/documentation/methods#create-document. Fortunately the everSign PHP Document Signing package will take care of the heavy lifting for you, so I will touch on the methods available.

setDocParams( $params )

This method passes an array of the basic document parameters and is used like this:

$doc = array(
    'is_draft' => 1,
    'title' => 'My Document Title'
);
$eSign->setDocParams($doc);

addFile( $name, $file )

This method adds a local file and properly encodes it. You would provide the name you want it stored on everSign as and full path to the file as parameters. It will return a local file ID that will be used to assign fields to this file, more on that in a moment.

addFilebyID( $name, $id )

This methods adds a file that you have previously uploaded to everSign. You would provide the name you want it stored on everSign as and the file ID that everSign has assigned to the file you uploaded. We will take a look at files uploads in another section. It will return a local file ID that will be used to assign fields to this file.

addFilebyURL( $name, $url )

This method adds a file that is web accessible. You would provide the name you want it stored on everSign as and the full url where everSign can retrieve it. It will return a local file ID that will be used to assign fields to this file.

addField( $fileID, $params )

Each file has the capability to have different fields added to it. These can include any supported field type with the associated settings. You would provide the local file ID returned by the add file methods mentioned above and the parameters will be an array of fields and their settings. Note that if a document does not contain any signature fields, a signature page will be created for you at the end of the document.

addSigner( $name, $email, $pin='', $message='', $order=0, $id=0, $role='' )

This method will add a signer to the document. You must specify their name and e-mail address and optionally provide a security pin, message, order for the signature page and for templates a user id and role.

addCC( $name, $email, $role='' )

This method will add an e-mail recipient to the document. You must specify their name and e-mail address and optionally provide their role for templates.

addMeta( $key, $value )

This method will add meta key-value pairs to the document. You specify the key and the value.

addTemplateField( $id, $value )

This method will add fields when using a template. You specify the template field ID and the value.

Once all the document properties have been set, you send the created document using the sendDocument() method. The package will post the required fields to the 'document' endpoint using CURL.

Uploading a file

As mentioned in the previous section, you can upload a file that can later be used as a new documents file.

To accomplish this, you would use a standard html form with multipart/form-data enctype and a file field.

Post the file to your script and use the uploadCurl($field) method to send it to the API. The field parameter is the name you used for your file field. The API will return the file ID which you can then use in the addFilebyID method.

<?php

include('eversign.class.php');

$eSign = new everSign(true);
if( isset($_FILES[ 'myfile' ][ 'tmp_name' ]) ) {
    $eSign->setEndPoint( 'f' );
    $eSign->uploadCurl( 'myfile' );
    if( !empty($eSign->errorCode) ){
        echo 'error ' . $eSign->errorCode . ': ' . $eSign->errorText;
        die;
    }
    $file_id = $eSign->response->file_id;
    $doc = array(
        'is_draft' => 1,
        'title' => 'Myfile Upload'
    );
    $eSign->setDocParams( $doc );
    $eSign->addFilebyID( 'Upload Test', $file_id);
    $eSign->addSigner( 'Joe Test', 'joe_test@yourdomain.com');
}
$eSign->sendDocument();
echo '<pre>';
var_dump( $eSign->response );
echo '</pre>';
die;
?>
<!DOCTYPE html>
<html>
<head>
<title>File Upload</title>
</head>
<body>
<form method="post" enctype="multipart/form-data">
<input type="file" name="myfile"><br>
<input type="submit" value="Send File">
</form>
</body>
</html>

The above example will upload the file you selected in the form and then create a new draft document using that file.

Displaying documents

There are two endpoints used to retrieve the documents in Adobe Acrobat (PDF) format.

To retrieve and view the final document in your browser you would set the endpoint to download_final_document and set the document_hash parameter. You then call the displayPDF( $name = '') method, naming the file if you wish.

<?php

include('eversign.class.php');

$eSign = new everSign(true);
$eSign->setEndPoint('fd');
$eSign->setParam( 'document_hash', 'your-document-hash-here');
$eSign->setParam('audit_trail', '1');
$eSign->displayPDF('myfile');
?>

Notice that we have also set the audit_trail parameter to 1, which will append the audit trail to our final document. This option is only available when displaying a final document.

We can also display the raw document by changing our endpoint to download_raw_document.

$eSign->setEndPoint('rd');

Keep in mind that there is not audit trail for raw documents, so that parameter would not be set in this instance.

Conclusion

That covers the basics for interacting with the everSign eSignature API. There are some other features and methods worth mentioning.

sendReminder( $hash, $id )

This method will send a reminder to the signer. You specify the document hash and the signers id. You must also set the endpoint to send_reminder.

setBusID($id)

This method will let you change the default business ID if you need to do so.

resetParams()

This method will reset all the parameters previously set by the setParam method.

I understand that this is quite a bit to absorb in one reading. Familiarize yourself with how everSign documents are managed from the dashboard, read the API documentation and then test the API and it all will start to make sense in no time.