> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta lead form sync

> Copy new Facebook and Instagram Instant Form leads into a lead dataset.

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](https://docs.erdo.ai/lead-identity.md) 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:

```bash theme={null}
erdo integrations status meta_ads
erdo provider-lead-sources forms --provider meta_ads --connection-id <meta-ads-integration-id> --account-id act_123456789
```

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

```bash theme={null}
erdo provider-lead-sources set --provider meta_ads --dataset northline.leads \
  --connection-id <meta-ads-integration-id> --account-id act_123456789 \
  --form 1169537898741742 --dry-run
```

`--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`:

```bash theme={null}
curl -X PUT "https://api.erdo.ai/v1/provider-lead-sources" \
  -H "Authorization: Bearer $ERDO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "dataset": "northline.leads",
        "provider": "meta_ads",
        "connection_id": "00000000-0000-4000-8000-000000000123",
        "account_id": "act_123456789",
        "forms": ["1169537898741742"],
        "dry_run": true
      }'
```

`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:

```bash theme={null}
erdo provider-lead-sources list --provider meta_ads
erdo provider-lead-sources delete --provider meta_ads --account-id 123456789
```

## 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

| Column | What it holds |
| - | - |
| `email`, `phone`, `name`, `first_name`, `last_name` | The person's answers to Meta's prefilled questions |
| `company`, `job_title` | The same, when the form asks for them |
| `location_city`, `location_state`, `location_country`, `postal_code` | Where the person said they live. `city` and `country` already record where their browser was |
| Each custom question | Saved under its question key, in lower case with underscores. A multiple-choice answer is written as the option's text. A key that clashes with a column Erdo writes, such as `budget_response`, is prefixed `question_`. See [Budget](#budget) |
| `utm_source`, `utm_campaign`, … | The form's tracking parameters, when it has any |
| `ad_campaign_id`, `ad_campaign_name`, `ad_set_id`, `ad_set_name`, `ad_id`, `ad_name` | The Meta campaign, ad set and ad that produced the lead |
| `ad_form_id`, `ad_form_name`, `ad_platform`, `ad_is_organic`, `ad_account_id` | The form, where the ad ran (`fb` or `ig`) and the ad account |
| `provider_lead_id`, `provider_form` | Meta's lead id and form id |
| `source` | Always `meta_lead_form` |
| `ts` | When the person submitted the form on Meta |
| `submitted_at` | When Erdo wrote the row. Alerts and automations key on this |

These are the same column names a [Meta export sheet or import](https://docs.erdo.ai/lead-sources.md)
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):

```json theme={null}
{
  "provider": "meta_ads",
  "dataset": "northline.leads",
  "connection_id": "00000000-0000-4000-8000-000000000123",
  "account_id": "act_123456789",
  "forms": ["1169537898741742"],
  "budget": {
    "question": "budget",
    "currency": "USD",
    "options": {
      "under_550k": "0:55000000",
      "550k_1m": "55000000:100000000",
      "1m_plus": "100000000:",
      "prefer_not_to_say": "prefer_not_to_say"
    }
  }
}
```

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.

## 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.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.