> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://katalyz.crisp.help/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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](https://storage.crisp.chat/users/helpdesk/website/-/5/5/4/8/554891f22af0b400/envelope-document-path-chooser_1o1hyfu.png)

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

1. *Declare each role and variable below.*
2. *Copy its code and type it into the document in Word.*
3. *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"](https://storage.crisp.chat/users/helpdesk/website/-/5/5/4/8/554891f22af0b400/signature-template-variables-r_1f3vqj9.png)

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:

1. **Download** the file
2. *Type the codes into it in Word*
3. **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.

## Related articles
- [Signature templates](https://katalyz.crisp.help/en/article/signature-templates-ybd6ym/)
- [Adding a signature block to a room](https://katalyz.crisp.help/en/article/adding-a-signature-block-to-a-room-u85qg0/)
- [Legal validity of Katalyz signatures](https://katalyz.crisp.help/en/article/legal-validity-of-katalyz-signatures-133h7gd/)