Lead Ads API: from the leadgen event to your CRM
Lead Ads are lead forms filled in without leaving Instagram or Facebook. When someone submits one, Meta sends a leadgen webhook to your endpoint containing only IDs. With the Socialift SDK your backend verifies it (verify_request), fetches the answers with fb.lead(), normalises them and writes the lead through your CRM's API as soon as the event arrives.
Updated:
Why integrate Lead Ads at all?
Meta Lead Ads store submitted leads inside the ads manager, where you can export them by hand as CSV. Integration removes that step: your backend receives the leadgen webhook and writes each lead to the CRM shortly after the form is submitted. The difference shows up in response time — no waiting for a daily export.
Manual export has two weaknesses. The first is latency: exporting once a day means a lead waits half a day on average, and a competitor has already called. The second is the 90-day limit: Meta only lets you download leads submitted in the last 90 days, so a missed export can lose data for good.
A lead that arrives through the integration carries the form ID, campaign context and the submitted answers together, so you can build correct source reporting in the CRM.
The lead's journey from ad to CRM
Create the form
The lead form is built inside a Facebook or Instagram ad. Its questions are later mapped onto CRM fields.
Request 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 webhook
In the App Dashboard subscribe the Page object to the leadgen field, then install the app on each Page: fb.subscribe_page(page_id, page_token, fields=["leadgen"]).
Fetch the lead payload
The event carries only IDs (leadgen_id, form_id, page_id, ad_id). Call fb.lead(leadgen_id, page_token) — it returns a Lead with the answers already normalised (socialift.leads.normalize).
Write to the CRM and assign
Your code creates the lead through the CRM's API, stores form_id and campaign as the source, and assigns an owner. Socialift has no ready CRM connector.
What the SDK gives you — and what your backend does
Event-driven
The event arrives shortly after the form is submitted — no waiting for a daily export.
Complete form answers
Not just an ID, but every field the person filled in.
Signature check
verify_request checks Meta's X-Hub-Signature-256 against the raw body, so forged leadgen events are rejected before any API call.
Dedupe key
Meta sends no event ID and may resend a webhook; dedupe_key() builds a stable key (leadgen_id) for a unique column in your database.
Retries on both sides
Meta retries failed webhook deliveries for up to 36 hours; SDK API calls retry 429/5xx with exponential backoff. Retrying writes into your CRM is your queue's job.
Source context
Form and Page identifiers travel with the lead, so attribution survives.
Things to get right when designing the lead flow
- Map form questions to CRM fields up front — changing them later is expensive.
- One person can submit twice: write down your merge rule by phone or email.
- Flag test leads separately or your reporting will be skewed.
- Store both the arrival time and the first-response time — that is the core KPI.
- If access is revoked the lead flow stops: keep that under monitoring.
- 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 do I capture Instagram leads automatically?
Instagram Lead Ads run through a linked Facebook Page, so Meta sends the leadgen event for that Page. Your backend fetches the answers with fb.lead() (leads_retrieval plus Page permissions) and writes the lead to the CRM.
How is this different from a CSV export?
CSV is manual and delayed, and Meta only lets you download leads from the last 90 days. The integration fetches each lead when its event arrives. On top of that, separating duplicates and test leads in a CSV is a manual job.
Which permissions does the Lead Ads API need?
leads_retrieval to read leads, pages_show_list, pages_read_engagement and pages_manage_ads for the Page, pages_manage_metadata for the webhook subscription, and ads_management for ad-level fields. Pages of people without a role on your app require Advanced Access via App Review.
Does Socialift push leads into my CRM itself?
No. Writing to the CRM happens in your backend: the SDK verifies the signature, fetches the lead answers and normalises them. Socialift has no ready connector for amoCRM, Bitrix24 or any other CRM. Leads from Pages connected in the dashboard show up under GET /crm/leads in the Playground.
Do the SDK's Lead Ads methods work during the free month?
Yes. For the first 30 days the 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) in the dashboard shows the exact list. The dashboard Playground works regardless of plan.
Sources
Related pages
Stop losing leads
Get a token, connect your Page and try the lead methods in the Playground.
Get a free token →