Integrations
Last updated recently
Integrations
An integration is a live connection to an account you own somewhere else: a Meta account whose Pages run lead ads, a TikTok account whose advertisers do, or a Snapchat account whose ad accounts do. It is the permission slip that lets Formwork read leads on your behalf.
This page used to cover routing. That moved to Routing when the names changed. Integrations now means connected accounts, which is what this page is about.
There is exactly one thing to understand about integrations, and everything else on this page follows from it: an integration is borrowed access, and it can be taken away without telling you. A form you built keeps working forever. A grant from Meta, TikTok or Snapchat expires, gets revoked when somebody leaves the company, and lapses when an app permission is reviewed. Formwork cannot prevent any of that. What it can do is notice, and say so.
Snapchat renews itself, the other two do not
Snapchat is the exception worth knowing about. Its access tokens last sixty minutes, so Formwork refreshes them automatically in the background and you will never be asked to reconnect because one expired. You only hear from us when the underlying grant itself is withdrawn, which is the one case reconnecting actually fixes.
There is a second Snapchat difference, and it cuts the other way. Meta and TikTok both let Formwork go back and fetch leads it missed. Snapchat has no such thing. Snapchat delivers each lead once, by webhook, and offers no way to ask for it again afterwards. Nothing Formwork does can recover a lead that was not delivered, so a Snapchat source is worth watching more closely after you set it up than the other two.
Where they live
Integrations in the sidebar lists every account you have connected, which provider it belongs to, and whether it is currently healthy.
Each row shows what that grant can reach: the Pages or advertisers it covers, and how many Formwork sources are feeding from it.
Connecting an account
You can connect from this page, or on the way through the capture wizard, which is where most people meet it first. Both do the same thing.
The provider's authorisation dialog opens in a new tab, deliberately. Redirecting away would throw away whatever you were halfway through. Approve the permissions there, come back to the Formwork tab, and press Refresh accounts.
Meta, TikTok and Snapchat all let you approve a subset of the permissions requested, and none of them treats a partial approval as a failure. The connection then succeeds and fetches nothing.
This is the single most common way a setup goes wrong, and it is painful precisely because it does not look like an error: leads arrive as notifications Formwork cannot open. Formwork lists the missing permissions on the integration row. If you see any, disconnect and authorise again rather than working around it.
What an integration actually carries
A grant is not a password, and it is narrower than people expect.
- A token, stored encrypted, that Formwork sends when it calls the provider.
- A scope, which is the list of things that token is allowed to do.
- A set of accounts the token can see: Pages for Meta, advertisers for TikTok, ad accounts for Snapchat.
It does not carry your login, and it cannot be used to post as you. Revoking it in the provider's own settings kills it immediately, from their side, without touching Formwork.
Keeping one alive
Tokens expire on a schedule you do not control. Formwork runs a job that refreshes them before they lapse, which handles the ordinary case silently and is the reason most people never think about this.
Refresh fails when the underlying permission is gone rather than merely old. In practice that means somebody removed the app from the Meta, TikTok or Snapchat account, or changed a Page role so the connecting user no longer administers it. No refresh recovers from that, because the answer from the provider is not "expired", it is "no".
When that happens the integration is flagged and needs reauthorising by someone who still has the right role on the account.
Leads do not error when a grant dies. The provider's webhook still fires, Formwork still receives the notification, and the fetch that follows is the part that fails. So the symptom is an absence: lead volume drops, and nothing announces why.
If lead volume falls off a cliff, check this page before you go looking in Logs.
Reconnecting
Reconnecting is safe and non-destructive. It replaces the stored token in place.
Your sources, field mappings, routing and destinations all reference the integration rather than the token inside it, so none of them are disturbed. You do not need to remap fields or reattach forms after a reconnect.
For Meta and TikTok, leads that arrived while the grant was broken are picked up by the reconciliation sweep once access is restored. For Snapchat they are not, because Snapchat has no endpoint that returns past leads. Reconnecting restores delivery from that moment on and recovers nothing from the gap.
Disconnecting
Disconnecting removes the stored grant. Any source that depends on it stops being able to fetch, so Formwork names those sources before it lets you proceed.
The leads already captured are yours and stay exactly where they are. An integration is how leads get in, not where they live.
What to read next
- Facebook Instant Forms - connecting a Meta lead form and mapping its fields.
- Fields - the canonical vocabulary those mapped answers land in.
- Routing - what happens to a lead once it is in.