How do I swap the PDF on a published form without losing my mappings?

Last updated: May 29, 2026

When you need to add an updated version of a PDF you've already mapped, you can swap the underlying file without rebuilding the form. Your existing field mappings carry over to the new PDF.

Government forms get reissued. Internal forms get a new revision date. The mappings you spent an hour wiring up are still good — it's just the file under them that changed. Here's how to swap the file in place.

Before you start

You're working in a draft version of the form. Published versions are read-only — if the form is already live, create a new draft first. See 📄 How do I edit a published form by creating a new draft version?
You have the new PDF file saved locally.

Steps

Open the draft version of the form and go to the Edit PDF tab (step 1 in the editor).
In the top toolbar, click the three-dot menu on the far right (next to Save PDF).
Click Change PDF. The Change PDF document dialog opens.
Drop the new PDF into the upload area, or click it and select the file. The file name appears once it's attached.
Leave Delete mappings? unchecked. This is the default, and it's what keeps your field mappings intact.
Click Upload.

A success toast — Uploaded {filename} — flashes briefly at the bottom of the screen, then the page reloads. The toast disappears quickly. If you blink past it, the page reload itself is the confirmation that the upload went through.

When to delete mappings instead

Checking Delete mappings? wipes every mapping on the form and starts you from a blank slate. Use this only when the new PDF is structurally different from the old one — different fields, different layout, a different form entirely. For a routine revision where the client changed wording, fixed a typo, or updated a date, leave it unchecked.

Verify

After the page reloads:

The PDF preview shows the new file.
On the Field Mappings tab, your field mappings are still attached to their PDF fields.
Spot-check a few mappings — open one, confirm the source field on the PDF still highlights in the expected location.

If a mapping is missing or pointing at the wrong PDF field, the new PDF probably renamed or moved that field. Re-map it from the Field Mappings tab — the rest of your work is intact.