Anchor Tags

Anchor tags let you position fields on a document by matching text that’s already in the file, instead of calculating x/y coordinates. You upload a PDF or DOCX containing marker text — commonly written as {{SIGN_HERE}} or similar, though any literal string works — pass an anchor_tags array in your create request, and Firma searches the document for each string and places a field wherever it finds a match.

Anchor tags only work with document-based creation — a request that includes document (base64) or document_id. They have no effect on template_id-based requests, because the anchor pipeline searches the uploaded document itself; a template’s fields are already positioned.

How matching works

anchor_string is matched as literal, case-insensitive-by-default substring text anywhere in the document — there’s no required delimiter syntax. {{...}} is just a convention that’s visually easy to spot in a document and unlikely to collide with real content; "Sign Here:" or "X_____" work exactly the same way. Each anchor tag supports:

Property	Default	Effect
`case_sensitive`	`false`	Whether the match respects letter case
`match_whole_word`	`true`	Requires non-word characters on both sides of the match
`occurrence`	`0`	`0` places a field at every match; `1`, `2`, etc. place a field only at that specific (1-indexed) occurrence
`ignore_if_not_present`	`false`	If the string isn’t found: `true` skips it silently, `false` fails the whole request
`x_offset` / `y_offset`	`0`	Shifts the placed field away from the matched text
`offset_units`	`percent`	`percent` of page dimensions, or `pixels` (PDF points, 72 DPI)

If the document has no extractable text at all — a scanned or image-based PDF, for example — no anchor can match. Set ignore_if_not_present: true if you want the request to continue anyway (the field is simply never placed); otherwise the request fails validation.

Default field sizes

If you don’t pass width/height on an anchor tag, the field is sized by type (as a percentage of the page):

Type	Width	Height
`signature`	25%	5%
`initial` / `initials`	10%	5%
`date`	20%	3%
`text` / `textarea` / `text_area` / `dropdown` / `url`	20%	3%
`checkbox` / `radio` / `radio_buttons`	3%	3%

stamp, file, approval_signature, approval_checkmark, and approval_date are all accepted as anchor type values by the server, but none of the five has a dedicated entry in this table — they silently fall back to the text default (20% × 3%). That’s usually too small for a stamp, file-upload box, or approval signature. Always pass explicit width/height when anchoring any of these types.

Hiding anchor text

Two independent, combinable options control what happens to the marker text and the area around it once a field is placed:

Option	Default	What it actually does
`remove_anchor_text`	`true`	Sets the anchor string’s glyphs to invisible PDF text rendering mode in place. The characters stay in the content stream (so surrounding text doesn’t reshuffle) but nothing is painted for them.
`add_white_background`	`false`	Draws an opaque white rectangle over the field’s entire bounding box, covering whatever document content sits underneath — not just the anchor string.

The public API reference currently describes remove_anchor_text as “drawing a white rectangle over” the anchor text. That description is stale — it matches an earlier implementation. The current behavior is invisible-text rendering (above), which leaves the glyphs in place rather than painting over them. Drawing a rectangle is what add_white_background does, and it acts on the whole field box, not the anchor string specifically.

Because remove_anchor_text only changes how the text is painted, it never removes the string from the document’s text layer:

A document processed with remove_anchor_text: true (the default) looks like the anchor text is gone in any PDF viewer — but running text extraction (pdftotext, a PDF library’s extractText, etc.) against the same file still returns the literal anchor string. This applies to the finished, signed document too, not just the version before signing. If you see a support report that anchor text is “still there” after processing, this is almost always the explanation: the text is invisible, not deleted, and the signature itself is a separate image layer placed at the anchor’s coordinates.

If you need the area behind a field visually blanked (for example, covering a printed placeholder box, not just the marker text inside it), combine both options — remove_anchor_text hides the marker glyphs, add_white_background covers the full field footprint.

DOCX documents

There’s no DOCX-specific anchor-matching logic. A DOCX upload is fully converted to PDF first, and the exact same text-search pipeline described above then runs against the resulting PDF:

