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'.

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.

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/orsigner_roles
.You can then retrieve the ID from this template object's template_id
field.curl 'https://api.hellosign.com/v3/template/list' \
-u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:'
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$template_list = $client->getTemplates();
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
TemplateList templateList = client.getTemplates();
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.get_template_list(page=1)
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.get_templates
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });
hellosign.template.list().then((res) => {
// handle response
}).catch((err) => {
// handle error
});
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var templates = client.ListTemplates();
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 thetemplate_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
test_mode
.curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
-u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
-F 'template_id=5eb54aaaa71ce8dcaec5d06e93a2754af1712606' \
-F 'title=NDA with Acme Co.' \
-F 'subject=The NDA we talked about' \
-F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
-F 'signers[Me][email_address]=jack@example.com' \
-F 'signers[Me][name]=Jack' \
-F 'signers[Client][email_address]=jill@example.com' \
-F 'signers[Client][name]=Jill' \
-F 'test_mode=1'
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\TemplateSignatureRequest;
$request->enableTestMode();
$request->setTemplateId('5eb54aaaa71ce8dcaec5d06e93a2754af1712606');
$request->setTitle('NDA with Acme Co');
$request->setSubject('The NDA we talked about');
$request->setMessage('Glad we could come to an agreement.');
$request->setSigner('Me', 'jack@example.com', 'Jack');
$request->setSigner('Client', 'jill@example.com', 'Jill');
$response = $client->sendTemplateSignatureRequest($request);
TemplateSignatureRequest request = new TemplateSignatureRequest();
request.setTitle("NDA with Acme Co.");
request.setSubject("The NDA we talked about");
request.setMessage("Please sign this NDA and then we can discuss more. Let me know if you have any questions.");
request.setSigner("Me", "jack@example.com", "Jack");
request.setSigner("Client", "jill@example.com", "Jill");
request.setTemplateId("5eb54aaaa71ce8dcaec5d06e93a2754af1712606");
request.setTestMode(true);
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
SignatureRequest newRequest = client.sendTemplateSignatureRequest(request);
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.send_signature_request_with_template(
test_mode=True,
template_id='5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
title='NDA with Acme Co.',
subject='The NDA we talked about',
message='Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
signers=[
{ 'role_name': 'Me', 'email_address': 'jack@example.com', 'name': 'Jack' },
{ 'role_name': 'Client', 'email_address': 'jill@example.com', 'name': 'Jill' }
]
)
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request_with_template(
:test_mode => 1,
:template_id => '5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
:title => 'NDA with Acme Co.',
:subject => 'The NDA we talked about',
:message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
questions.',
:signers => [
{
:email_address => 'jack@example.com',
:name => 'Jack',
:role => 'Me'
},
{
:email_address => 'jill@example.com',
:name => 'Jill',
:role => 'Client'
}
]
)
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });
const opts = {
test_mode: 1,
template_id: '5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
title: 'NDA with Acme Co.',
subject: 'The NDA we talked about',
message: 'Please sign this NDA and then we can discuss more.',
signers: [
{
email_address: 'jack@example.com',
name: 'Jack',
role: 'Manager'
},
{
email_address: 'jill@example.com',
name: 'Jill',
role: 'Employee'
}
]
};
hellosign.signatureRequest.sendWithTemplate(opts).then((res) => {
// handle response
}).catch((err) => {
// handle error
});
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = new TemplateSignatureRequest();
request.AddTemplate("5eb54aaaa71ce8dcaec5d06e93a2754af1712606");
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("Me", "jack@example.com", "Jack");
request.AddSigner("Client", "jill@example.com", "Jill");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
Using a Template with Custom Fields
When sending a signature request based on a template, you can also pass incustom_fields
as an optional parameter.The following example takes the POST request in the previous section and includes custom field data. The signer role 'Client' is allowed to edit the value start_date
.curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
-u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
-F 'template_id=5eb54aaaa71ce8dcaec5d06e93a2754af1712606' \
-F 'title=NDA with Acme Co.' \
-F 'subject=The NDA we talked about' \
-F 'message=Please sign this NDA and then we can discuss more. Let me know if you have any questions.' \
-F 'signers[Me][email_address]=jack@example.com' \
-F 'signers[Me][name]=Jack' \
-F 'signers[Client][email_address]=jill@example.com' \
-F 'signers[Client][name]=Jill' \
-F 'custom_fields=[{"name":"contract_number", "value":"DD21"},{"name":"start_date", "value":"01/10/2016", "editor":"Client", "required":true}]' \
-F 'test_mode=1'
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\TemplateSignatureRequest;
$request->enableTestMode();
$request->setTemplateId('5eb54aaaa71ce8dcaec5d06e93a2754af1712606');
$request->setTitle('NDA with Acme Co');
$request->setSubject('The NDA we talked about');
$request->setMessage('Glad we could come to an agreement.');
$request->setSigner('Me', 'jack@example.com', 'Jack');
$request->setSigner('Client', 'jill@example.com', 'Jill');
$request->setCustomFieldValue('contract number', 'DD21');
$response = $client->sendTemplateSignatureRequest($request);
TemplateSignatureRequest request = new TemplateSignatureRequest();
request.setTitle("NDA with Acme Co.");
request.setSubject("The NDA we talked about");
request.setMessage("Please sign this NDA and then we can discuss more. Let me know if you have any questions.");
request.setSigner("Me", "jack@example.com", "Jack");
request.setSigner("Client", "jill@example.com", "Jill");
request.setCustomField("contract_number", "DD21");
request.setTemplateId("5eb54aaaa71ce8dcaec5d06e93a2754af1712606");
request.setTestMode(true);
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
SignatureRequest newRequest = client.sendTemplateSignatureRequest(request);
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.send_signature_request_with_template(
test_mode=True,
template_id='5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
title='NDA with Acme Co.',
subject='The NDA we talked about',
message='Please sign this NDA and then we can discuss more. Let me know if you have any questions.',
signers=[
{ 'role_name': 'Me', 'email_address': 'jack@example.com', 'name': 'Jack' },
{ 'role_name': 'Client', 'email_address': 'jill@example.com', 'name': 'Jill' }
],
custom_fields=[{ 'contract number': 'DD21' }]
)
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request_with_template(
:test_mode => 1,
:template_id => '5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
:title => 'NDA with Acme Co.',
:subject => 'The NDA we talked about',
:message => 'Please sign this NDA and then we can discuss more. Let me know if you have any
questions.',
:signers => [
{
:email_address => 'jack@example.com',
:name => 'Jack',
:role => 'Me'
},
{
:email_address => 'jill@example.com',
:name => 'Jill',
:role => 'Client'
}
],
:custom_fields => [
{
:name => 'contract_number',
:value => 'DD21'
}
]
)
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });
const opts = {
test_mode: 1,
template_id: '5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
title: 'NDA with Acme Co.',
subject: 'The NDA we talked about',
message: 'Please sign this NDA and then we can discuss more.',
signers: [
{
email_address: 'alice@example.com',
name: 'Alice',
role: 'Manager'
},
{
email_address: 'bob@example.com',
name: 'Bob',
role: 'Employee'
}
],
custom_fields: [
{
contract_number: 'DD21'
}
]
};
hellosign.signatureRequest.sendWithTemplate(opts).then((res) => {
// handle response
}).catch((err) => {
// handle error
});
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = new TemplateSignatureRequest();
request.AddTemplate("5eb54aaaa71ce8dcaec5d06e93a2754af1712606");
request.Title = "NDA with Acme Co.";
request.Subject = "The NDA we talked about";
request.Message = "Please sign this NDA and then we can discuss more. Let me know if you have any questions.";
request.AddSigner("Me", "jack@example.com", "Jack");
request.AddSigner("Client", "jill@example.com", "Jill");
request.AddCustomField("contract_number", "DD21");
request.AddCustomField("start_date", "01/10/2016");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
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 necessarytemplate_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.
Important
test_mode
, no locked templates can be used in a multi-template request.curl 'https://api.hellosign.com/v3/signature_request/send_with_template' \
-u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
-F 'template_ids[1]=5eb54aaaa71ce8dcaec5d06e93a2754af1712606' \
-F 'template_ids[2]=35e3787bd2e61e496099afe44e2767f076378c12' \
-F 'template_ids[3]=24084dc86475a088b39a49e6fb0fc33006882695' \
-F 'title=Contracts' \
-F 'subject=Three Contracts' \
-F 'message=Please review these three contracts and sign them at your earliest convenience.' \
-F 'signers[Me][email_address]=jack@example.com' \
-F 'signers[Me][name]=Jack' \
-F 'signers[Client][email_address]=jill@example.com' \
-F 'signers[Client][name]=Jill' \
-F 'custom_fields=[{"name":"Client Address", "value":"123 Main St, Anytown, ST 12345"},{"name":"Client Phone Number", "value":"(123) 456-7890"}]' \
-F 'test_mode=1'
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\TemplateSignatureRequest;
$request->enableTestMode();
$request->setTemplateId('5eb54aaaa71ce8dcaec5d06e93a2754af1712606', 1);
$request->setTemplateId('35e3787bd2e61e496099afe44e2767f076378c12', 2);
$request->setTemplateId('24084dc86475a088b39a49e6fb0fc33006882695', 3);
$request->setTitle('Contracts');
$request->setSubject('Three Contracts');
$request->setMessage('Please review these three contracts and sign them at your earliest convenience.');
$request->setSigner('Me', 'jack@example.com', 'Jack');
$request->setSigner('Client', 'jill@example.com', 'Jill');
$request->setCustomFieldValue('Client Address', '123 Main St, Anytown, ST 12345');
$request->setCustomFieldValue('Client Phone Number', '(123) 456-7890');
$response = $client->sendTemplateSignatureRequest($request);
TemplateSignatureRequest request = new TemplateSignatureRequest();
request.addTemplateId("5eb54aaaa71ce8dcaec5d06e93a2754af1712606", 0);
request.addTemplateId("35e3787bd2e61e496099afe44e2767f076378c12", 1);
request.addTemplateId("24084dc86475a088b39a49e6fb0fc33006882695", 2);
request.setTitle("Contracts");
request.setSubject("Three Contracts");
request.setMessage("Please review these three contracts and sign them at your earliest convenience.");
request.setSigner("Me", "jack@example.com", "Jack");
request.setSigner("Client", "jill@example.com", "Jill");
request.setCustomFieldValue("Client Address", "123 Main St, Anytown, ST 12345");
request.setCustomFieldValue("Client Phone Number", "(123) 456-7890");
request.setTestMode(true);
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
SignatureRequest newRequest = client.sendTemplateSignatureRequest(request);
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.send_signature_request_with_template(
test_mode=True,
template_ids=[
'5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
'35e3787bd2e61e496099afe44e2767f076378c12',
'24084dc86475a088b39a49e6fb0fc33006882695'
],
title='Contracts',
subject='Three Contracts',
message='Please review these three contracts and sign them at your earliest convenience.',
signers=[
{ 'role_name': 'Me', 'email_address': 'jack@example.com', 'name': 'Jack' },
{ 'role_name': 'Client', 'email_address': 'jill@example.com', 'name': 'Jill' }
],
custom_fields=[
{'Client Address': '123 Main St, Anytown, ST 12345'},
{'Client Phone Number': '(123) 456-7890'}
]
)
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request_with_template(
:test_mode => 1,
:template_ids => [
'5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
'35e3787bd2e61e496099afe44e2767f076378c12',
'24084dc86475a088b39a49e6fb0fc33006882695'
],
:title => 'Contracts',
:subject => 'Three Contracts',
:message => 'Please review these three contracts and sign them at your earliest convenience.',
:signers => [
{
:email_address => 'jack@example.com',
:name => 'Jack',
:role => 'Me'
},
{
:email_address => 'jill@example.com',
:name => 'Jill',
:role => 'Client'
}
],
:custom_fields => [
{
:name => 'Client Address',
:value => '123 Main St, Anytown, ST 12345'
},
{
:name => 'Client Phone Number',
:value => '(123) 456-7890'
}
]
)
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });
const opts = {
test_mode: 1,
template_ids: [
'5eb54aaaa71ce8dcaec5d06e93a2754af1712606',
'35e3787bd2e61e496099afe44e2767f076378c12',
'24084dc86475a088b39a49e6fb0fc33006882695'
],
title: 'Contracts',
subject: 'Three Contracts',
message: 'Please review these three contracts and sign them at your earliest convenience.',
signers: [
{
email_address: 'alice@example.com',
name: 'Alice',
role: 'Me'
},
{
email_address: 'bob@example.com',
name: 'Bob',
role: 'Client'
}
],
custom_fields: [
{
'Client Address': '123 Main St, Anytown, ST 12345',
'Client Phone Number': '(555) 555-5555'
}
]
};
hellosign.signatureRequest.sendWithTemplate(opts).then((res) => {
// handle response
}).catch((err) => {
// handle error
});
var client = new Client("SIGN_IN_AND_CREATE_API_KEY_FIRST");
var request = new TemplateSignatureRequest();
request.AddTemplate("5eb54aaaa71ce8dcaec5d06e93a2754af1712606");
request.AddTemplate("35e3787bd2e61e496099afe44e2767f076378c12");
request.AddTemplate("24084dc86475a088b39a49e6fb0fc33006882695");
request.Title = "Contracts";
request.Subject = "Three Contracts";
request.Message = "Please review these three contracts and sign them at your earliest convenience.";
request.AddSigner("Me", "jack@example.com", "Jack");
request.AddSigner("Client", "jill@example.com", "Jill");
request.AddCustomField("Client Address", "123 Main St, Anytown, ST 12345");
request.AddCustomField("Client Phone Number", "(123) 456-7890");
request.TestMode = true;
var response = client.SendSignatureRequest(request);
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 anavg_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.