Using Text Tags Field Parsing

Using Text Tags with our API involves two parameters:

Parameter Description
use_text_tags [boolean], defaults to 0 if not set
hide_text_tags [boolean], defaults to 0 if not set

To enable Text Tags send a signature request and make sure you set "use_text_tags=1". 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=1" although we don't recommend this 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:


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 Value Field Type
text Text field
check Checkbox field
date Date field
initial Signer's initials field
sig Signer's signature field

The only valid values for field requirement are "req" and "noreq". The value defaults to "req" if the entry is not understood.

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:


You have specified that signer[1] is required to sign and signer[2] is required to initial. The corresponding API call for this might look something like this:

Defining Tags as Variables

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


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


For more information on defining and using variables see 'Sizing and Substitution' under Usage Options.

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.


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


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


Options are:

req[The exact number of checkboxes the user must check]
req[Minimum number of checkboxes that must be checked]-[Maximum number of checkboxes that can be checked]
req[Minimum number of checkboxes that must be checked]-ormore
Tag Removal

There is a parameter than 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: We recommend instead of enabling automatic tag removal you should try to hide your tags by making their color match the background (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 is 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

By default, the new field has the same width and height as the original tag text. The height is always fixed to the text height that HelloSign offers the signer, but you can change the width of the tag. To make the tag wider, use spaces:

[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:


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


If "hide_text_tags" is set to 1 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:


                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:


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


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


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


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.

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 signature_request API request there must be a "signers[1][name]" and a "signers[1][email_address]" parameter set.

Tag Removal

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=1 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.


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

Document with text tags visible