The first bytes of the uploaded file are sniffed to detect DOCX (a ZIP-format file) vs. PDF.
A DOCX is converted via mammoth (DOCX → HTML) and then re-laid-out from scratch onto a fixed A4 page with fixed margins and a fixed font-size table — it is not a rasterization of the original Word pagination.
Anchor matching runs against this freshly-rendered PDF.

Because the DOCX→PDF conversion re-lays out content rather than preserving Word’s original layout, an anchor’s position after conversion depends on where the converter’s own renderer places that text — not on where it appeared in the original Word document. Page breaks and line wraps can shift. Images embedded in the DOCX are dropped entirely during conversion — the HTML parsing step only handles headings, paragraphs, lists, and tables, with no image support. If an anchor sits near an image in your source DOCX, expect the image to be missing from the signing document, not just repositioned.

Supported field types are identical to PDF anchors — by the time anchor matching runs, the file is already a PDF, so there’s no DOCX-specific restriction on which type values you can use.

PDF documents

For a native PDF upload, anchor matching runs directly against the document: positioned text is extracted page by page, adjacent text fragments on the same line are merged (so an anchor string split across separate PDF text-show operators by the original PDF producer is still found as one match), and each match is converted from PDF points into a page-relative percentage position for the new field.

Match position is approximated proportionally from character index within a text run, not from exact per-glyph kerning. On proportional (non-monospace) fonts, a placed field can be very slightly off-center relative to the exact anchor text. This is rarely visible at normal field sizes, but worth knowing if you need sub-pixel placement accuracy.

PDF vs. DOCX at a glance

	PDF	DOCX
Original layout preserved	Yes — matching runs on the exact uploaded file	No — the file is reflowed onto a fixed A4 layout before matching runs
Images	Untouched by anchor processing	Dropped during DOCX→PDF conversion
Matching pipeline	Runs directly	Runs against the converted PDF (identical logic)

Complete example

This request creates and sends a document with three anchor-placed fields: a signature, a date defaulting to the day of signing, and a read-only text field pulling from a fixed value.

curl -X POST "https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employment Contract",
    "document_id": "c251c2c0-a184-4f8c-8e65-be433e6a714a",
    "recipients": [
      {
        "first_name": "Alice",
        "last_name": "Johnson",
        "email": "alice@example.com",
        "designation": "Signer"
      }
    ],
    "anchor_tags": [
      {
        "anchor_string": "{{SIGN_HERE}}",
        "type": "signature",
        "recipient_id": "temp_1"
      },
      {
        "anchor_string": "{{DATE}}",
        "type": "date",
        "recipient_id": "temp_1",
        "date_signing_default": true
      },
      {
        "anchor_string": "{{CONTRACT_REF}}",
        "type": "text",
        "recipient_id": "temp_1",
        "read_only": true,
        "read_only_value": "Contract #12345"
      }
    ]
  }'

const response = await fetch(
  'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
  {
    method: 'POST',
    headers: {
      'Authorization': process.env.FIRMA_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Employment Contract',
      document_id: 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
      recipients: [
        {
          first_name: 'Alice',
          last_name: 'Johnson',
          email: 'alice@example.com',
          designation: 'Signer'
        }
      ],
      anchor_tags: [
        {
          anchor_string: '{{SIGN_HERE}}',
          type: 'signature',
          recipient_id: 'temp_1'
        },
        {
          anchor_string: '{{DATE}}',
          type: 'date',
          recipient_id: 'temp_1',
          date_signing_default: true
        },
        {
          anchor_string: '{{CONTRACT_REF}}',
          type: 'text',
          recipient_id: 'temp_1',
          read_only: true,
          read_only_value: 'Contract #12345'
        }
      ]
    })
  }
)

const result = await response.json()

import os
import requests

