--- title: "Text tags" url: "https://docs.signnow.com/docs/text-tags" type: "page" section: "Documentation" slug: "text-tags" --- # Text tags ## About text tags Text tags allow adding fields to a document before the document is uploaded to SignNow. Text tags can be added to a document in two ways: - **Simple text tags**: all the field details are added to a document. - **Complex text tags**: fields are added to a document, and their properties are sent in a request body. To upload a document with simple or complex text tags, use [Upload document with tags](/docs/document/operations/upload-document-with-text-tags). Only .doc, .docx, and .pdf formats are supported. ## Simple text tags Simple text tags are combinations of keys and values that define field properties and must be correctly ordered. A simple text tag is added to a document in the place where a field should appear.
Simple text tags video tutorial Note: The design shown in the video is outdated, but the flow is still accurate. You can go ahead and follow the steps as demonstrated. [Simple text tags video tutorial](https://youtu.be/iopDT5_4-Co?si=xZShbVlslPNkMi5f)
To upload a document with simple text tags, use [Upload document with tags](/docs/document/operations/upload-document-with-text-tags). Only .doc, .docx, and .pdf formats are supported. ```bash curl --request POST \ --url https://api.signnow.com/document/fieldextract \ --header 'Authorization: Bearer {{access_token}}' \ --header 'file=@/path/to/FILE_NAME.pdf' ``` ```json { "id":"519f97b02da37a411d624e758c631cb64c9d9eb6" } ``` > The format of tags is positional, so their properties must be correctly ordered. The order of simple text tags is the following: > > **{Type of the field}{Required}{Role}**{Label}{Prefilled text}{Text horizontal alignment}{Text vertical alignment}{Lock signing date}{Height multiplier}{Dropdown}{Width}{Height}{Validator ID value}{Radio name}{Radio value}{Checked}{Link}{Hyperlink hint} > > The properties in bold are required. **Simple text tag example**
A required signature field for the role 'CEO': width '100', and height '15' {{t:s;r:y;o:"CEO";w:100;h:15;}}
The tag can have multiple lines with page breaks before or after a colon or semicolon. > Both single-brace `{...}` and double-brace `{{...}}` syntax are supported. For example, `{t:s;r:y;o:"CEO";w:100;h:15;}` and `{{t:s;r:y;o:"CEO";w:100;h:15;}}` are equivalent. > Make sure to use double quotes (") inside the tag syntax. ### Simple text tag parameters | Property | Key | Values | When to use | | ------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | Field type | `t` | `s` - signature
`i` - initials
`t` - text
`d` - dropdown
`c` - checkbox
`f` - attachment
`r` - radio button
`h` - hyperlink
`cc` - text field for cc email
`e` - instant invite. [See Invite text tags](/docs/text-tags#invite-text-tags)

Example: `t:s;` | Always | | Required | `r` | `y` - required
`n` - optional

Example: `r:y;` | Always | | Role | `o` | String with a role name. Allowed symbols: letters, digits, and `',.`.

Example: `o:"CEO";` | Always | | Label | `l` | String with a field label. Allowed symbols: letters, digits, and `',./\$`.

Example: `l:"Signature";` | Only with text, dropdown, and file fields | | Prefilled text | `p` | String with a prefilled text. Allowed symbols: letters, digits, and `',./\`.

Example: `p:"John Doe";` | Only with text fields | | Text horizontal alignment | `al` | `l` - left
`c` - center
`r` - right

Example: `al:c;` | Only with text fields | | Text vertical alignment | `vl` | `t` - top
`m` - middle
`b` - bottom

Example: `vl:b;` | Only with text fields | | Lock signing date | `lsd` | Whether to set the current date of signing by default.
`y` - set the default date
`n` - no restrictions on the date

Example: `lsd:y;` | Only with text fields | | Height multiplier | `i` | If height = 20 and i = 3, the SignNow field is 60 points high.

Example: `i:3;` | Only with text fields | | Dropdown | `dd` | Dropdown options separated by commas. Allowed symbols: letters, digits, and `',.`.

Example: `dd:"Option1, Option2, Option3";` | Only with dropdown fields | | Width | `w` | Field width in pixels.

Example: `w:12;` | Any field type. If not indicated, the field is of the tag width. | | Height | `h` | Field height in pixels.

Example: `h:12;` | Any field type. If not indicated, the field is of the tag height. | | Validator ID | `v` | Use to validate filled data against certain formats. For possible values, see [Data validators](/docs/fields#data-validators).

Example: `v:"13435fa6c2a17f83177fcbb5c4a9376ce85befeb";` | Only with text fields | | Name of the radio button group | `rn` | String with a name for a group of radio buttons. Allowed symbols: letters, digits, and `',.-`.

Example: `rn:"Select your department";` | Only with radio buttons | | Radio button value | `rv` | String with the value of a radio button. To create a group of radio buttons, create a tag for each radio button with the same group name and different values. For more information, see [Radio buttons]().

Allowed symbols: letters, digits, and `',.-$`.

Example: `rv:"HR";` | Only with radio buttons | | Checked | `checked` | `1` - checked
Any other number - unchecked

Example: `checked: 1;` | With radio buttons and checkboxes | | Link | `lk` | Hyperlink.

Example: `lk:"https://signnow.com";`

To use a hyperlink text tag, a corresponding organization setting must be enabled. To update the settings, contact SignNow [support](https://support.signnow.com/). | Only with hyperlinks | | Hyperlink hint | `ht` | String with a hyperlink hint that appears in the field. Allowed symbols: letters, digits, and `,.$`.

Example: `lk:"https://yourlink.com";` | Only with hyperlinks | | CC email | `cc` | Add a CC recipient of the document.

Example: `{{t:cc;e:"j.doe@email.com";}}` | Only with `cc` fields | ### Radio buttons Radio buttons are created using the following tags: - `rn` - a name of the group of radio buttons. Several radio buttons related to one question comprise a radio button group. To add a radio button group, add several text tags with the same `rn`. - `rv` - a radio button value. Create a separate text tag for each value. - `checked` - determines whether the button is checked by default. Possible values: 0 - unchecked, 1 - checked. Example: `{{t:r;r:y;o:"Customer";rn:"Select a color";rv:"Red";}}` `{{t:r;r:y;o:"Customer";rn:"Select a color";rv:"Green";}}` `{{t:r;r:y;o:"Customer";rn:"Select a color";rv:"Blue";}}` > Allowed symbols for `rn`: letters, digits, and `',.-`.
> Allowed symbols for `rv`: letters, digits, and `',.-$`. ## Invite text tags Use invite text tags to send an invite to sign immediately after uploading a document. This way, you won't need to send a separate `POST /document/invite` request. To use an invite tag: 1. Add one or more simple text tags to your document to create fields. 2. Add a tag with the following structure: `{{t:e;o:"Role1";e:"signer@mail.com";}}` to your document. **Invite tag for a document with two signatures** > `{{t:s;r:y;o:"Manager";}}` > `{{t:s;r:y;o:"Client";}}` > > `{{t:e;o:"Manager";e:"";order:1;}}` > `{{t:e;o:"Client";e:"";order:2;}}` `order` indicates signing order and is optional. ## Complex text tags Complex text tags have two parts: tag names in a document and an array of tag parameters in the request body. To upload a document with complex text tags, add the tag names in double curly braces to the document. Then, send a request to [`POST /document/fieldextract`](/docs/document/operations/upload-document-with-text-tags) with an array of tag parameters in the request body. Only .doc, .docx, and .pdf formats are supported. > The following syntax is supported for wrapping tag names in the document: `{{tagName}}`, `{tagName}`, `[[tagName]]`, and `[tagName]`.
Complex text tags video tutorial Note: The design shown in the video is outdated, but the flow is still accurate. You can go ahead and follow the steps as demonstrated. [Complex text tags video tutorial](https://www.youtube.com/watch?v=V0YWL2T8F-o)
### Complex tag parameters - `tag_name` (required): a tag name used in the document. - `type` (required): a field type. Possible values: - `text` - `signature` - `initials` - `checkbox` - `attachment` - `hyperlink` - `radio button` - `enumeration` (a dropdown menu) - `role` (required): a role the field is assigned to. - `required` (required): if true, the field is mandatory. - `prefilled_text`: editable text that appears in the field when the signer opens the document. - `label`: a hint in the field, for example, first_name. A value entered in the first field automatically appears in other fields with the same label, if any. If a field has prefilled text, the label appears when a signer hovers over the field. - `validator_id` (optional): format validation for the field. For possible values, see [Data validators](/docs/fields#data-validators). - `width`: field width in pixels. - `height`: field height in pixels. - `lock_to_sign_date`: a boolean. If `true`, the date field is automatically pre-filled with the signing (completion) date. Defaults to `false`. - `enumeration_options`: an array of dropdown options. - `custom_defined_option`: if true, allows a signer to enter their option in a dropdown. - `radio`: an array of radio buttons. - `value`: radio button value. - `checked`: set to `1` to check the checkbox or radio button; set to `0` to leave it unchecked. If not specified, the field is unchecked. - `x-offset`: a number that allows radio buttons to be aligned horizontally. - `y-offset`: a number that allows radio buttons to be aligned vertically. - `name`: for radio buttons, sets the group name. For hyperlinks, sets the name of the field. - `hint`: a hyperlink hint that appears in the field. > To use a hyperlink text tag, a corresponding organization setting must be enabled. To update the settings, contact SignNow [support](https://support.signnow.com/). ### Complex tag examples
TagExample
Text tag ```json { "tag_name": "EmployeeName", "role": "Employee", "label": "Your name", "required": true, "type": "text", "width": 100, "height": 20 } ```
Text tag with date validation ```json { "tag_name": "BirthDate", "role": "Role1", "label": "Your date of birth", "required": true, "type": "text", "height": 15, "width": 100, "validator_id": "13435fa6c2a17f83177fcbb5c4a9376ce85befeb" } ```
Initials tag ```json { "tag_name": "ClientInitials", "role": "Client", "required": true, "type": "initials", "height": 15, "width": 40 } ```
Signature tag ```json { "tag_name": "Signature", "role": "Client", "required": true, "type": "signature", "height": 15, "width": 200 } ```
Dropdown tag ```json { "tag_name": "Citizenship", "role": "Client", "label": "Your citizenship", "required": true, "type": "enumeration", "height": 15, "width": 100, "custom_defined_option": false, "enumeration_options": [ "US", "Non-US" ] } ```
Attachment tag ```json { "tag_name": "Photo", "role": "Client", "label": "Your photo", "required": true, "type": "attachment", "width": 100, "height": 20 } ```
Checkbox tag ```json { "tag_name": "ConsentCheckbox", "role": "Client", "required": true, "type": "checkbox", "height": 12, "width": 12, "checked": 1 } ```
Radio button tag ```json { "tag_name": "Citizenship", "role": "Employee", "required": true, "x": 36, "y": 246, "width": 340, "height": 13, "radio": [ { "x": 36, "y": 246, "width": 13, "height": 13, "checked": 0, "value": "Yes", "x-offset": 0, "y-offset": 0 }, { "x": 36, "y": 246, "width": 13, "height": 13, "checked": 1, "value": "No", "x-offset": 0, "y-offset": 14 } ], "name": "Citizenship", "type": "radiobutton" } ```
Hyperlink tag.

A corresponding organization setting must be enabled to use a hyperlink text tag. To update the settings, contact SignNow support.		 ```json { "tag_name": "URL", "role": "Client", "type": "hyperlink", "name": "hyperlink_unique_id", "required": true, "width": 118, "height": 33, "link": "https://google.com", "label": "Website link", "hint": "https://yourwebsite.com" } ```
## Send an invite to sign with complex text tags ### Step 1. Create a document Create a document with tag names. Let's create a document with three tags: ``` Name: {{employee name}} Date {{date}} Signature: {{signature}} ``` ### Step 2. Create an array of tags Create an array of tags for the request body. Use the tag names specified in the document. ```json [ { "tag_name": "employee name", "role": "employee", "label": "name", "required": true, "type": "text", "width": 100, "height": 15 }, { "tag_name": "date", "role": "employee", "label": "date", "required": true, "type": "text", "width": 100, "height": 15, "validator_id": "059b068ef8ee5cc27e09ba79af58f9e805b7c2b3" }, { "tag_name": "signature", "role": "employee", "label": "signature", "required": true, "type": "signature", "width": 100, "height": 30 } ] ``` ### Step 3. Upload a document with tags Send a request with your document and array of tags to [`POST /document/fieldextract`](/docs/document/operations/upload-document-with-text-tags). ```bash curl --request POST \ --url https://api.signnow.com/document/fieldextract \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{access_token}}' \ --header 'Content-Type: multipart/form-data' \ --form file=@/path/to/your/file.pdf \ --form 'Tags="[ { \"tag_name\": \"name\", \"role\": \"employee\", \"label\": \"name\", \"required\": true, \"type\": \"text\", \"width\": 100, \"height\": 15 }, { \"tag_name\": \"date\", \"role\": \"employee\", \"label\": \"date\", \"required\": true, \"type\": \"text\", \"width\": 100, \"height\": 15, \"validator_id\": \"059b068ef8ee5cc27e09ba79af58f9e805b7c2b3\" }, { \"tag_name\": \"signature\", \"role\": \"employee\", \"label\": \"signature\", \"required\": true, \"type\": \"signature\", \"width\": 100, \"height\": 30 } ]"' ``` ## Try out in Postman [Access](https://www.postman.com/signnow-api/signnow-public-collection/request/ppnonf2/upload-document-with-tags?action=share\&source=copy-link\&creator=29919567\&ctx=documentation) this feature in Postman, and optimize your workflows with automatic field generation. --- *Full page: https://docs.signnow.com/docs/text-tags*