What you need
- A connected Meta Ads integration with the
leads_retrievalandpages_manage_adspermissions. 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: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_retrievalfor the ad account. - Each form is on a Page the account promotes.
- Erdo can read each form’s leads.
--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.
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. Addbudget 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):
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.
Consent
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.