response = requests.post(
    'https://api.firma.dev/functions/v1/signing-request-api/signing-requests/create-and-send',
    headers={
        'Authorization': os.environ['FIRMA_API_KEY'],
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Employment Contract',
        'document_id': 'c251c2c0-a184-4f8c-8e65-be433e6a714a',
        'recipients': [
            {
                'first_name': 'Alice',
                'last_name': 'Johnson',
                'email': 'alice@example.com',
                'designation': 'Signer'
            }
        ],
        'anchor_tags': [
            {
                'anchor_string': '{{SIGN_HERE}}',
                'type': 'signature',
                'recipient_id': 'temp_1'
            },
            {
                'anchor_string': '{{DATE}}',
                'type': 'date',
                'recipient_id': 'temp_1',
                'date_signing_default': True
            },
            {
                'anchor_string': '{{CONTRACT_REF}}',
                'type': 'text',
                'recipient_id': 'temp_1',
                'read_only': True,
                'read_only_value': 'Contract #12345'
            }
        ]
    }
)

result = response.json()

recipient_id uses a temporary id (temp_1) here because the recipient is defined in the same request (document-based creation). Fields resolved from anchor tags are merged with any manually specified fields in the same request, and once created they’re ordinary field rows — the response doesn’t distinguish an anchor-placed field from a manually positioned one, and doesn’t expose which anchor string or occurrence produced it.

Gotchas

Removed anchor text is hidden, not deleted — plan for it showing up in extraction

As covered above, remove_anchor_text never deletes characters from the PDF; it only stops them from being painted. If your own compliance or redaction requirements mean a marker string can never appear in programmatic text extraction of the final signed document, anchor tags as implemented today can’t satisfy that — choose anchor strings you’re comfortable having permanently present (invisibly) in the file, or don’t rely on this API to scrub them.

Reprocessing an already-anchored document re-matches the same anchors

Because the anchor text is only visually hidden, a document you’ve already run through anchor-tag processing still matches the same anchor_string values if you pass it (or a copy of it) back into a new create request with the same anchor_tags. The invisible text is indistinguishable from visible text to the matching step. Always run anchor tags against your original, unprocessed source document — not against a document you already generated from a previous anchor-tag request.

Anchor-tag font styling mostly doesn’t persist

An anchor tag accepts font_family, font_size, font_color, and text_align. Only font_size actually reaches the created field — it’s merged into format_rules.fontSize (clamped to 8–48). font_family, font_color, and text_align are resolved internally but dropped before the field is saved, so setting them on an anchor tag has no visible effect.

`stamp`, `file`, and `approval_*` anchor types need explicit sizing

stamp, file, approval_signature, approval_checkmark, and approval_date all pass server-side validation as anchor type values, but none has a dedicated default-dimensions entry, so all five silently inherit the text default (20% × 3%). Pass width and height explicitly for these types.

Next steps

Sending a signing request for the full recipient and field creation flow
Field prefilling — the read_only/read_only_value/format_rules.prefilledData behavior that anchor-placed fields also follow once created
Webhooks — subscribe to webhook events to react as anchor-placed fields are completed

Starter guides

Advanced guides

How matching works

Default field sizes

Hiding anchor text

DOCX documents

PDF documents

PDF vs. DOCX at a glance

Complete example

Gotchas

Removed anchor text is hidden, not deleted — plan for it showing up in extraction

Reprocessing an already-anchored document re-matches the same anchors

Anchor-tag font styling mostly doesn’t persist

`stamp`, `file`, and `approval_*` anchor types need explicit sizing

Next steps

​How matching works

​Default field sizes

​Hiding anchor text

​DOCX documents

​PDF documents

​PDF vs. DOCX at a glance

​Complete example

​Gotchas

​Removed anchor text is hidden, not deleted — plan for it showing up in extraction

​Reprocessing an already-anchored document re-matches the same anchors

​Anchor-tag font styling mostly doesn’t persist

​stamp, file, and approval_* anchor types need explicit sizing

​Next steps

How matching works

Default field sizes

Hiding anchor text

DOCX documents

PDF documents

PDF vs. DOCX at a glance

Complete example

Gotchas

Removed anchor text is hidden, not deleted — plan for it showing up in extraction

Reprocessing an already-anchored document re-matches the same anchors

Anchor-tag font styling mostly doesn’t persist

`stamp`, `file`, and `approval_*` anchor types need explicit sizing

Next steps