Text Tags Walkthrough

Introduction

Using Text Tags with our API involves two parameters:

Parameter	Description
`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 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.

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, use "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:

Copy

Copied

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.

Allow Signer to Edit Pre-filled Data

This feature only supports single-signer flows. The signer that you have assigned to the text-tag component will be able to adjust the pre-filled data. Here is an example with editable pre-filled text tag value:

Copy

Copied

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

Usage of custom_fields for the above text tag:

Copy

Copied

custom_fields:[{"name":"organization_name", "value":"Enter organization name"}]

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.

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||LinkId1]
[text|noreq|signer1|Label2|UniqueId2|email_address||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:

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'

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 recommend hiding 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

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