Text Tags Walkthrough

Introduction

Using Text Tags with our API involves two parameters:

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:

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

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:

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

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

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.

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:

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

Usage of custom_fields for the above text tag:

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:

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

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

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:

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

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

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

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

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

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

Options are:

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

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:

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

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

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

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

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

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

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

[text|noreq|signer1||perm_addr]

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

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

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

[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 the Events Overview.

Document Field Detection Feedback

You can use the Detect Document Fields endpoint to check a PDF’s Text Tags before sending a signature request. Set detection_mode to text_tags and upload the same PDF you plan to send:

curl 'https://api.hellosign.com/v3/document/detect_fields' \
    -u 'SIGN_IN_AND_CREATE_API_KEY_FIRST:' \
    -F 'file=@TextTagsDocument.pdf' \
    -F 'detection_mode=text_tags'

This endpoint analyzes the document without creating a signature request or changing the PDF. It returns each detected Text Tag as an API-ready field in form_fields_per_document. It also returns any checkbox or radio group definitions in form_field_groups.

A successful response can include detected fields along with warnings and errors:

• Top-level warnings describe how the request was handled. For example, parameter_ignored means that an unsupported parameter was not used.
• detection_result.warnings describe problems that did not stop field detection. You can still use the other fields in the response.
• detection_result.errors describe tags or fields that could not be processed. A 200 response can include these errors and any fields that were detected successfully.
• error_path, when present, points to the affected item in form_fields_per_document.

{
    "detection_result": {
        "document_hash": "7f83b1657ff1fc53b92dc18148a1d65dfa13514f2d4e3f5ab863d493e6f5d6a8",
        "detection_mode": "text_tags",
        "page_count": 1,
        "pages_analyzed": "all",
        "detected_at": 1780243200,
        "form_fields_per_document": [
            {
                "document_index": 0,
                "api_id": "signature_1",
                "type": "signature",
                "page": 1,
                "required": true,
                "signer": 0,
                "width": 120,
                "height": 30,
                "x": 72,
                "y": 144
            }
        ],
        "form_field_groups": [],
        "warnings": [
            {
                "warning_name": "form_fields_placement",
                "warning_msg": "A text tag is outside the page bounds."
            }
        ],
        "errors": [
            {
                "error_name": "pdf_text_tag_parse_error",
                "error_msg": "A text tag could not be parsed."
            }
        ],
        "suggestions": []
    },
    "warnings": []
}

Reusing Detected Fields

The returned form_fields_per_document and form_field_groups use the same format accepted by signature request endpoints. You can pass both values into a later signature request instead of setting use_text_tags=true and asking Dropbox Sign to detect the tags again:

const signatureRequest = {
    file: [samePdf],
    form_fields_per_document: detectionResult.form_fields_per_document,
    form_field_groups: detectionResult.form_field_groups
};

Reusing the detected fields can make repeated signature requests faster because the Text Tags do not need to be extracted and converted for every request. You can also store the detected field definitions and reuse them whenever you send the same document layout.

Keep the following in mind when reusing a detection result:

• Do not set use_text_tags or hide_text_tags on the signature request. The returned coordinate fields replace Text Tag parsing.
• Use the same PDF and signer order. Each field’s page and coordinates refer to the analyzed document, and its signer index comes from the signer encoded in the Text Tag.
• The endpoint analyzes one PDF, so returned fields have document_index set to 0. If that PDF is not the first file in a multi-document signature request, update each field’s document_index to match its position in the request.
• Compare document_hash with the SHA-256 hash of the document you expect to send. Run field detection again if the document content, page size, page order, or layout changes.
• Pass form_field_groups with the fields when any field references a checkbox or radio group.
• Review detection_result.warnings and detection_result.errors before storing or reusing a result. A successful response can contain only a partial set of fields.
• Field detection does not remove the visible Text Tag text from the PDF. Keep tags visually hidden in the source document because hide_text_tags is not used when you reuse detected fields.

For more information about the returned field structure, see Using Form Fields per Document.

The following errors can appear in detection_result.errors:

If the request is invalid or the document cannot be opened for analysis, the endpoint returns a top-level error instead of detection_result, commonly with HTTP 422.

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