Using Templates with the API

Templates created on HelloSign.com and Embedded Templates can be used for sending Signature Requests with the HelloSign 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 HelloSign 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.

Screenshot of template editor

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.

Screenshot of template editor
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 listrequesting additional pages if necessaryto 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.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/template/list' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$template_list = $client->getTemplates();
Copy
Copied
HelloSignClient client = new HelloSignClient("SIGN_IN_AND_CREATE_API_KEY_FIRST");
TemplateList templateList = client.getTemplates();
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.get_template_list(page=1)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.get_templates
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

hellosign.template.list().then((res) => {
  // handle response
}).catch((err) => {
  // handle error
});
Copy
Copied
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 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.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
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'
Copy
Copied
$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);
Copy
Copied
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);
Copy
Copied
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' }
    ]
)
Copy
Copied
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'
        }
    ]
)
Copy
Copied
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
});
Copy
Copied
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 in custom_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.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
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'
Copy
Copied
$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);
Copy
Copied
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);
Copy
Copied
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' }]
)
Copy
Copied
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'
        }
    ]
)
Copy
Copied
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
});
Copy
Copied
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 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.

Important

Unless working in test_mode, no locked templates can be used in a multi-template request.

curlphpjavapythonrubynodejsdotnet
Copy
Copied
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'
Copy
Copied
$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);
Copy
Copied
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);
Copy
Copied
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'}
    ]
)
Copy
Copied
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'
        }
    ]
)
Copy
Copied
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
});
Copy
Copied
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 privilleges 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.