Text Tags Walkthrough

Introduction

Using Text Tags with our API involves two parameters:

ParameterDescription
use_text_tags[boolean] Set to true to enable Text Tag parsing in your document. Defaults to false.
hide_text_tags[boolean] Enables automatic Text Tag removal when true. Defaults to false.

To enable Text Tags, send a signature request on a document with text tags and set use_text_tags=true on the request. Your Text Tags will be converted into UI components for the user to interact with. Keep in mind that by default the tags themselves will remain on the page. To hide the tags from the end user you can change the text color to match the background (such as white on white). Alternatively, you can set hide_text_tags=true although we don't recommend this approach because auto-removal can lead to unwanted clipping.

To begin and end a tag, use square brackets "[ ]" in your document. Within the square brackets, use the pipe character "|" to divide the parts of the tag. The first part of the tag is the type. The second part indicates if it is required or not. The third part indicates which signer in the list of signers needs to complete the field. The last two parts are optional and are for setting a label and unique ID. For example:

Copy
Copied
[text|noreq|signer1|Label|UniqueId]

Text Tags let you specify which signer the field is for, what type of field it is, and if the field is required or not in addition to the relative size of the field. The types of fields available are the same as when you create a template:

Text Tag ValueField Type
textText field
checkCheckbox field
dateDate field
initialSigner's initials field
sigSigner's signature field
text-mergeA text field that has default text set by the API
checkbox-mergeA checkbox field that has default value set by the API

The only valid values for field requirement are req and noreq. The value defaults to req if the entry is not understood. The only exception to this is group checkbox validation.

Features

Pre-filled Data

Text tags can automatically populate fields with information using pre-filled data. For example, with this text tag we can automatically pre-fill a field with the email address of a signer:

Copy
Copied
[text|noreq|signer1|Label|UniqueId|email_address|email]

Check out the list of auto fill types to learn more about the possible values.

Sending Text Tags with Pre-filled Data

You have the ability to pre-fill data to the text tag that will be viewed by the signer. To do this, us "sender" instead of “signer” in the text tag. Note: if you do this, then the values you want to pre-fill the field must be sent with the custom_fields parameter at the time you make the API request. If you don't, then you'll receive an error callback after the file is processed.

In the case where you're creating an unclaimed draft, the pre-filled values you supply will be editable by the requester.
Here is an example with pre-filled text tag value:

Copy
Copied
[text-merge|req|sender|organization_name|api_id]

Usage of custom_fields for the above text tag:

generalcurlphpruby
Copy
Copied
custom_fields:[{"name":"organization_name", "value" : "Acme Co."}]
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/send' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -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[1][email_address]=jack@example.com' \
    -F 'signers[1][name]=Jack' \
    -F 'custom_fields=[{"name":"organization_name", "value":"Acme Co."}]' \
    -F 'file[0]=@TextTagsDocument.pdf' \
    -F 'use_text_tags=1' \
    -F 'hide_text_tags=1' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$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->addSigner('jack@example.com', 'Jack');
$request->addSigner('jill@example.com', 'Jill');
$request->addFile($path_to_text_tags_document);
$request->setCustomFieldValue('Client Address', '123 Main St, Anytown, ST 12345');
$request->setUseTextTags(true);
$request->setHideTextTags(true);
$response = $client->sendSignatureRequest($request);
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request(
    :test_mode => 1,
    :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'
        },
        {
            :email_address => 'jack@example.com',
            :name => 'Jack'
        }
    ],
    :custom_fields => [
        {
                :name => 'Cost',
                :value => '$20,000'
        }
    ],
    :files => ['TextTagsDocument.pdf'],
    :use_text_tags => 1,
    :hide_text_tags => 1
)

In the example above, a textbox would be created with the value "Acme Co.". Note that this value will not be editable. If you want to allow a signer to edit the value, see the next example.

Allow Signer to Edit Pre-filled Data

