Articles on: Signatures

PDF fields vs Word codes

Every envelope and every signature template starts with one question — What are you sending? (or, for a template, What are you building this template from?). The two answers, Fixed-layout PDF and Write it in Word, work in opposite ways. This article explains why, and which one to pick.

The one-line version

A PDF is a fixed page. Fields are boxes you drag onto it.
A Word file re-flows every time its text changes. Fields are placed by codes you type into the document, and Katalyz never rewrites your file.

The document-path chooser with the "Fixed-layout PDF" and "Write it in Word" cards

Why the two can't work the same way

When a template merges a variable — the customer's legal name, the deal value, today's date — the text gets longer or shorter. In a PDF nothing moves, so a signature box placed at "page 2, two-thirds down" stays right. In a Word document every paragraph after that point shifts, and any box placed by position would drift onto the wrong line.

That is why a .docx doesn't use positions at all. A field is anchored to a token typed in the text; wherever that token ends up after the merge, that's where the field goes. The signing provider finds the token and drops the field on it, and the token itself is hidden in the final document.

Fixed-layout PDF


Card text	The page never re-flows. Fields are boxes on it. — best for Order forms, printed contracts.
Steps	Import → Place fields
Sources	Upload the PDF, or (for envelopes) From this room, From HubSpot, From library
Placing fields	Drag Signature, Initials, Date, Text or Annotation from the sidebar onto the page. Resize as needed.
Scope	A field lives on a single page or on all pages at the same position. Initials default to all pages — handy for long contracts.
Variables	The text of a PDF can't merge variables — the editor notes variables only fit overlay boxes. Put what changes into a Text field for the signer, or an Annotation you type yourself.
What is sent	The file As uploaded.

Uploading a .docx on this path is refused; the upload zone only accepts .pdf.

Write it in Word


Card text	Paste the codes into your own file. Never rewritten. — best for Letterheads, precise layout.
Steps	Template: Declare codes → Paste in Word → Import. Envelope: Write in Word → Import → Send
Sources	Upload only — the file is yours and stays yours
Placing fields	Type anchor codes where each signature block should go
Variables	Type merge codes in the text; Katalyz fills them at send time
What is sent	Your file, with the codes replaced. In-app editing of .docx files is not available — every change is made in Word and re-imported.

Uploading a PDF here is refused: "{file} is a PDF. This template is set up for a Word file, so its variables merge into the text." (envelopes: "{file} isn't a Word file. This envelope is set up for a .docx.").

Anchor codes

The codes are not derived from the role name. Katalyz generates one set per role, with a short random identifier, and hands them to you on screen. For a role named Customer signatory, the panel shows something like:

Field	Generated code	Required?
Signature	`[[sig_c92fbbdf]]`	Yes — every signer role needs one
Date signed	`[[date_c92fbbdf]]`	Optional
Initials	`[[initials_c92fbbdf]]`	Optional

Note the shape: double square brackets, a prefix (sig, date, initials), an underscore, then the role's identifier — the same one across all three codes of a given role. Each code has a copy icon; renaming the role does not change its identifier.

That is why you must never retype a code from this page: the identifier belongs to your role, in your template. Copy it from the Katalyz screen.

Merge codes

{{key}} anywhere in the text. Native keys resolve themselves from whatever the envelope is linked to:

Source	Codes
CRM · Account	`{{account.name}}`, `{{account.legal_name}}`, `{{account.address}}`, `{{account.vat_number}}`
CRM · Deal	`{{deal.name}}`, `{{deal.value}}`, `{{deal.close_date}}`, `{{deal.owner}}`
Room	`{{room.name}}`, `{{room.url}}`
Your org	`{{org.legal_entity}}`, `{{org.address}}`
Role	`{{signer.name}}`, `{{signer.email}}`, `{{signer.title}}`
System	`{{today}}`
Custom field	Your org's custom fields, typed by the sender at send time

Never copy the codes from this page — copy them from the panel in Katalyz, which knows your exact role names.

The Word authoring checklist

On a template's Variables & roles tab (and an envelope's Prepare tab), the left panel is your checklist:

Declare each role and variable below.
Copy its code and type it into the document in Word.
Import the edited file on the next step — this list re-checks itself.

The panel's header tracks progress — {n} codes to type into your document before any file exists, then {found} of {n} codes are in the file and finally All {n} codes are in the file, with a Still to type: … line naming what's missing.

"Variables & roles" panel — Signer anchors with their codes, one marked "✓ in document" and one "not typed yet"

Sections of the panel:

Signer anchors — one block per signer role with its three codes. Click a code to copy it.
Variables — the merge codes you declared, with a + picker (Search fields…) to add native variables or org custom fields.
Fills itself — Already in the document, and resolved from the room or CRM. Native codes you typed without declaring them: nothing to do.
{n} codes in the document have no match — codes Katalyz found in the file that nothing resolves. These stay as literal text when the envelope is generated. Usually a typo, or a variable that was never declared here.

What the badges mean

Badge	Meaning
✓ in document	The code was found in the imported file
not typed yet	The code is declared here but not in the file — go type it in Word and re-import
(no badge)	No file imported yet, so there is nothing to check against

Only signature anchors and declared variables are required; date and initials anchors are optional and never block publishing.

The round-trip

Once a Word file is imported, the document pane shows it Read-only · edit it in Word. To change anything, use the strip above it:

Download the file
Type the codes into it in Word
Upload the edited file

The re-upload replaces the previous version of the same document, and every code is checked again. Katalyz never writes into your file — that's the whole point of this path.

Which one should I choose?

Choose…	When…
Fixed-layout PDF	The document is final and shouldn't change — a printed order form, a counterparty's paper, a scanned contract. You want to drag boxes and be done.
Write it in Word	You maintain the contract in Word, care about the letterhead and exact layout, and want names, amounts and dates merged into the text automatically from the CRM or the room.

An envelope can mix both: your own paper on the Word path and the counterparty's PDF as uploaded. The Send tab's What will be sent list shows each document as As uploaded or Rebuilt, with a Preview to download the exact file that will go out.

Updated on: 04/10/2026

Was this article helpful?

Thank you!