Text Tags

Text Tags - specific combinations of symbols and letters in a document that represent fillable fields.

Text Tags are always typed in the document first. Some of them require additional information in the body of API requests. After the document with Text Tags is uploaded to SignNow, Text Tags convert to fillable fields. Requests containing Text Tags have to be directed to the POST /document/fieldexract.

signNow supports three kinds of Text Tags: Simple Text Tags, Complex Text Tags, and Invite Text Tags.

Simple Text Tags

Simple Text Tags are added to the document only. You don’t have to specify any field properties in an API request. Upload the document using POST /document/fieldextract, add only the name of the document in the request:

curl -X POST \
  https://api-eval.signnow.com/document/fieldextract \
  -H 'Authorization: Bearer {{access_token}}' \
  -F 'file=@/path/to/FILE_NAME.pdf'

When you add a Simple Text Tag to a document, you should combine keys in curly braces in a specific order. Every key stands for the property of a field.

Table 1. The Order of Field Properties in a Text Tag

KEY What does it mean? Accepted format and values When do fields require this key?
t TYPE of the field s (for signature), i (for initials), t (for text), d (for dropdown), c (for checkboxes), f (for files) Specify it for every field
r REQUIRED y (for required), n (for optional) Specify it for every field
o ROLE "Signer 1" Specify it for every field
l LABEL label 1 Only for Text, Dropdown, and Attachment fields
dd DROPDOWN "option1, option2, option3, ...." Only for Text and Dropdown fields
f FILE "doc1.pdf" Specify for file attachments
w WIDTH "w: <num>" Specify it for every field
h HEIGHT "h: <num>" Specify it for every field
v VALIDATOR_ID "v:<id>" Only for Text Field

Simple Text Tag formula looks like this:

"{{t:[s/i/t/d/c];r:[y/n];o:"Role";l:"date";w:width;l:length;v:"validator_id";}}

Table 2. Simple Text Tag Examples

Task Simple Text Tag
Create a required signature field for the role ‘CEO’: width ‘100’, and height ‘15’ {{t:s;r:y;o:“CEO”;w:100;h:15;}}
Validate a US phone number in an optional text field for the role ‘CFO’, label ‘phone’, width ‘100’, height ‘15’, and validator_ID ‘13cc1d661da456d27b249b73056ed4d1f2e72d8e’ {{t:t;r:n;o:“CFO”;l:“phone”;w:100;h:15;v:“13cc1d661da456d27b249b73056ed4d1f2e72d8e”;}}
Create a required dropdown field for the role ‘Employee’, labeled ‘Year’, with dropdown options ‘2017, 2018, 2019’ {{t:d;r:y;o:“Employee”;l:“Year”;dd:“2017,2018,2019”;}}
Create a required Attachment field for the role ‘Employee’: width ‘100’, and height ‘15’ {{t:s;r:y;o:“Employee”;f:y;w:100;h:15;}}

Complex Text Tags

Complex Text Tags are also added to a document first but field properties are then specified in the body of the request.

When you add a Complex Text Tag to a document, you only put a tag name in double curly braces, like so {{tag_name}}.

Then, make a request to POST /document/fieldextract. In your request body, specify parameters of the field you saved place for with your {{tag_name}}.

Parameters for a Complex Text Tag:

“tag_name” - duplicates the name without curly braces, e.g. tag_name

“role” - which role the field is assigned to, e.g. Signer_1

“label” (optional) - hint for the signer inside a fillable field about the field type, e.g. first_name or text_1; once the field is filled in, the value automatically appears in all the fields with the same label

“required” - whether the field is mandatory to fill in, e.g. true/false

“type” - could be “text”, “signature”, “initials”, “checkbox”, “radiobutton”, or “enumeration” (stands for a dropdown menu)

“prefilled_text” (optional) - editable text that appears in the field when the signer opens the document, e.g. Lucy

“validator_id” (optional) - data validation format for a field.

Check for available formats in Data Validators.

“width” - how many pixels wide the field is

“height” - how many pixels high the field is

Popular Field Sizes

Field Type Purpose Width & Height, Font Size 10 Width & Height, Font Size 12 Width & Height, Font Size 10
Text field name
Text field email address
Text field US phone number
Signature field for signing a document

Table 3. Complex Text Tag Examples

Tag Example
Text Tag {
tag_name:‘employee’,
role:‘employee’,
label:‘Label1’,
required:true,
type:‘text’,
width:100,
height:20
},
Date Validator Tag {
“tag_name”:“DateValidatorTagExample”,
“role”:“Role1”,
“label”:“Date of Birth”,
“required”:true,
“type”:“text”,
“height”:15,
“width”:100,
“validator_id”:“13435fa6c2a17f83177fcbb5c4a9376ce85befeb”
},
Initials Tag {
“tag_name”:“InitialsTagExample”,
“role”:“CLIENT”,
“required”:true,
“type”:“initials”,
“height”:15,
“width”:40
},
Signature Tag {
“tag_name”:“SignatureTagExample”,
“role”:“CLIENT”,
“required”:true,
“type”:“signature”,
“height”:15,
“width”:200
},
Dropdown Tag {
“tag_name”:“DropDownTagExample”,
“role”:“Role1”,
“label”:“Options”,
“required”:true,
“type”:“enumeration”,
“height”:15,
“width”:100,
“custom_defined_option”:false,
“enumeration_options”:[“All”,“None”]
},
Attachment Tag {
tag_name:‘AttachmentTagExample’,
role:‘Role2’,
label:‘Label2’,
required:true,
type:‘attachment’,
width:100,
height:20
},
Checkbox Tag {
“tag_name”:“CheckboxTagExample”,
“role”:“CLIENT”,
“required”:true,
“type”:“checkbox”,
“height”:12,
“width”:12,
}

Invite Text Tags

Invite Text Tags are added to the document only, no additional configuration in the request body. Among field properties, you can specify signer’s email address. So, when you upload a document to POST /document/fieldextract, it’s automatically sent for signautre to that address. There’s no need to make a separate request to POST /document/invite.

Table 4. Invite Text Tag Examples

Invite Text Tags
{{t:e;o:“Role1”;e:“siri@mailinator.com”;}}
{{t:e;o:“Client”;e:“siri2@mailinator.com”;}}
{{t:e;o:“Manager”;e:“siri3@mailinator.com”;}}

To specify a signing order:
{{t:e;o:“Role1”;e:“siri@mailinator.com”;order:1;}}
{{t:e;o:“Client”;e:“siri2@mailinator.com”;order:2;}}
{{t:e;o:“Manager”;e:“siri3@mailinator.com”;order:3;}}