Signature Request Walkthrough

There are several ways to send a signature request using the Dropbox Sign API. The method you may want to use will depend on your use case. Take a look at the different options we offer to decide which scenario fits your needs.

Scenarios

How do you plan on creating your signature requests?

You provide the files to create the request and we add a signature page for the signers to sign.

Files

Setup a template on hellosign.com and reuse it with custom data when sending signature requests.

Templates

You provide the files and tell us exactly where form fields go on them. No signature page is added in this case.

Form Fields

Using Files

This is the simplest way to create a signature request, attach the file(s) along with signer details and you're all set. A signature page will be appended at the end of your documents with a signature field for each signer involved.

This will send a signature request to Jack and Jill. Both will receive an email with a link to sign the request. The link will take them to a page where they can review the document before adding their signatures onto the signature page.The signature_request_id field, found in the response object, allows you to keep track of the request status as shown in the signature request status section. You can find more details about the Signature Request object on the API reference page.

Using Templates

If you need to send signature requests with the same documents often and need to have them filled in specific places, then using templates make perfect sense. This way, you save yourself the trouble of uploading the document files everytime and get to decide where the signers should fill in information.

Templates allow you to specify form fields (text, check boxes, signatures, etc...) that the signers should fill. But it also offers the possibilty to define "custom fields" that will be filled when the request gets sent via the API and will be shown to the signers.

Visit our template walkthrough if you're not familiar with templates and how to use them with the API.

This will send a signature request to George. George will receive an email with a link to sign the request. The link will take them to a page where they can review the document and fill out the required fields.The signature_request_id field, found in the response object, allows you to keep track of the request status as shown in the signature request status section. You can find more details about the Signature Request object on the API reference page.

Using Files and Form Fields

warning

Due to a bug, the form_fields_per_document parameter only supports two-dimensional arrays right now. We're testing a fix right now. You can read more here: Using Form Fields per Document.

If you need to send documents with changing content but the same form fields, we have a better alternative than using templates. Rather than creating a large number of templates to cover all the variations, you can create one single template and retrieve the coordinates of the associated form fields. With that information, you can provide the list of form fields and their coordinates when sending the signature request via the API.

Note: Text Tags are a much easier way to handle this scenario as they allow you to place tags in the document that will be converted to components when the request is sent.

This following request will create a signature request for two signers. On the first document (NDA), there will be a signature field and a date field for the signer. No form fields will be present on the second document.

For more information about form fields and their attributes, see form_fields in Templates on the API reference page.

Retrieving Signature Status

There are 2 ways get the status of a document. The preferred method is to provide a callback url which we'll post events to. The option to poll the API is also available but it's impractical in most situations since signers may take a while to view and sign your documents.

Webhooks (preferred)

Read our documentation about Dropbox Sign Events to get a better understanding of how webhooks work with your account and apps.

Polling

Important

If you poll, any frequency you choose has disadvantages, either having to make thousands of requests per signature request over a day or two or making fewer requests and having more time pass between the signature request completion and your system finding out about it. Webhooks solve both of these problems.

Checking the status of a Signature Request

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestGet($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Retrieving Documents

The Dropbox Sign API can be used to download files (documents) in several different formats. Those formats include:

A binary file
A hyperlink to a downloadable file
A data uri (base64 encoded string)

Download Files

You can either download a single PDF document or separate pages in a zip file. Either option will contain all the signatures and information that signers have added so far.

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";
$fileType = "pdf";

try {
    $result = $signatureRequestApi->signatureRequestFiles($signatureRequestId, $fileType);
    copy($result->getRealPath(), __DIR__ . '/file_response.pdf');
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Download Files as Data Uri

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestFilesAsDataUri($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}

Download Files as File Url

<?php

require_once __DIR__ . "/vendor/autoload.php";

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();

// Configure HTTP basic authorization: api_key
$config->setUsername("YOUR_API_KEY");

// or, configure Bearer (JWT) authorization: oauth2
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

$signatureRequestApi = new Dropbox\Sign\Api\SignatureRequestApi($config);

$signatureRequestId = "fa5c8a0b0f492d768749333ad6fcc214c111e967";

try {
    $result = $signatureRequestApi->signatureRequestFilesAsFileUrl($signatureRequestId);
    print_r($result);
} catch (Dropbox\Sign\ApiException $e) {
    $error = $e->getResponseObject();
    echo "Exception when calling Dropbox Sign API: "
        . print_r($error->getError());
}