This feature only supports single-signer flows.
Making pre-filled text-tag fields editable by the signer uses a similar convention to "editable merge fields" that are sent using templates. Use the custom_fields parameter in the post body of the request to specify the editor index. When using this form of "editable" text tags, if you don't pass an "editor" in the custom_fields data, you will receive an error callback after the file is processed. The editor is the signer who can change the pre-filled data.

KeyDescription
nameThe label or api id of the text tag.
valueThe value you want it to default to.
editor(optional)The signer that can edit the field.
required(optional)Whether the field is required, this will over ride the text tag

Here is an example with editable pre-filled text tag value.Example for editable text tag:

Copy
Copied
[text-merge|req|signer1|organization_name|api_id]

Usage of custom_fields for the above text tag:

bashcurlphpruby
Copy
Copied
custom_fields:[{"name":"organization_name", "value":"Enter organization name", "editor":"1", "required":"true"}]
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/send' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -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[1][email_address]=jack@example.com' \
    -F 'signers[1][name]=Jack' \
    -F 'custom_fields=[{"name":"organization_name", "value":"Enter organization name", "editor":"signer1", "required":"true"}]' \
    -F 'file[0]=@TextTagsDocument.pdf' \
    -F 'use_text_tags=1' \
    -F 'hide_text_tags=1' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$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->addSigner('jack@example.com', 'Jack');
$request->addSigner('jill@example.com', 'Jill');
$request->addFile($path_to_text_tags_document);
$request->setCustomFieldValue('Client Address', '123 Main St, Anytown, ST 12345', 0);
$request->setUseTextTags(true);
$request->setHideTextTags(true);
$response = $client->sendSignatureRequest($request);
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request(
    :test_mode => 1,
    :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'
        },
        {
            :email_address => 'jack@example.com',
            :name => 'Jack'
        }
    ],
    :custom_fields => [
        {
            :name => 'Cost',
            :value => '$20,000',
            :editor => 0
        }
    ],
    :files => ['TextTagsDocument.pdf'],
    :use_text_tags => 1,
    :hide_text_tags => 1
)

In the example above, an editable textbox would be created with a value of "Enter organization name". The textbox will be editable by the signer. If you assign the text-tag component to the signer, but you don't include the editor in the custom fields, the field will default to being editable and required by the signer.

Link Text Fields

You can link two or more text fields. For example with these two text tags:

Copy
Copied
[text|noreq|signer1|Label1|UniqueId1|email_address_1||LinkId1]
[text|noreq|signer1|Label2|UniqueId2|email_address_2||LinkId1]

You enter data into one linked text field, which automatically fill all other linked text fields.

Matching Signer API Parameters

When you write a Text Tag you must assign it to somebody. The number N in "signerN" represents the signer index for when you make the API call itself. For example with these two text tags:

Copy
Copied
[sig|req|signer1|OptionalLabel|OptionalID]
[initial|req|signer2|OptionalLabel|OptionalID]

You have specified that signer1 is required to sign and signer2 is required to initial. The corresponding API call for this might look something like this:

curlphpjavapythonrubynodejsdotnet
Copy
Copied
curl 'https://api.hellosign.com/v3/signature_request/send' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -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[1][email_address]=me@example.com' \
    -F 'signers[1][name]=Me' \
    -F 'signers[2][email_address]=jack@example.com' \
    -F 'signers[2][name]=Jack' \
    -F 'file[0]=@TextTagsDocument.pdf' \
    -F 'use_text_tags=1' \
    -F 'hide_text_tags=1' \
    -F 'test_mode=1'
