Fields
Last updated recently
Fields
Every source names things differently. Your Facebook form calls it field_data[phone_number], your
website form calls it phone_number, the webhook from your partner's CRM calls it contact.Phone,
and the destination you sell to expects primary_phone.
Formwork's answer is a fixed middle name. Every source translates into it on the way in, and everything downstream - presets, destination templates, event payloads - refers only to that. This page is about that vocabulary and how sources translate into it.
The canonical fields
Routing → Fields is the registry.
Formwork ships eleven built-in fields:
| Key | Label | Type | Normalised to |
|---|---|---|---|
email | lowercased | ||
phone | Phone | phone | E.164, e.g. +15551234567 |
firstname | First name | string | trimmed |
lastname | Last name | string | trimmed |
fullname | Full name | string | for sources that do not split the name |
state | State | state | two-letter code, e.g. TX |
city | City | string | trimmed |
zip | ZIP / Postcode | string | trimmed |
country | Country | string | name or ISO code |
consent | Consent | boolean | true / false |
submitted_at | Submitted at | date | when the origin recorded the lead |
The built-ins are read-only. You can add as many of your own as you need - monthly_bill,
roof_type, credit_band, whatever your destinations ask about.
Adding your own
A custom field needs a key and a label, and the key has rules: lowercase letters, digits and
underscores, starting with a letter. That is not fussiness - the key is interpolated into
destination request bodies as {{monthly_bill}}, so anything else would make the template
unparseable.
Pick a type as well. The type is what Formwork coerces incoming values into, and it is how
"42" becomes the number 42 and "Texas" becomes "TX".
The key is referenced by every preset, destination body template and event payload that uses it. Changing it does not update those references - it breaks them. Treat a key as permanent once anything points at it.
How a source translates into them
That translation is called field mapping, and where you configure it depends on the source.
Website forms map themselves
Because you authored the questions, the canonical key is a property of the field itself. Set it in the builder's field inspector and the mapping is derived automatically every time the draft saves. There is no separate mapping screen and no chance of the two drifting apart.
Everything else maps on the source page
Facebook, TikTok and inbound webhook sources arrive with somebody else's field names, so the mapping is explicit. Open the capture from the Forms list to reach Match up the fields.
Each row is one translation, and reads left to right as a sentence: this form calls it X, treat it as Y.
Clean-up steps
Raw values are rarely in the shape a destination wants. Each mapping row can carry an ordered chain of transforms, shown as numbered chips.
| Step | What it does |
|---|---|
| trim | Removes leading and trailing whitespace |
| lowercase / uppercase | Changes case |
| digits only | Strips everything that is not a digit |
| phone format | Normalises to E.164 |
| state code | Turns a state name into its two-letter code |
| first answer | Takes the first value when the source sends a list |
| join with commas | Flattens a list into one string |
Order matters. Facebook sends every answer as an array, so first answer has to run before
phone format - reversed, the phone formatter is handed a list and gives up. The chips are numbered
for exactly this reason, and the arrow on each chip moves it earlier.
Passthrough, and what happens to unmapped answers
A source can keep unmapped answers rather than discarding them, and by default it does - the raw payload is stored forever regardless, so nothing is ever truly lost.
But an unmapped answer is not part of the shared vocabulary. Presets cannot test it, destination templates cannot reliably reference it, and it will not be normalised or type-checked. If a question matters to your routing or your destinations, map it.
The mapping editor's toolbar counts this for you: how many of the fields in the lead are mapped, and how many are not.
Checking the contract before it bites
A routing setup knows which canonical keys it needs - the union of every key referenced by its presets, its destinations' body templates, its ping templates and its event payloads.
When you attach a source to a routing setup, Formwork compares that list against what the source actually produces and warns about the gap. The routing builder shows the same thing per attached form, and marks preset nodes that test a field some attached source does not supply.
This is a warning, not a block. A preset testing a field that never arrives simply never matches, which sends every lead to your default waterfall - a failure that is easy to miss and expensive to leave running.
What to read next
- Presets - testing these fields to decide where a lead goes.
- Destinations - putting these fields into an outbound request.
- Routing - where the field contract is checked per attached form.