Legalesign Esignature API quickstart with the PHP SDK

A PHP SDK can be generated using the OpenAPI3 specification of our API and openapi generator.

The package contains its own documentation (in docs/), but the examples below will show you how to get started.

##### Get your API Key

1. Sign up for a trial account. Configure for API when prompted and [email support](mailto:support@legalesign.com?subject=API key request) to get an API Key. You need to show a level of understanding about using REST API. Include a summary of your programming/REST experience.

2. Once issued, your API key will be available in the web app. You'll be in sandbox mode - use the form to enter emails for sending test documents.

3. Your api key goes in the "Authorization" header, and takes the form: Apikey username:secret. Your username and secret will be clearly indicated in the web app.

##### Install

1. Install Composer and ensure 'composer' exec is on your command line - visit Composer.

2. Clone the PHP package.

3. cd into the package, type: composer install.

##### Test a GET request

Start with a basic GET request to make sure your Auth is correct.

'<?php
  
require_once('path-to-package/vendor/autoload.php');

$config = OpenAPI\\Client\\Configuration::getDefaultConfiguration()->setApiKey
       ('Authorization', 'ApiKey username:secret');

$apiInstance = new OpenAPI\Client\Api\GroupApi(new GuzzleHttp\Client(), $config);

try {
    $groups =  $apiInstance->getGroups();
    echo $groups;
} catch (Exception $e) {
    echo 'Exception when calling: ', $e->getMessage(), PHP_EOL;
}

'?>

All being well, JSON text just appeared with your group information. If you have any issues, double and triple check your Auth.

It's common to need your latest signing document, use getDocuments, or getStatuses from the DocumentApi

$docsapi = new OpenAPI\Client\Api\DocumentApi(new GuzzleHttp\Client(), $config);
$status = $docsapi->getStatuses();
$docs = $docsapi->getDocuments();

##### Test a POST request

With Auth credentials confirmed we'll test some POST requests. We'll start by sending a text/html document directly through the DocumentApi, then upload a PDF and send that.

How to get response headers in the OpenAPI generator PHP library: In openapi php, the documented POST requests do not return response headers. But we want the Location header since it contains our new object resource URI. The solution is to use the 'WithHttpInfo' methods, just append "WithHttpInfo" to the documented POST request. Inspect the source PHP to find these 'WithHttpInfo' calls alongside the documented post requests, for example postDocument() becomes postDocumentWithHttpInfo(). See the examples below.

$text = "<h1>Test doc</h1><p>Test doc for testing, <span class=\"field\" 
data-optional=\"false\" data-name=\"Please add your ...\" data-signee=\"1\" 
data-type=\"signature\" data-options=\"\"> ....... </span>";

$signer = array(
   "order" => "0",
   "email" => "my@email.com",
   "firstname" => "firstname-here",
   "lastname" => "lastname-here"
);

$postdata = array(
      "group" => "/api/v1/group/my-group/",
      "name" => "test document working",
      "text" => $text,
      "signers" => [$signer],
      "do_email" => true
);
$post = new \OpenAPI\Client\Model\DocumentPost($postdata);

[$resp, $status, $headers] = $docsapi->postDocumentWithHttpInfo($post);

//the new resource uri is in the headers. 
//N.B. When you create any new object, the ID will be in the Location header of the response.

$doc_ref = $headers['Location'][0];

If you prefer to use PDFs there are a couple of more tasks. First, you need to tell us where your signers should sign. Second, you need to upload the PDF in an initial API request.

For telling us about signatures and form fields Legalesign offers text tags. Put some specially formatted text into your PDF and we convert them into fields we understand. You can also use a pre-saved PDF (using drag and drop in the web app), or X/Y coordinates (use the /fields/ endpoint).

Learn more about text tags.

For the upload there's an API endpoint for that. Lets see how it's all done below.

//get our PDF as base64 data

$pdffile = file_get_contents('testtag.pdf');
$pdfdata = base64_encode($pdffile);

//prep the upload POST data, setting process tags to true.

$pdfupload = array(
    "group" => "/api/v1/group/my-group/",
    "title" => "Test tagged pdf file",
    "pdf_file" => $pdfdata,
    "process_tags" => True
);

//upload the PDF

$pdfapi = new OpenAPI\Client\Api\TemplatepdfApi(
                           new GuzzleHttp\Client(), $config);

[$pdfresponse, $pdfstatus, $pdfheaders] = $pdfapi->postPdfTemplateWithHttpInfo($pdfupload);

//extract the new PDF resource uri, so we can send use it when we create the signing document.

$pdf_resource_uri = $pdfheaders['Location'][0];

//prep signing data. Note we have now replaced the html/text attribute 'text' with 
//the attribute 'templatepdf' together with the new PDF resource uri.

$postdata = array(
      "group" => "/api/v1/group/my-group/",
      "name" => "test document new",
      "templatepdf" => $pdf_resource_uri,
      "signers" => [$signer],
      "do_email" => True
);

[$docresponse, $docstatus, $docheaders] = $docsapi->postDocumentWithHttpInfo($postdata);

$doc_id = $docheaders['Location'][0];

That's it. In this article you have gathered your API key, queried for your documents, sent a HTML based doc in one call, then uploaded a PDF with text-tags and sent that to be signed.

We found the PHP docs from OpenApi generator a little hard to follow, and had to dig around in the source code. Be prepared to do that for more complex situations. But the PHP itself is well laid out and you should have no trouble tracking down the code you need.