Copy
Copied
$client = new HelloSign\Client('SIGN_IN_AND_CREATE_API_KEY_FIRST');
$request = new HelloSign\SignatureRequest;
$request->enableTestMode();
$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->addSigner('me@example.com', 'Me');
$request->addSigner('jack@example.com', "Jack');
$request->addFile($path_to_text_tags_document);
$request->setUseTextTags(true);
$request->setHideTextTags(true);
$response = $client->sendSignatureRequest($request);
Copy
Copied
SignatureRequest request = new SignatureRequest();
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.addSigner("me@example.com", "Me");
request.addFile(new File("TextTagsDocument.pdf"));
request.setUseTextTags(true);
request.setHideTextTags(true);
request.setTestMode(true);
Copy
Copied
client = HSClient(api_key='SIGN_IN_AND_CREATE_API_KEY_FIRST')
client.send_signature_request(
    test_mode=True,
    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': 'me@example.com', 'name': 'Me' },
        {'email_address': 'jack@example.com', 'name': 'Jack'}
    ],
    use_text_tags=True,
    hide_text_tags=False,
    files=['TextTagsDocument.pdf']
)
Copy
Copied
client = HelloSign::Client.new :api_key => 'SIGN_IN_AND_CREATE_API_KEY_FIRST'
client.send_signature_request(
    :test_mode => 1,
    :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 => 'me@example.com',
            :name => 'Me'
        },
        {
            :email_address => 'jack@example.com',
            :name => 'Jack'
        }
    ],
    :files => ['TextTagsDocument.pdf'],
    :use_text_tags => 1,
    :hide_text_tags => 1
)
Copy
Copied
const hellosign = require('hellosign-sdk')({ key: 'SIGN_IN_AND_CREATE_API_KEY_FIRST' });

const opts = {
  test_mode: 1,
  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: 'alice@example.com',
      name: 'Alice'
    },
    {
      email_address: 'bob@example.com',
      name: 'Bob'
    }
  ],
  files: ['NDA-with-text-tags.pdf'],
  use_text_tags: 1,
  hide_text_tags: 1
};

