Hidden Tags

Table of contents

Getting Started

Create Document: Fields

Bulk Sending

Bulk Sending Process

Hidden Tags

Embedded Signing

Embedded Requesting

OAuth 2.0

Webhooks

Libraries

Stay up to date

Twitter(@geteversign)

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_tags when 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.

White-on-White:

Since hidden tags should in fact be hidden on your document, they should be added in same color as the background of your document. In most cases, this is white-on-white.

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.

Skipping Options:

In order to skip an option, simply leave it empty without making any changes to the order of other options. A field with a field identifier but without a field label would look like this: [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

Embedded Signing