Text tags let you define signing fields inside the PDF itself. When you send a signature request via the API, Lumin parses the document for any tags that match the expected syntax and converts them into interactive form fields for your signers.
This approach is ideal when you generate documents programmatically and want to define field placement without using the Lumin Sign editor.
How to enable text tags
Include "use_text_tags": true in your POST /signature_request/send request body. If you omit this field, it defaults to false and tags are ignored.
{
"use_text_tags": true,
"file_url": "https://example.com/my-document.pdf",
...
}
Syntax
A text tag is a string placed directly in the body of your PDF document, wrapped in square brackets with identifiers separated by pipe characters:
[type|req|signerN|Label|UniqueId]
[sig|req|signer1|Sign here|sig_001]
[initial|noreq|signer2|Initials|init_002]
[text|req|signer1|Full name|name_003]
[date|noreq|signer1|Date signed|date_004]
Identifiers
| Identifier | Accepted values | Required | Description |
|---|
| Field type | sig, initial, text, date | Yes | The type of interactive form field to render |
| Requirement | req, noreq | Yes | Whether the signer must complete this field before submitting |
| Assigner | signer1, signer2, signer3, … | Yes | Maps to the signer at that index in the signers array of your API request |
| Label | Any text | No | Placeholder text shown inside the field. Currently overridden by Lumin Sign’s default placeholders |
| Unique ID | Any text | No | A name you assign to the field for your own reference |
Field types
| Type | Renders as |
|---|
sig | Signature field |
initial | Initials field |
text | Single-line text input |
date | Date picker |
Important notes
Tags are detected by reading actual text in the PDF — not by OCR. If your tag
text is embedded in an image, it will not be detected.
-
PDF format is required. Form fields may be placed incorrectly if the document is not a PDF.
-
Tags remain in the rendered document. To hide a tag, set its text color to match the document background color.
-
No whitespace allowed inside tags. If you need extra horizontal space for layout, use underscores (
_) after the last identifier instead:
[sig|req|signer1|____________________]
- Height is fixed to accommodate a 12pt font.
- Width equals the rendered length of the full tag string (including brackets). Add underscores after the last identifier to make a field wider.
[sig|req|signer1] ← narrow field
[sig|req|signer1|____________] ← wider field
Validation behavior
Lumin does not validate tag syntax at the time of the API request. Instead:
- A tag missing any required identifier (type, requirement, assigner) is silently ignored — it is not converted into a form field and no error is returned.
- A tag with an invalid value (e.g., wrong requirement type, or a signer index that does not exist in your
signers array) triggers the signature_request_invalid webhook event after submission.
You will not receive an immediate API error for malformed tags. Subscribe to
the signature_request_invalid webhook event to catch these issues in your
integration. See the Webhooks guide for
setup instructions. Validation errors
When a text tag is malformed or references invalid data, the signature_request_invalid webhook event is fired with an error_code and error_message. Below are the possible validation errors:
| Error type | Meaning | Error message |
|---|
| Missing field type | Parser cannot infer the field type from the tag text. | can't detect field type from this text tag |
| Undefined requirement type | The requirement token is not a supported value (e.g. a typo of req). No form field is created. | the requirement type <value> is undefined. Form field could not be created from this text tag |
| Wrong requirement type | Incompatible pairing — e.g. noreq used on a sig, initial, or date field which must be required. | the requirement type noreq can't be used for signature/initial/date field |
| Missing requirement type | No recognizable requirement segment in the tag. | can't detect requirement type from this text tag |
| Undefined assigner | Signer reference (e.g. signer3) does not match any signer on the request. | signer3 is undefined. Form field could not be assigned to this assigner |
| Assigner index not numeric | Signer slot is not parseable as a number (e.g. signerOne instead of signer1). | Can't detect assigner index from this text tag |
| Duplicated definition tag | The unique ID collides with another tag (e.g. checkbox group definitions must be unique). | definition tag must be unique for each check box group |
Example webhook payload
When a text tag error is detected, the signature_request_invalid webhook event is sent:
{
"event": {
"event_time": 1776408567122,
"event_type": "signature_request_invalid",
"event_metadata": {}
},
"signature_request": {
"signature_request_id": "69e1d7f623ab47de200c8903",
"error_code": "invalid_request",
"error_message": "The requirement type noreq can't be used for signature/initial/date field"
}
}
Example: complete request with text tags
curl -X POST https://api.luminpdf.com/v1/signature_request/send \
-H "Authorization: API-key <your-key>" \
-H "Content-Type: application/json" \
-d '{
"title": "Tenant Agreement",
"file_url": "https://example.com/tenant-agreement.pdf",
"use_text_tags": true,
"expires_at": 1927510980694,
"signing_type": "SAME_TIME",
"signers": [
{ "email_address": "[email protected]", "name": "Alex Tenant" }
]
}'
file_url might contain:
Please sign below:
[sig|req|signer1|Signature|sig_001]
Date:
[date|req|signer1|Date|date_001]
Full name:
[text|req|signer1|Full name|name_001]
signer1 resolves to [email protected] because that signer is at index 1 in the signers array. 
