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.

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.

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.