Understanding field paths

Last updated: June 12, 2026

Every field on a form has a path. The path decides where the field's answer is stored — and whether the field connects to a fact about the employee, employer, client, or job, so the form can read what's already on file and write new answers back.

What it is

A field's path is the address where its value is stored. Every field has one.

There are two kinds. A form-local path — it starts with form. — stores the answer only on this form; the value lives nowhere else. An entity path connects the field to a record that exists outside the form: the employee (employee.first_name), the employer (employer.name), the client (client.name), or the job (job.address.state).

If you remember nothing else: an entity path isn't just storage — it's a live connection to that record, in both directions.

Why it matters

When you point a field at employee.first_name, you're not inventing a new "first name" that only this form knows about. You're connecting the field to the employee's actual first name — the same one every other form and record uses.

That one connection is what lets a form show information you already have and keep your records current at the same time, instead of asking the employee to retype what you already know and then storing the answer in a dead end.

This matters most when:

The same piece of data — a name, an address, an email — appears on more than one form.
You want forms to arrive partly filled with what you already know.
You want the answers an employee gives on a form to update the underlying record.

How it works

Every path is scoped to an object

A path always names the object it belongs to — that's the prefix: employee., employer., client., job., or form. for form-local. The prefix is how Onboarded knows which record to read from and write to. There's no unscoped reference: name on its own means nothing, while job.name resolves to the job connected to this placement and employer.name resolves to its employer.

Because a path resolves against the records connected to the placement, the object has to actually be there. job.name only has a value when the placement has a job attached; if a form runs in a context where that object isn't present, the path has nothing to resolve to and comes back empty.

Placement-level data takes the same rule one step further: placement.custom_attributes.* only resolves when the form is running on a placement, so Onboarded knows which placement to read from. Placement attributes aren't selectable as field paths or content variables — they live in the policy and rules layer, where they decide which forms get assigned. (See 📄 Rule operators.)

Reading: the form arrives pre-filled

When you preview a form, or when an employee opens it, Onboarded resolves each field's path against the connected records. A field pointed at employee.first_name shows the employee's existing first name already filled in; a field pointed at employer.name shows the employer's name. The employee confirms what's there instead of typing it from scratch.

A form-local form. path has no outside record to read from, so it starts empty — it only holds what gets entered on the form itself.

Writing back: the answer updates the record

When the form is submitted, a field connected to an entity writes its value back to that record. If an employee corrects the address on a field pointed at employee.address, the employee record is updated with the new address — so the next form they open already reflects it. The same holds for employer fields and the employer record.

This is the part that's easy to miss: an entity path reads and writes. It's a connection, not a copy. Point two forms at employee.email and they share one value — whichever form is submitted last updates it.

Where you can use a path

The same path system shows up in more than one place. You can use a path:

As a field's path — connecting the field to a fact, as described above.
In a review table — to display a fact read-only. A review table lists the paths you want to show and renders their current values without collecting or changing anything. This is the right tool when you want an employee to see a fact (their employer's legal name, say) without being able to edit it.
As a content-block variable — to drop a fact into body text. In a content block, type {{ to open the variable picker and choose a path; the value renders inline when the employee reads the form.

One rule ties the display cases together: a review table or content variable can only show a field that was collected on an earlier page. A field's answer isn't recorded until its page is submitted, so a value entered on page two can be displayed on page three — but not on the same page it's being filled out on, where there's nothing to show yet. Facts that already exist before the form starts, like employee.first_name or employer.name, are available from the first page.

For example: collect form.gender on page one, then on page two display it back — alongside employee.first_name — in a content block or a review table.

If you only want to display a fact, don't bind an editable field to it — that field will overwrite the record on submit. Use a review table or a content variable for read-only display.

Finding the right path

You don't have to memorize paths. As you type in a field's Path, a dropdown suggests matches as you go — built-in facts with friendly labels like First name (employee.first_name) and Employer name (employer.name), alongside the custom attributes defined on your account. Pick one from the list to connect the field to that record.

Custom attributes show up here too, grouped separately from the built-in facts. Once you create a custom attribute on an entity, you can reference it exactly like a built-in fact — under that entity's custom_attributes namespace (for example, employee.custom_attributes.shirt_size). For the full list of facts available without creating anything, see 📄 Facts available by default.

What you can connect to depends on the form

The facts a form can reference depend on whether it's one of your account's own forms or a global form — a shared, pre-built form designed to be adopted across many accounts.

A global form can only reference the built-in facts that every account has: the system fields on the employee, employer, client, and job. It can't reference account-specific custom attributes, because the accounts that adopt the form may not have them.

On your account's own forms, you can reference both — the built-in facts and the custom attributes you've defined. So if a path you expect isn't offered in the dropdown, check whether you're editing a global form; that's the usual reason a custom attribute is missing.

Example

Take an account onboarding a new hire who has already registered, so the employee's name and address are on file. Two of the forms in their flow are an I-9 and a direct-deposit authorization.

On the I-9, the name and address fields are pointed at employee.first_name, employee.last_name, and employee.address. When the employee opens the form, those fields are already filled with what's on file — they confirm rather than retype. They notice their apartment number is missing and add it; on submit, the corrected address writes back to the employee record. When they reach the direct-deposit form, its address field — pointed at the same employee.address — already shows the corrected version.

The I-9 also needs to display the employer's legal name for reference, but the employee shouldn't edit it. Rather than an editable field bound to employer.name, the account puts the employer name in a review table, where it shows read-only. The result: less typing, fewer mismatched copies of the same data, and one source of truth that each form both reads from and keeps current.