# Text tags

Type field instructions into a PDF or Word document, and eSignStack places the fields for you when you upload it.

Text tags are on by default. When you upload, leave **Turn text tags into fields** checked under **Upload options** (on an envelope's **Documents** step) or **Use text tags** (when uploading a template). eSignStack places a field at each supported tag, using the tag's printed width and height, and tells you how many it found. See [Fields](/docs/fields) for what each field type does.

Tags must fit on one line and remain selectable text. Scanned text is not detected. Malformed, split, or unsupported tags are skipped; the notice includes their count and the first example. No field names or recipient names are guessed.

## Adobe Acrobat Sign

Use `{{name_es_:signerN:type:directives}}`:

```text
{{*customer_es_:signer1:text}}
{{signature_es_:signer1:signature}}
{{initials_es_:signer2:initials}}
{{signed_es_:signer1:date}}
{{consent_es_:signer1:checkbox}}
{{department_es_:signer1:dropdown:options(Sales,Support)}}
{{color_es_:signer1:radio(Red)}}
{{color_es_:signer1:radio(Blue)}}
{{*license_es_:signer1:attachment}}
```

Supported types: text, signature, initials, signing date (`date`), checkbox, dropdown, radio, attachment, full name (`fullname`), email, company, and title. An omitted type means text. Radio options share a name and signer number, with a separate tag at each option's position.

- `*` before the name or `:required` makes a field required. Signatures and initials are required by default.
- `!` before the name, `:readonly`, or `:readOnly` makes an editable field sender-prefill only. Enter its value before sending.
- `optsignature` and `optinitials` make those fields optional. eSignStack also accepts `:optional` as a compatibility extension. Do not combine optional and required markers.
- `date`, `fullname`, and `email` are populated from the signing ceremony, not entered by the sender.
- The legacy dropdown form `:dropdown(options="Sales,Support")` is also accepted.

Defaults, display/export-value pairs, validation and formatting directives, conditions, shortened tags, and non-numbered roles are not supported. Tags requesting those behaviors are skipped, not partially applied.

## Dropbox Sign

Use `[type|req|signerN|Label|UniqueID]`, or `noreq` for optional fields. Label and ID are optional:

```text
[sig|req|signer1]
[initial|req|signer1]
[text|noreq|signer2|Witness|witness]
[date|req|signer1]
[check|req|signer1|Consent|consent_id]
```

Supported types are `sig`, `initial`, `text`, `check`, `date`, and `date_signed`. `date` is a signer-entered date; `date_signed` is the automatic signing date. Trailing spaces before `]` can widen a field. Merge fields, variables, autofill, validation, linked-field directives, and checkbox-count rules are not supported.

## Recipient slots and templates

`signer1` means the first recipient in signing order, `signer2` the second, and so on. A missing recipient does not change the slot: the field stays unassigned until that position is filled. Slots in templates correspond to the ordered recipient roles. Review assignments before sending, particularly when the envelope includes approvers or people who need to acknowledge.

## Existing PDF form fields

Adobe-style AcroForm names containing `_es_:signerN[:type]` use the same explicit type and slot conventions. Native dropdowns and radio groups can use their existing PDF choices. A radio convention needs a native radio widget; an incompatible convention retains the original field type with a warning rather than inventing a group.

DocuSign names `DocusignSignHere` / `eSignSignHere`, `DocusignInitialHere`, `DocusignDateSigned`, `DocusignFullName`, `DocusignCompany`, and `DocusignTitle` set the field type. Add `Optional` to the signature or initials names, such as `DocusignSignHereOptional`, to make them optional. These names do not specify a recipient slot.

In the editor, a field placed from a tag shows **From tag**, and a field imported from a PDF form shows **From the form**.

## Word documents

Upload a `.docx` with ordinary, single-line tags. Word files are converted to PDF, and tags are found at their positions in the converted file. Font substitution or line wrapping can change a tag's width, so check the placed fields.

## API

Detection is on by default. Set `use_text_tags=false` when creating a file with `POST /api/v1/files` to leave its text unchanged. The same flag on `POST /api/v1/envelopes` opts out when creating an envelope from a previously prepared file. File inspection includes a `text_tags` count and warnings. See the [API reference](/docs/api).

## Covered, not redacted

Supported tag text is painted over on the signing copy and final PDF, using the surrounding background color sampled from the page. White is the fallback when background sampling is unavailable. Patterned backgrounds may not blend perfectly.

**This is visual covering, not redaction.** The original text remains extractable from the PDF, and the original upload is preserved. Do not put secrets inside tags.

## References

- [Adobe Acrobat Sign text tags](https://helpx.adobe.com/sign/using/text-tag.html)
- [Dropbox Sign text tags](https://developers.hellosign.com/docs/walkthroughs/text-tags)
- [DocuSign PDF field transformation](https://developers.docusign.com/docs/esign-rest-api/esign101/concepts/tabs/pdf-transform/)