Text Tags Field Parsing | HelloSign API Documentation
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
text-merge A text field that has default text set by the api
checkbox-merge A 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.

Auto populating fields

Text tags can be auto populated. For example with this text tag we can auto populate a field with the email address of a signer:

Check out the list ofauto fill types to learn more about the possible values.
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
Sending Text Tags with pre-set values

You have the ability to add pre-set data to the text tag that will be viewed by the signer. To do this, use the word "sender" in place of the word “signer” in the tag. Remember, that if you do this, then the pre-set values you want to use must be sent with the custom_fields param at the time you make the request. If you don't do it you will receive an error callback after the file is processed.

In the case you are creating an unclaimed draft, the pre-set values you supply will be editable by the requester.

Here is an example with pre-set text tag value.

Example text tag:


Usage of custom_fields for the above text tag:

custom_fields:[{"name":"organization_name", "value" : "Acme Co."}]

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.

Allowing a signer to edit pre-set values

You can't have more than one signer when using this feature.

Signer editable text-tag pre-set values use a similar convention to our editable merge fields when sending templates. Use the custom_fields key in the post body of the request to specify the editor index. When using this form of "editable" text tags and 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-set data.

Key Description
name The label or api id of the text tag.
value The 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-set text tag value.

Example for editable text tag:


Usage of custom_fields for the above text tag:

custom_fields:[{"name":"organization_name", "value":"Enter organization name", "editor":"1", "required":"true"}]

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.

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

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

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


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.

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