Facebook Lead Ads

Leads that people submit on your Facebook and Instagram lead forms are created in the CRM automatically. Each Facebook lead form is linked to one of your CRM forms (built in the Engagement Form Builder), so the CRM form's submit actions — Create Lead, duplicate checks, auto-replies and lead_created workflows — run for every Facebook lead, the same as for a web form.

Navigate to Admin > Integrations > Facebook Lead Ads.

Who can use this page

Task	Who
Connect or disconnect Facebook Pages	Administrators only
Link lead forms, edit mappings, review and retry leads	Administrators, and roles with Integrations → Configure

Roles with Integrations → Configure see Facebook Lead Ads in the settings menu; they don't need access to the rest of the Integrations page.

Server setup

The page shows a banner when something on the server is missing: the Facebook app (FB_APP_ID / FB_APP_SECRET) or lead delivery (the message broker). When everything is in place it shows Lead delivery is running. The banner also shows the redirect URI to allow in the Meta app. See Environment Variables.

Connecting Pages

1. Click Connect Facebook and sign in with a Facebook account that manages the Pages.
2. Facebook asks which Pages and Businesses to share. Tick every Page whose lead forms you want, and accept all the permissions asked for.
3. Back in the CRM, the Choose Pages to connect window lists the Pages Facebook returned. Tick the Pages and click Connect.

The CRM asks Facebook for these permissions: pages_show_list, pages_manage_metadata, pages_read_engagement, pages_manage_ads, leads_retrieval and business_management. Meta requires pages_manage_ads (with leads_retrieval) to list a Page's lead forms and read its leads.

• Pages in a Business portfolio are listed too, even when your Facebook account reaches them only through the business.
• Pages that can't be connected are shown greyed out with the reason — usually that Facebook didn't give the CRM access to that Page for your account. Ask someone with full control of the Page to connect it, or check your tasks on the Page in Meta Business Suite.
• A Page is missing from the list? It wasn't ticked on Facebook's Choose the Pages screen. Click Connect Facebook again, choose Edit previous settings and tick it.

Connected Pages are listed under Connected Pages. A Page shows lead subscription failed — reconnect or access expired — reconnect when Facebook no longer delivers its leads; connect it again to fix it.

Reconnect after this release

Pages connected before the 2026-10-14 release were connected without pages_manage_ads. If listing a Page's lead forms fails with a message asking you to reconnect, click Connect Facebook again and grant the permission.

Linking a lead form

Under Lead form mapping, pick a Page to see its Facebook lead forms. A form that isn't linked shows Not linked; its leads can't be created until you link it.

1. Click Link next to the form (Edit for a form that is already linked).
2. Choose the CRM form that should create the leads. The CRM form must have a Create Lead submit action.
3. Under Fill each CRM field, set a value for each field of the CRM form (see below).
4. Click Save.

To unlink a form, click × next to its mapping.

Filling CRM fields

Each CRM field has one input. Type fixed text and insert chips for values from the Facebook lead — like a Zapier field. You can mix several chips and text in one field.

Chip group	Examples
Answers — every question on the Facebook form	Email, Phone number, Full name, any custom question. A Full name question also offers first part and last part.
Lead details	Campaign name / ID, Ad set name / ID, Ad name / ID, Form name / ID, Page name / ID, Platform (Facebook or Instagram), Submitted at, Facebook lead ID

Examples:

• Lead source description: Lead from + Form name + Facebook
• Last name: Full name: last part
• Notes: Campaign name + / + Ad name

Under each field you see the value it would get. Required CRM fields are flagged in amber when they would be empty: leads go to review if a required field is empty.

When you first open a form, common questions are filled in for you (email, phone, first and last name from the full name, company). Mappings made before this release still work; they are converted to the new editor the next time you edit them.

Recent leads

Recent leads lists every lead Facebook delivered, grouped by Page, with the number created, failed and in progress for each Page. Pages with failed leads are listed first and opened automatically. Filter by Page and by status.

Status	Meaning
created	The lead was created. created (reviewed) means someone fixed it in Review.
processing	Being handled right now.
retry	A temporary error (for example Facebook didn't answer). It is tried again automatically: up to five attempts over about 2½ hours.
failed	The lead could not be created — for example a required CRM field is empty, the CRM form rejected a value, or the Facebook form isn't linked (No active mapping).

Each row shows the person's name and email, the form, the number of attempts (×2, ×3…) and the error. If Facebook delivers the same lead twice, it is created only once.

Leads from a form you haven't linked yet

They fail with No active mapping rather than being lost. Link the form, then open each lead in Review (or click ↻) to create it.

Reviewing a failed lead

Click Review on a failed lead.

• The left side shows what they answered and the lead details (campaign, ad, form).
• The right side shows the same field editor as the mapping, with the value each CRM field would get and the fields that failed highlighted. You can also pick a different CRM form under Create the lead through.
• Tick Use this mapping for future leads from this form to save your changes as the form's mapping, so the next leads don't fail the same way.
• Click Create lead.

The lead's answers are stored with the log entry when it arrives, so you can still review it after Facebook stops keeping the data (Meta keeps lead data for 90 days).

The ↻ button runs the lead again as it is — useful after a Facebook outage, when nothing about the mapping needs to change.

Failure alerts

When a lead fails, every administrator and the person who connected the Page get an in-app notification and an email (Facebook Lead Failed), whatever their notification preferences. The notification opens the review directly. The email template can be edited in Notification Settings → Templates.

Troubleshooting

Problem	What to do
Requires pages_manage_ads permission / a message asking you to reconnect	Click Connect Facebook again and accept every permission Facebook asks for.
A Page is greyed out in the Page picker	Facebook didn't give your account a Page token for it. Ask someone with full control of the Page, or check your Page tasks in Meta Business Suite.
No leads arrive	Check the banner at the top of the page says Lead delivery is running, and that the form is linked. A Page marked reconnect must be connected again.
Many leads fail with the same field	Open one in Review, fix the field, tick Use this mapping for future leads and create it. Then retry the others.
Leads arrive without campaign or ad details	Your Facebook account may not be allowed to read the ad. The lead is still created with its answers.

See also: Email Leads — the same approach for a shared mailbox.