How Formwork Works
Last updated recently
How Formwork works
Formwork captures leads from several places, puts them all into one shape, and then offers each one to the destinations you have configured until somebody takes it.
Everything in the Lead capture menu is one half of that sentence. This page explains the shape of the system so the rest of the documentation makes sense; if you would rather start doing than reading, go straight to Your first website form.
The four things a lead can arrive from
Formwork calls all of them sources, and treats them identically once the lead is inside.
| Source | Where the lead comes from | Where you set it up |
|---|---|---|
| Website form | A form you build in Formwork and embed on your own site | Forms → New capture |
| Facebook Instant Form | A Meta Lead Ads form attached to a Page you manage | Forms → New capture |
| TikTok Instant Form | A TikTok Lead Ads form on an advertiser account | Forms → New capture |
| Google Ads lead form | A lead form asset on a Google Ads campaign | Forms → New capture |
| Snapchat Lead Ads | A lead generation form on a Snapchat ad account | Forms → New capture |
| Inbound webhook | Anything that can send an HTTP POST | Forms → New capture |
Only the first one involves the form builder. The other five already have a form - somebody else's
- so the job there is translating their field names into yours.
The path a lead takes
Read left to right, that is: something sends a lead, Formwork renames its fields into a vocabulary you control, a routing setup decides which destinations should see it and in what order, and the first destination to say yes gets it.
The five ideas worth learning once
Sources are interchangeable. A Facebook lead and a webhook lead run through exactly the same code once they are inside. Anything you configure downstream - presets, destinations, events - works for all of them without being written twice.
Canonical fields are the shared vocabulary. Your Facebook form calls it
field_data[phone_number], your website form calls it phone_number, and your destination expects
primary_phone. Formwork's answer is a fixed middle name - phone - that everything else speaks.
Translating a source's field names into canonical keys is called field mapping, and it is the
one piece of setup per source that nothing else can do for you. See Fields.
A routing setup is reusable. It is not owned by a form. It is a library object that holds your routing rules, and many forms can point at the same one. Change the destination order in one place and every form using that routing setup follows.
A branch is a preset plus an ordered list of destinations. Presets decide whether a group of destinations gets the lead; the order of the list decides who gets first refusal. That ordered list is the waterfall.
At most one sale per lead. The waterfall stops at the first destination whose response satisfies its accept rule. Destinations below that one are never called. There can be many outbound calls per lead, but never two sales.
Where to start
Do it in this order. Each step is useless without the one before it.
- Fields - check the canonical fields cover what your destinations ask for. Add any that are missing.
- Destinations - add at least one destination, with an accept rule that describes what a "yes" looks like from them.
- Presets - only if you need to send different leads to different destinations. A single default waterfall needs no presets at all.
- Routing - put those pieces together into the routing a lead will actually run through, and switch it live.
- Your first website form or Facebook Instant Forms - capture something.
You can also do it backwards - build a form first and route it later. Formwork will let you, and the form's settings page will warn you clearly that leads are being stored but not sold.
Where things live in the menu
- Forms - every capture you have, of all four types, and the button that makes new ones.
- Integrations - the Facebook, TikTok and Snapchat accounts you have connected.
- Routing - the routing library, plus its Presets and Fields sub-pages.
- Destinations - who you sell to, and what their "accepted" response looks like.
- Presets - reusable rules like state is one of TX, FL, AZ.
- Fields - the canonical vocabulary.
- Logs - every lead that arrived and every call Formwork made about it.
Signing in
Development databases seeded with npm run seed get a Super Admin account. The credentials are
printed in the project README; change the password before the app is reachable from anywhere public.