Using Templates with the API | HelloSign API Documentation
Using templates with the API

Template can be manipulated using the API but they cannot be created this way. As a result, you will need to manually set them up on HelloSign before you can use them with the API.

Template setup

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

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

Click "Prepare Documents" and add fields to be filled out by each role by dragging them from the top bar down to the document.

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

In the field pop-up menu under "Who fills this out?", select "Me (when sending)." This designates the field as a custom field that will be populated by your API request when you use the template to send a signature request.

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

NOTE The 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.
Finding a template ID via hellosign.com

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

Find the template on the documents page and select it. The id is listed in the slide out info panel.

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.

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. Signers may be omitted to provide additional flexibility, but you will receive a warning for each unfilled role. If a signer is not provided for a template role, all fields associated with that role will be removed from the document.

NOTE Locked templates can be used in test mode with using the boolean parameter "test_mode".
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 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.

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. One exception to sending a request with multiple templates is that you cannot use more than one template with ordered signers.

NOTE Unless in test mode, when using multiple templates, all templates must not be locked. Otherwise, an error will be returned.
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 issued. Alternatively, if the signer is assigned editor privilleges to the custom field and the text overruns the border, an error will be returned. The exact length of text that will fit in the space depends on the nature of that text. If the text uses words with wide letters, or uses words that are long and do not wrap efficiently, few words will fit. If the text instead uses small skinny words, lots of words will fit.

Some guidance is given to help you choose an appropriate text length. Refer to "Finding a template ID with the API", the response object contains avg_text_length, which contains the expected number of characters that will fit on each line of the custom field, and how many lines will fit in the custom field. You can use this to choose the best text length. If you exceed the number of characters that fit when sending a template, the warning message will repeat this suggest length information.

It is possible to send fewer than the suggested number of characters, and to still get the warning message. This is because you may be sending unusually wide words, or words that wrap into the available space inefficiently.