Using Templates with the API

Templates created on HelloSign.com and Embedded Templates can be used for sending Signature Requests with the Dropbox Sign API. The API will allow you to interact with the template almost every way except editing.

Note: At the time of writing, templates created on HelloSign.com cannot be edited from the API. Similarly, templates created through Embedded Templates cannot be edited on HelloSign.com

Template Setup

The following steps walk you through the process of creating a template using the Dropbox Sign web interface.

On HelloSign.com, create a template. Upload a document and specify the roles for each signer, for example 'Client' and 'Me'.

Screenshot of 'Roles setup' section in template editor

Click "Next" and add fields to be filled out by each role by dragging them from the left sidebar down to the document.

Add fields for any text or checkmark annotations you'll want to make at the time of sending.

Selecting "Sender" from the "Signers" menu will allow you to add Merge Fields (aka Custom Fields). Custom field data can be populated via API when the template is used in a signature request.

You must also specify a case-sensitive "Merge field" label that you will use to reference the custom field in your API request.

Important

The "Merge field" label is case-sensitive but does not need to be unique, however, uniqueness is recommended to ensure accuracy when specifying the data that will be used to populate the signature request.

Click "Next" and add CC recepients, if applicable. Give your new Template a tittle and add an optional message.

Screenshot of CC recepients, title and message in template editor

Finding a Template ID

You will need to find a template's ID in order to be able to use it with the API.

Finding a Template ID via HelloSign.com

Find the template on the account's Templates page and select it. Click on "More Information" and select the "Template ID".

Finding a Template ID via the API

You can retrieve a paged list of your templates by making a GET call to /template/list. Iterate through this list—requesting additional pages if necessary—to find the template that has a matching title and/or signer_roles.

You can then retrieve the ID from this template object's template_id field.

<?php

namespace Dropbox\SignSandbox;

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

use SplFileObject;
use Dropbox;

$config = Dropbox\Sign\Configuration::getDefaultConfiguration();
$config->setUsername("YOUR_API_KEY");
// $config->setAccessToken("YOUR_ACCESS_TOKEN");

try {
    $response = (new Dropbox\Sign\Api\TemplateApi(config: $config))->templateList(
        page: 1,
        page_size: 20,
    );

    print_r($response);
} catch (Dropbox\Sign\ApiException $e) {
    echo "Exception when calling TemplateApi#templateList: {$e->getMessage()}";
}

Using a Template to Send a Request

You can send a signature request based on a template in your account by making a POST request to /signature_request/send_with_template and including the template_id parameter. You will also be required to provide a unique signer name and email address for each signer role defined in the template.

Important

Locked templates can be used in test mode using the boolean parameter test_mode.

{"template_ids": ["5eb54aaaa71ce8dcaec5d06e93a2754af1712606",
"35e3787bd2e61e496099afe44e2767f076378c12",
"24084dc86475a088b39a49e6fb0fc33006882695"
],
"subject": "Purchase Order",
"message": "Glad we could come to an agreement.",
"signers": [{"role": "Client",
"name": "George",
"email_address": "george@example.com"
}
],
"ccs": [{"role": "Accounting",
"email_address": "accounting@example.com"
}
],
"custom_fields": [{"name": "Cost",
"value": "$20,000",
"editor": "Client",
"required": true
}
],
"signing_options": {"draw": true,
"type": true,
"upload": true,
"phone": false,
"default_type": "draw"
},
"test_mode": true
}

Using Multiple Templates in a Request

You can send a signature request based on multiple templates in your account by making a POST request to /signature_request/send_with_template and including the necessary template_ids[%i%] parameters. You will be required to provide a unique signer name and email address for each signer role in each template.

Note: When sending a request with multipe templates, no more than one template with ordered signers can be used.

Using Long Text in Custom Fields

The text for a custom field should fit into the space available. If it does not fit it will overrun the box and a warning will be thrown. Additionally, if the signer is assigned editor privileges to the custom field and the text overruns the border, an error will be thrown.

The exact length of text that will fit in any given field depends on the nature of that text. If the text uses wide fonts, or uses words that are long and do not wrap efficiently, less text will fit. If the font is small and narrow, more text will fit.

To help you choose an appropriate text length, some guidance is provided in the response object when calling /template/list or /template/{template_id}. The response object contains an avg_text_length object, per custom field. This object contains two properties (num_lines and num_chars_per_line) whose values are the expected number of lines and expected number of characters per line, respectively.If the expected number of characters is exceeded a warning message will be thrown, this warning will contain the avg_text_length object once again.

There may be some instances where a warning message will still be thrown even when the text length is less than the expected value. Typically, this is due to the usage of unusually wide fonts, or words that wrap inefficiently into the available space on the field.