Hidden Tags
Introduction
Hidden tags offer a way of specifying the location of document fields using invisible text tags in the original document before uploading it. One of the several advantages of hidden tags is the ability to place fields without knowing their coordinates, enabling you to skip manually dragging fields within the Xodo Sign web interface, which is especially useful when working with a large number of varying documents and templates.
Enable Hidden Tags:
By default, the Xodo Sign API does not look for hidden tags in your document. In order to enable
this feature, add the use_hidden_tags parameter to your API request and set it to
1 when creating a document:
[...] "sandbox" = 1, "is_draft" = 0, "use_hidden_tags" = 1, "title": "Sample Document", "use_signer_order": 1, [...]
When providing a file_id for document creation
(see Create Document) be aware that
text tags are only parsed when the file is being initially uploaded. To enable text tag parsing
for file uploads you can:
- Enable the respective business setting under
Business Settings → General Preferences → Enable hidden tags - Provide the parameter
use_hidden_tagswhen uploading a file (see Upload File), which will override the business setting:https://api.eversign.com/file ? access_key = YOUR_ACCESS_KEY & business_id = 1 & use_hidden_tags = 1
Usage
A hidden tag is a text element wrapped in square brackets [ ] containing a series of
options in a specific order, all divided by | symbols. You can specify a total of 9
options, such as field type, signer ID, required/non-required, field label, field identifier,
and more.
Example: Here's a hidden tag using all available options:
[text|req|signer1|Name|name_1|Paul McSign|125|50|letters_only]
In the example above we are creating a required 125x50px text field, prefilled with the value "Paul McSign", with "letters_only" field validation enabled. Additionally, the field label is set to "Name" and the field identifier is set to "name_1".
Options: Below you will find all 9 available options explained:
| Order | Name | Description |
|---|---|---|
| 1 | Field Type | Enter your preferred field type. See a list of available field types here ». [Example:
sig for Signature]
|
| 2 | Required / Non-Required | Enter req for required or nonreq for a non-required field.
|
| 3 | Signer Number | Enter signerX with X being the number/ID of the signer this
field is for. [Example: signer1]
|
| 4 | Field Label | Enter your field label. This will be displayed as the placeholder for text fields.
[Example: Name]
|
| 5 | Field Identifier | Enter your field identifier. [Example: signature_2] |
| 6 | Prefill Field Value | Enter a value to prefill your field with. Different field types come with different prefill options, which are explained here ». |
| 7 | Field Width Override | By default, your field will come with the same width as your hidden tag. You can
override this width by entering a pixel width here. [Example: 125]
|
| 8 | Field Height Override | By default, your field will come with the same height as your hidden tag. You can
override this height by entering a pixel height here. [Example: 50]
|
| 9 | Field Validation | Enter your preferred field validation type, if any. |
[text|req|signer1||name_1|...]
Supported Field Types: The following field types can be created using hidden tags. "Prefill Value" refers to the type of value your field can be prefilled with.
| Field Type | Context | Prefill Value |
|---|---|---|
sig |
Signature field | |
init |
Initials field | |
text |
Text field | String |
date |
Date Signed field | |
check |
Checkbox field | 0 for un-checked and 1 for checked |
Defining Variables
Complex hidden tags can become very long and confusing if they are placed multiple times. In order to prevent having to copy/paste identical hidden tags, you can define a given hidden tag as a variable and reuse it simply by referencing this tag across your document.
Variables are defined by prepending def: followed by your $variableName.
Example: Below we are defining an email address field as a variable:
[def:$emailTag|req|signer1|Email Address|email_1||150|30|email_address]
Our example field above is a required email address field for signer 1, containing "Email
Address" as a field label (placeholder), custom dimensions and email validation. This hidden tag
can now be reused multiple times simply by referencing $emailTag.
Using a variable: Below we are adding one instance of our
$emailTag to the document. Please note that when using variables you can use the
2nd option within the brackets to specify a custom field label an the 3rd option to specify a
custom field identifier.
[$emailTag|Custom Field Label|custom_identifier_1]
Find below a quick explanation of the custom options available when using variables:
| Order | Name | Description |
|---|---|---|
| 1 | Variable Name | Enter your preferred field type. See a list of available field types here ». [Example:
sig for Signature]
|
| 2 | Custom Field Label | Enter a custom field label (optional) |
| 3 | Custom Field Identifier | Enter a custom field identifier (optional) |
| 4 | Custom Field Value | Enter a custom field value (optional) |
| 5 | Custom Width | Enter a custom field width (optional) |
| 5 | Custom Height | Enter a custom field height (optional) |
Example Document
Below you will see a document containing a number of examples. You can download this PDF here »
