How do I map an address field to a PDF?

Last updated: June 9, 2026

Collect a full address with a single address field, then map each box on your PDF — street, city, state, zip — to a sub-path like form.personal_address.street.

PDFs almost always split an address across separate boxes: Street Address, City, State or Province, Zip Code, Country. It's tempting to recreate each box as its own text field on the form. Don't — one address field collects every component in a single structured input, validates it on submission, and gives you a dedicated sub-path for each PDF box.

Separate text fields skip that validation entirely. The employee can type california, Calif., or CA and your PDF will show whatever they typed. An address field normalizes state to a 2-letter abbreviation for US and Canadian addresses and country to a 3-letter code, so the PDF comes out consistent every time.

Address sub-paths

Every component of an address field lives at its own sub-path under the field's path. With a field at form.personal_address:

Sub-path

What it holds

Notes

form.personal_address.street

Street address

Always collected

form.personal_address.secondary

Unit, apartment, or suite

Optional — maps as blank when empty

form.personal_address.city

City

Always collected

form.personal_address.state

State or province

2-letter code for US and Canada (IL, ON); full name elsewhere

form.personal_address.zip

Zip or postal code

Optional

form.personal_address.country

Country

3-letter code (USA, CAN)

form.personal_address.full_address

The whole address as one formatted line

e.g. 55 E Jackson Blvd, Chicago, IL 60604, USA

Steps

The flow has two phases: add the address field to your form page, then map its sub-paths in the PDF view.

Add the address field

  1. Open your form's draft version in the form editor.

  2. Add a field and choose address from the field type list.

  3. Set the field's path — for example, form.personal_address. Every sub-path in the table above hangs off this path.

Map each PDF box

  1. Switch to the PDF tab to load the PDF mapping view.

  2. Map each PDF box to the matching sub-path. Mappings are LiquidJS templates — the street box gets {{ form.personal_address.street }}, the city box gets {{ form.personal_address.city }}, and so on down the table.

  3. Confirm every address box on the PDF has a mapping, including secondary if the PDF has a unit or apartment line.

PDF wants the whole address in one box? Map it to {{ form.personal_address.full_address }}. It's formatted per country automatically — don't stitch the sub-paths together by hand.

If the address lives inside a repeating section — emergency contacts, prior addresses, references — the same idea applies: make address a subfield of a repeatable group and map each instance's sub-paths.

Verify

Preview the form, submit a test address, and open the completed PDF. Each box is filled from its sub-path, with state as a 2-letter abbreviation and country as a 3-letter code. If a box is empty, check its mapping for a typo in the path — the sub-path must match the field's path exactly, and the path is case-sensitive.

Related