> ## Documentation Index
> Fetch the complete documentation index at: https://docs.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating templates using tags

Box Sign enables you to create templates so you can automatically add the same fields and format to standardize requests for signature. With templates, you don't need to repetitively add the same fields and configure the same signature request properties for each request that is sent out for signature or approval. Creating, configuring, and testing a template takes a few minutes, but when properly deployed, it streamlines the signature request experience for senders.

[Video: Creating templates using tags in Box Sign](https://players.brightcove.net/6291496955001/VkP5RdZVu_default/index.html?videoId=6370352946112)

Box Sign offers two ways to create a template:

* [Templates within Box Sign](https://docs.box.com/en/box-sign/templates/creating-using-and-sharing-templates.md)
* Templates with tags embedded in base files

## About template tags

With template tags, you can embed custom tags or text in the base files of a signature request or reusable template. Add the tags in an editor such as Microsoft Word, Google Docs, PowerPoint, or Adobe Acrobat. Box Sign automatically recognizes the embedded tags and converts them into fillable and signable fields. You can use template tags through the Box Sign API, the Salesforce integration (through the Box for Salesforce managed package), and the document preparation view in the Box Sign web app.

## Creating a template with tags

To [create a template](https://docs.box.com/en/box-sign/templates/creating-using-and-sharing-templates.md) with tags:

1. Open your document in your preferred text editor (for example, Microsoft Word, Google Docs, PowerPoint, or any PDF reader).
2. Determine how many people will sign the document and identify which recipient number each person will be assigned. This helps you plan which tags to use for each signer. See [Recipient numbering](#recipient-numbering) for details on how recipient numbers work.
3. Add special tags to each corresponding input field where you want signers to fill out information or sign. See the [Available field tags](#available-field-tags) section for details.
4. Adjust the display size:
   * Set the font size for the tag.
   * Add spaces before the closing `]]` brackets. Each space increases the field width. For example: `[[s1|0       ]]`.
5. Change the font color of the tags to white to hide them from view in the final document.
6. Save and upload your document to Box Sign.

### Best practices

* Keep distance between tags, preferably by using line breaks or proper line height.
* Place tags in a table format or use a different text style than the body of the document for better positioning.
* Test your template tags before you send the document to signers.

## Tag syntax

All template tags follow this basic format:

`[[field_type|recipient_number|optional_parameters]]`

Where:

* `field_type` is the type of field (signature, text, date, and so on)
* `recipient_number` identifies which recipient the field is assigned to
* `optional_parameters` add additional settings like validation or requirements

### Recipient numbering

Recipient numbers link each tag to a recipient:

* `0` is reserved for the sender. Start numbering with `0` if the sender signs the document.
* If the sender doesn't sign, start numbering with `1`. Your document must not contain `|0` tags.
* `1`, `2`, `3`, and so on refer to recipients in the order you add them to the signature request.
* Recipient numbers in tags correspond to the order you add recipients, **not** the signing order.

> [!WARNING]
>
> Assign template tags only to recipients with the **Signer** role. Don't assign tags to recipients with other roles, such as **Approver** or **Get a Copy**.

> [!NOTE]
>
> If you send signature requests with template tags through the Box API, see [Signing structured docs](https://developer.box.com/guides/box-sign/document-types/structured#recipient-numbering) in the Box developer documentation for API-specific numbering rules.

**Example: The sender signs**

You create a document with these tags and upload it for signature:

* `[[s|0]]` for signature
* `[[s|1]]` for signature
* `[[s|2]]` for signature

As the sender, you are assigned to the `[[s|0]]` tags. The first and second recipients you add are assigned to the `[[s|1]]` and `[[s|2]]` tags.

> [!WARNING]
>
> You can't set the signing order with template tags. Configure the signing order in the document preparation view.

**Example: Recipient order vs. signing order**

Let's say you create a document with these tags:

* `[[s|1]]` for signature
* `[[s|2]]` for signature
* `[[s|3]]` for signature

When you prepare the document for signing, you add recipients in this order:

1. [alice@example.com](mailto:alice@example.com) → automatically assigned to `[[s|1]]` tags
2. [bob@example.com](mailto:bob@example.com) → automatically assigned to `[[s|2]]` tags
3. [charlie@example.com](mailto:charlie@example.com) → automatically assigned to `[[s|3]]` tags

Now you configure the signing order:

* First to sign: [charlie@example.com](mailto:charlie@example.com) (but still assigned to `|3` tags)
* Second to sign: [alice@example.com](mailto:alice@example.com) (but still assigned to `|1` tags)
* Third to sign: [bob@example.com](mailto:bob@example.com) (but still assigned to `|2` tags)

**Result**: Charlie signs first and completes the `[[s|3]]` fields, then Alice signs and completes the `[[s|1]]` fields, and finally Bob signs and completes the `[[s|2]]` fields. The tag numbers stay tied to the order recipients were added, regardless of who signs first.

For more information and examples, see the [Working with multiple signers](#working-with-multiple-signers) section.

## Available field tags

The table below lists all available template tags for Box Sign templates.

| **Field type** | **Tag** |
| - | - |
| Text input\* | `[[t\|1]]` |
| Date signed | `[[d\|1]]` |
| Checkbox | `[[c\|1]]` |
| Signature | `[[s\|1]]` |
| Stamp | `[[st\|1]]` |
| Initials | `[[i\|1]]` |
| Name | `[[n\|1]]` |
| First name | `[[fn\|1]]` |
| Last name | `[[ln\|1]]` |
| Company | `[[co\|1]]` |
| Email | `[[e\|1]]` |
| Title | `[[ti\|1]]` |
| Attachment | `[[a\|1]]` |

\*Text input fields support additional validation tags to control data format. See [Text input validation tags](#text-input-validation-tags) for options including numbers, email, dates, ZIP codes, SSN, and custom patterns.

> [!NOTE]
>
> Box Sign doesn't support template tags for radio and dropdown fields.

> [!NOTE]
>
> Box Sign fills in **Date signed** `[[d|1]]` and **Email** `[[e|1]]` automatically, with the signing date and the signer's email address. Signers can't edit these fields.

## Text input validation tags

You can add validation to text input fields to control what type of data signers can enter. This helps ensure data accuracy and reduces errors. To learn more, see [Using input text validation](https://docs.box.com/en/box-sign/sending-a-document-for-signature/using-input-text-validation.md).

All text input validation tags are required by default.

Use `|r:0` to make them optional. See [Optional template tag parameters](#optional-template-tag-parameters) for more information and examples.

| Validation type | Tag |
| - | - |
| Numbers with period decimal separator | `[[t\|1\|v:np]]` |
| Numbers with comma decimal separator | `[[t\|1\|v:nc]]` |
| Email address | `[[t\|1\|v:e]]` |
| ISO standard date (YYYY-MM-DD) | `[[t\|1\|v:d1]]` |
| US date format (MM/DD/YYYY) | `[[t\|1\|v:d2]]` |
| European date format (DD/MM/YYYY) | `[[t\|1\|v:d3]]` |
| Alternative ISO format (YYYY/MM/DD) | `[[t\|1\|v:d4]]` |
| 5-digit ZIP code (#####) | `[[t\|1\|v:z5]]` |
| 7-digit ZIP code (###-####) | `[[t\|1\|v:z7]]` |
| 9-digit ZIP code (ZIP+4: #####-####) | `[[t\|1\|v:z9]]` |
| SSN (###-##-####) | `[[t\|1\|v:ssn]]` |

> [!WARNING]
>
> You can't combine text input validations with multi-line or read-only fields. If you add both `|ro:1` and a validation tag, the field defaults to a standard text input field without validation.

## Optional template tag parameters

Use optional parameters to make fields optional or required and to configure other field settings. Add parameters after the recipient number, separated by the pipe symbol `|`.

### Making a field optional or required

* Text input, checkboxes, and signature fields are required by default but can be made optional.
* Date and email fields are read-only and cannot be configured as optional or required.
* All other field types can be configured as optional or required.

**Syntax:**

* `|r:0` (optional)
* `|r:1` (required)

**Examples:**

* Optional text field: `[[t|1|r:0]]`
* Optional checkbox: `[[c|1|r:0]]`

### Adding field names or descriptions

Add a name to fields to provide context for signers. The name replaces the default placeholder text.

**Syntax:** `|n:field_name`

**Examples:**

* Text field with name: `[[t|1|n:Employee Name]]`
* Optional text field with name: `[[t|1|r:0|n:Middle Name]]`

### Pre-filled date and email fields

The date field is pre-filled with the signing date and the email field is pre-filled with the signer's email address.

### Making a field read-only

To lock the content from being modified by signers, senders can mark fields as read-only.

**Syntax:** `|ro:1`

**Supported fields:**

* Name
* Text Input
* Company
* Title
* Checkbox

**Examples:**

* Read-only text field: `[[t|1|ro:1]]`
* Read-only name field: `[[n|1|ro:1]]`

> [!WARNING]
>
> * Read-only field usage is not included in the signing log.
> * You can't combine text input validations with read-only fields. If you add both `|ro:1` and a validation tag, the field defaults to a standard text input field without validation.

### Adding an external identifier to a field

An external identifier gives a field a name you can refer to outside the document. Use it to:

* Prefill the field with data from another application. See [Prefilling fields through the API](#prefilling-fields-through-the-api).
* Export signer data to Excel. Each column in the export is labeled with the field's external identifier, so you can match what signers entered to your own records.

**Syntax:** `|id:identifier_name`

**Examples:**

* Text field with external identifier: `[[t|1|id:employee_id]]`
* Text field with validation and external identifier: `[[t|1|v:e|id:contact_email]]`

### Making a text field multi-line

By default, text fields are single-line. Add multi-line text entry to support longer responses like comments, descriptions, or addresses.

**Syntax:** `|m:1`

**Example:**

* Multi-line text field with name: `[[t|1|m:1|       id:contact_name]]`

## Prefilling fields through the API

If you send signature requests with the Box Sign API, you can fill in fields with different values for each request without editing the document.

**1. Add a tag with an ID to your document**

Add `|id:` to any tag you want to prefill. For example: `[[n|1|id:signer_name]]`

**2. Pass the value when you create the request**

In [`POST /sign_requests`](https://developer.box.com/reference/post-sign-requests/), add a `prefill_tags` entry. Set `document_tag_id` to the ID from step 1:

```json theme={null}
"prefill_tags": [
  { "document_tag_id": "signer_name", "text_value": "Jane Doe" }
]
```

When the signer opens the document, the **Name** field already shows *Jane Doe*.

## Working with multiple signers

### Example 1: Three signers, including the sender

If you are the sender and also need to sign:

* You are automatically assigned to `|0` tags (sender)
* First recipient gets `|1` tags
* Second recipient gets `|2` tags

**Example tags:**

* Your signature: `[[s|0]]`
* First signer's signature: `[[s|1]]`
* Second signer's signature: `[[s|2]]`

### Example 2: Two external signers only

If you are only the sender and do not need to sign:

* Do not use `|0` tags
* First recipient gets `|1` tags
* Second recipient gets `|2` tags

**Example tags:**

* First signer's signature: `[[s|1]]`
* Second signer's signature: `[[s|2]]`

### Mismatched signer and tag counts

**Fewer signers than tags:** If your document has tags for 3 signers but you add only 2, remove the unused template tags before you send the request.

**More signers than tags:** If you add more signers than you have tags, the extra signers can sign the document but aren't assigned any fields.

## Testing tags

To test template tags in Box Sign, use our [example documents](https://cloud.app.box.com/folder/138765865013?s=w9ixlxn9v5hejg84udidngc4y3pc8amr).