# Text tags: place signature fields from the PDF

> Write a tag into your document where a field should go, and SignWith puts the field there and hides the tag. No coordinates, no editor.

Source: https://signwith.co/docs/api/text-tags · Updated 2026-10-02

Text tags are the easiest way to place fields when your system generates the PDF, for example from a Word or HTML template. They work however the PDF reaches SignWith: [`POST /templates`](https://signwith.co/docs/api/templates#create-a-template-from-documents), the MCP `create_template` tool, uploading a new template in the app, or adding a document in the template editor.

## Syntax

```text
{{Field name;key=value;key=value}}
```

The first part is the field name, which you can also use as the key in `prefill`. After it come optional settings, separated by semicolons:

| Setting | What it does | Default |
| --- | --- | --- |
| `type` | `text`, `signature`, `initials`, `date`, `checkbox`, `number`, `phone`, `select`, `image`, `file` or `stamp` | `text` |
| `role` | Who fills the field, such as `Client`. A new role is added to the template. | The template's first role |
| `required` | `false`, `no` or `0` makes the field optional | `true` |
| `options` | Choices for a `select` field, separated by commas or `\|` | |
| `width`, `height` | Size in PDF points (72 points to an inch) | The tag's own size, with a minimum per type |

If the first part is a field type on its own, it's the type, and the field is named after it: `{{signature;role=Provider}}` is a signature field called "Signature".

Some short forms work too: `sig` means `signature`, `initial` means `initials`, `check` means `checkbox`, and `radio` or `multiple` mean `select`. An unknown type becomes a text field.

## Examples

| Tag | Field |
| --- | --- |
| `{{Client signature;type=signature;role=Client}}` | The client's signature |
| `{{Date signed;type=date;role=Client;required=false}}` | An optional date for the client |
| `{{Plan;type=select;options=Basic,Pro;role=Client}}` | A choice between Basic and Pro |
| `{{signature;role=Provider}}` | The provider's signature, named "Signature" |
| `{{initials;role=Client}}` on every page | One initials field, with an area on each page |

## Where fields land

- **Position.** The field starts at the tag's left edge and sits on the tag's baseline. Taller fields, such as signatures, grow upward, so a tag on a signature line puts the signature on the line.
- **Size.** Without `width` and `height`, a field takes the tag's size, but never less than a minimum: 160 × 36 points for signatures, 60 × 30 for initials, 12 × 12 for checkboxes, 120 × 60 for images and stamps, 120 × 20 for files, and 80 × 16 for everything else.
- **Repeats.** The same name, type and role in several places is one field with several areas, which is how "initial every page" works.
- **Wrapping.** A tag that wraps onto a second line in a narrow column still works; the line break counts as a space.

## Roles

If every tag names a role and the PDF has no fillable form fields, the template gets exactly those roles, in the order they first appear. Tags without a role go to the template's first role. A template has at most 10 roles; tags naming more fall back to the first role.

Signers are matched to roles when you send, so name the roles the way you'll fill them in [`POST /signature_requests`](https://signwith.co/docs/api/signature-requests#send-a-signature-request).

## Combining with other fields

Tags work together with fillable PDF form fields, which SignWith detects automatically, and with fields you pass in `fields` when you create the template. Use whichever fits each part of the document.

## Hiding the tag text

SignWith covers each tag with white so signers don't see it. For the cleanest result:

- Keep each tag on a line of its own, or colour the tag text white in your source document.
- Leave a little space between lines. In very tightly set text, the white cover can slightly clip neighbouring letters.

## With AI assistants

Assistants connected through the [SignWith MCP server](https://signwith.co/docs/mcp) know the tag syntax. When Claude or ChatGPT writes or edits a document for you, it puts tags where the fields go and then creates the template, so the signature lines land in the right place. For a PDF with no tags or form fields, it gives you the template's `edit_url` to place fields in the SignWith editor instead of guessing positions.

## Limits

- Text tags only work in PDFs, not images, because images have no text layer.
- Tags are read from the page's visible area (its crop box), so text outside it is ignored.
- Rotated pages are skipped: tags on them stay in the document as plain text and don't become fields.

## Try it

Add `{{Client signature;type=signature;role=Client}}` to a PDF, then create a template from it:

cURL:

```bash
curl -X POST https://app.signwith.co/api/v1/templates \
  -H "Authorization: Bearer $SIGNWITH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Residential lease",
  "external_id": "lease-v3",
  "folder": "Leasing",
  "documents": [
    {
      "name": "Lease agreement",
      "file": "https://files.acme.co/templates/lease-v3.pdf"
    }
  ]
}'
```

Node:

```javascript
const response = await fetch('https://app.signwith.co/api/v1/templates', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SIGNWITH_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    name: 'Residential lease',
    external_id: 'lease-v3',
    folder: 'Leasing',
    documents: [
      {
        name: 'Lease agreement',
        file: 'https://files.acme.co/templates/lease-v3.pdf',
      },
    ],
  }),
})

console.log(response.status, await response.json())
```

Python:

```python
import os
import uuid

import requests

response = requests.post(
    "https://app.signwith.co/api/v1/templates",
    headers={
        "Authorization": f"Bearer {os.environ['SIGNWITH_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "name": "Residential lease",
        "external_id": "lease-v3",
        "folder": "Leasing",
        "documents": [
            {
                "name": "Lease agreement",
                "file": "https://files.acme.co/templates/lease-v3.pdf",
            },
        ],
    },
)

print(response.status_code, response.json())
```

The response lists the fields SignWith found. Check them with [`GET /templates/{id}`](https://signwith.co/docs/api/templates#get-a-template), then [send it for signature](https://signwith.co/docs/api/quickstart).