Text tags: place signature fields from the PDF

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, the MCP create_template tool, uploading a new template in the app, or adding a document in the template editor.

Syntax

{{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:

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

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.

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 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 -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"
    }
  ]
}'

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())

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}, then send it for signature.