Sending Instagram Lead Ads leads to a CRM
When a Lead Ads form is submitted, Meta sends a leadgen event for your Page. It carries only IDs (leadgen_id, form_id, page_id, ad_id) — the answers are fetched with a separate API call using a Page token. Your backend then writes the lead through the CRM's API and assigns an owner. Meta keeps leads downloadable for only 90 days, so relying on manual exports is risky.
Published: Updated:
Why CSV is not enough
A CSV export is manual and introduces delay: exporting once a day means a lead waits half a day on average. Meta also lets you download only leads from the last 90 days, so a skipped export can lose data. Integration solves both problems.
How the flow is built
Request the permissions
Request leads_retrieval, pages_show_list, pages_read_engagement, pages_manage_ads, pages_manage_metadata (for the webhook) and ads_management (ad-level fields). Pages you don't manage require Advanced Access via App Review.
Subscribe to the leadgen event
In the App Dashboard subscribe the Page object to the leadgen field, then install the app on each Page with POST /{page-id}/subscribed_apps?subscribed_fields=leadgen (pages_manage_metadata).
Fetch the lead payload
Use the leadgen_id from the event: GET /{leadgen_id} with a Page token. In the Socialift SDK this is fb.lead(leadgen_id, page_token), which also normalises the answers.
Write it to the CRM
Your code creates the lead through the CRM's API: store the source and form ID, and assign an owner.
Separate duplicates and tests
Merge by phone or email; flag test leads distinctly.
Practical advice
- Map form questions to CRM fields up front — changing them later is expensive.
- Store both arrival time and first-response time: that is the core KPI.
- Deduplicate by leadgen_id — Meta may resend a webhook, and one lead must never be written twice.
- If access is revoked the flow stops: add monitoring.
- Store the form ID rather than the campaign name — names change.
- If a Page admin customised Leads Access Manager, grant access to the user whose token you use — otherwise fb.lead() is refused.
Frequently asked questions
How fast does a lead reach the CRM?
Meta sends the event shortly after submission; the rest depends on your lead fetch, queue and CRM API speed.
Do Instagram and Facebook leads share one stream?
Yes. The leadgen event is delivered at Page level, so one integration covers both platforms.
Can I retrieve older leads?
Yes, via GET /{form-id}/leads (fb.leads(form_id, page_token, since=...)), but Meta keeps leads available for download for only 90 days after submission.
Why does fb.lead() return a permission error?
Usually for one of three reasons: the token lacks leads_retrieval or the Page permissions; it was not issued by someone who can advertise on the ad account; or a Page admin customised Leads Access Manager without granting this user lead access.
Does a Socialift trial token unlock the Lead Ads methods?
Yes. For the first 30 days a trial token unlocks every SDK feature, including lead_forms, leads, lead and ad_context. After that the token renews in 30-day periods from your balance and its features depend on the token's plan — “Tekshirish va muhitlar” (Check and environments) under “Tokenlar” (Tokens) in the dashboard shows the exact list. The dashboard Playground works regardless of plan.