hellosign.signatureRequest.send(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 SignatureRequest();
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@example.com", "Me");
request.AddSigner("jack@example.com", "Jack");
request.AddFile("C:\Users\Me\My Documents\TextTagsDocument.pdf");
request.UseTextTags = true;
request.HideTextTags = true;
request.TestMode = true;
var response = client.SendSignatureRequest(request);

Defining Tags as Variables

A tag definition starts with def:$tagName, and is otherwise like a normal tag:

Copy
Copied
[def:$tagName|text,check,data,initial,sig|req,noreq|signerN|OptionalLabel|OptionalID]

A tag variable starts with just $tagName, and may also have a label an ID:

Copy
Copied
[$tagName|OptionalLabel|OptionalID]

For more information on defining and using variables see Sizing and Substitution.

Grouping Checkboxes

You can group checkbox by adding characters after the req. For example, if you have a list of checkboxes and want to require that the user has to choose at least 1 and can choose up to 3.

Copy
Copied
[def:$color|check|req1-3|signer1]

Let's say you had 5 checkboxes and you wanted to ensure that the user chooses 2 or more.

Copy
Copied
[def:$color|check|req2-ormore|signer1]

Let's say you had 10 checkboxes and you wanted to ensure that the user checks 4.

Copy
Copied
[def:$color|check|req4|signer1]

Options are:

Copy
Copied
# The exact number of checkboxes the user must check
req3
# The range of checkboxes that must be checked
req2-5
# Minimum number of checkboxes that must be checked
req3-ormore

Tag Removal

There is a parameter that can enable automatic tag removal called hide_text_tags. While this may seem convenient, we actually don't recommend it. The reason is that automatic tag removal can be an inexact science and unwanted clipping may occur.

important

Instead of using automatic tag removal, we recommendhiding your tags by making their color match the background of the document(such as white on white). This is especially important if your document doesn't have much space between items.

In general, for best results, use a document with double line spacing and a font between 12 and 16 points. Because there can be display problems, it's a good idea to test your document before using it with real signers. If there are problems, you can then modify your document to address them.

Usage Options

Sizing and Substitution

For any text tags [with the exception to signature block], font size is restricted to a font size of 12pt:

Copy
Copied
[sig|req|signer4            ]

To make the tag shorter, you can use tag variables. Choose a place in the document that is blank, and put the tag variable there. The blank area can be on any page. To create a tag variable, start the tag with def:$ and then the name of the tag:

Copy
Copied
[def:$tiny|sig|req|signer4]

In another part of the document, you can refer to the tag variable using $ and the tag name again:

Copy
Copied
[$tiny]

If hide_text_tags is set to true then both tags will be removed, but only the second tag will be replaced with a field. This same technique can be used to save typing. If you have many tags to place, perhaps because there is an large array of checkboxes in your document, you can use a tag variable to specify the type of tag, and then re-use it:

Copy
Copied
[def:$chk|check|noreq|signer1]

    A: [$chk] B: [$chk]
    C: [$chk] D: [$chk]

If a tag is not valid it will be left on the document. If a variable is not used, or a reference to a variable not found, the tag will still be removed from the document.

Labels and Unique IDs

You may also wish to add a label for the signer to see displayed over the field. Specify the label after the signer in the tag:

Copy
Copied
[text|noreq|signer1|Address]
[def:$zip|test|req|signer1|ZipCode]

You can also specify a unique ID for the tags. The unique ID is optional, and follows the label:

Copy
Copied
[text|noreq|signer1|Address|perm_addr]

If you do not want to use a label, but you do want a unique ID, you must leave the label section empty:

Copy
Copied
[text|noreq|signer1||perm_addr]

You can also use labels and unique IDs in variable tags, in either the definition or the variable.

Copy
Copied
[def:$tiny|sig|req|signer4|Label|id123]
[$tiny|Different_Label|id456]

Note that if you re-use a variable definition without specifying a new unique ID, the existing ID will be renumbered so that it remains unique. Any other IDs that are repeated will also be renumbered so that they are unique.
Optionally, each text field may contain a validation type, which follows the unique ID. Check out the list of validation types to learn more about the possible values.

Copy
Copied
[text|req|signer1|Label|UniqueID_1|bank_account_number]
[def:$phone|text|req|signer1|Label|UniqueID_2|phone_number]

Optionally, each text field may contain an auto fill type, which follows the validation type. Check out the list of auto fill types to learn more about the possible values.

Copy
Copied
[text|req|signer1|Label|UniqueID_1|email_address|email]
[def:$email|text|req|signer1|Label|UniqueID_2|email_address|email]

Possible Problems

Allowed Characters

Tag elements can be made of alpha-numeric characters, and the underscore "_" character. Tag types and signer numbers are case insensitive, but tag variables are case sensitive and case is preserved in the label.

Tag Detection

Tags are detected by text value, not by OCR, so the documents supplied must contain literal text for tags. PDF files are recommended, because the location of the tags is important. With other formats, such as plain text, the tag may end up in a different location than expected. The tag may even wrap from one line to the next, which will cause the tag to be ignored.

Specifying Signers

Signers must be part of a list without gaps, so a set of documents could not specify only "signer1" and "signer3". Every signer mentioned in a tag must be specified in the signature request. Every signer specified in the signature request must be in a tag. If the document refers to "signer1" then in the Send Signature Request API request there must be a signers[1][name] and a signers[1][email_address] parameter set.

Removing Tags

We recommend writing your tags using a font that is not visible, such as using a white font on a white background. If you do NOT do this, the tags will be read and understood but the Text Tags will still be present on the document. You can have us attempt to hide the text by setting hide_text_tags=true. However we don't recommend this as occasionally, removing the tags on the backend can cause undesired clipping side-effects. For more information see the Tag Removal section.

Errors

If your signature request is not valid because of missing signer information or missing fields for signers to complete, there will not be an immediate error. Instead, you can be notified of the error as an event. The error event type will be signature_request_invalid. You can read more about this in our events and callbacks walkthrough.

Example Document

To see an example of a document with invisible text tags you can download this pdf document. Keep in mind you may not be able to see the tags in this document because they are white-on-white:

Document with text tags hidden Screenshot of docs using text tags with a white font set on a white background

Document with text tags visible Screenshot of docs using text tags with a white font set on a white background but the text is selected so you can see them