Skip to main content
Meta lead form sync reads the leads people submit on your Facebook and Instagram lead ads (Meta’s Instant Forms) and writes each one as a lead in your lead dataset. Erdo checks every 15 minutes. You don’t need a Google Sheet or a Zapier step in between. The capability is available to all organizations. The dataset must have lead identity turned on.

What you need

  • A connected Meta Ads integration with the leads_retrieval and pages_manage_ads permissions. If your connection predates them, reconnect Meta Ads and approve them.
  • The ad account that runs your lead ads. It must be one the connection selected, and it must not be shared with another organization.
  • A role on the Facebook Page your Instant Forms belong to.

Find your forms

An Instant Form belongs to a Facebook Page, not to an ad account. Erdo lists the forms on the Pages your ad account can promote:
Each form comes back with its id, name, state and the page_id it belongs to. An ad account can often promote Pages your connection has no role on. Erdo skips those and lists them under unreadable_pages, and the forms on the other Pages still come back. Saving a form that sits on one of those Pages is refused with that Page named, until the connected user gets a role on it. The same list is at GET /v1/provider-lead-sources/forms?provider=meta_ads&connection_id=<id>&account_id=<ad-account-id>.

Declare a source

--dry-run checks everything a save checks and saves nothing:
  • The dataset is a lead dataset in your organization.
  • The connection holds leads_retrieval for the ad account.
  • Each form is on a Page the account promotes.
  • Erdo can read each form’s leads.
Run it again without --dry-run to save. Over REST, send the same fields to PUT /v1/provider-lead-sources:
account_id works with or without the act_ prefix. Erdo stores it without the prefix. One declaration covers one ad account, and saving again replaces it. Over MCP, erdo_list_lead_source_forms with provider: "meta_ads" lists the forms, and erdo_save_lead_source declares the source. List or remove a declaration by provider and account:

Which leads are written

One form can run in ads across several ad accounts. Erdo writes a lead only when the ad it came from belongs to the declared account. These leads are never written:
  • Organic leads. People who opened the form from a Page post rather than an ad carry no ad.
  • Ad preview leads. Leads submitted from an ad preview have no ad either.
  • Leads from another account’s ads. The form may be shared, but those leads belong to the other account.
If every lead is skipped this way, check that the connection has advertiser access to the ad account. Without it, Meta sends leads without their ad. Test leads from Meta’s Lead Ads Testing tool are stored apart from real leads, and Erdo never reads them.

Backfill and timing

The first sync reads the last 90 days, which is how long Meta keeps leads available. Leads submitted before you declared the source are written as history. They keep their own arrival date and never trigger a new-lead alert, a row action or follow-up until somebody starts them. Adding a form later backfills that form too. Later syncs reread the last 48 hours, so leads Meta makes available late are still caught. Each lead is written once, however often Erdo reads it. A person who already reached you another way, through a landing page or a Meta sheet or import, matches their existing lead, so they’re not added twice.

Columns in a lead row

These are the same column names a Meta export sheet or import uses, so leads from both look the same. Meta’s campaign is never written to utm_campaign, which belongs to the campaign tags on links to your own pages.

Budget

A budget question on the form is written to the lead’s budget only when the source says what each option means. Erdo never reads a range out of the option text. Add budget to the declaration, with the question’s key, the currency, and each option key mapped to a range in whole minor units (cents for USD):
Save it with erdo provider-lead-sources set --file source.json. <min>: is an open-ended top band. Each lead then gets budget_response, budget_min_minor, budget_max_minor, budget_currency and budget_label (the option they chose), the same columns a landing page’s budget field fills. An option you leave out records no budget, and the answer stays as a custom question. Saving a changed budget rereads the last 90 days, and leads already imported that have no budget yet get their answer too. They’re updated as history, so no alert or row action fires. A budget a lead already has is kept: changing the ranges later doesn’t rewrite it. Saving the declaration replaces it, so include budget every time you save. When the form has a custom disclaimer with consent checkboxes, the person’s answers fill the consent columns. consent_given is true only when every box was ticked, and consent_method is checkbox. A form without checkboxes records no consent. A later “no” never replaces a recorded “yes”.

Checking a source

erdo provider-lead-sources list --provider meta_ads shows these for each declaration:
  • synced_through: every earlier lead has been handled up to this time.
  • last_run_at: when Erdo last read the source.
  • last_error: why the last read didn’t finish, such as a connection that needs reconnecting or a permission Meta refused.
A lead that failed to write is read again on the next sync. After three failed syncs in a row, Erdo raises an attention item. If the dataset is deleted, Erdo disables the source. Deleting a declaration leaves the leads already written in place. Declaring the same account again never writes a lead a second time.