Facebook Lead Ads
Read Meta Lead Ads - the Pages, their lead forms and questions, and the leads submitted through them - plus the webhook subscription that pushes new leads in real time.
Connect a Meta access token to work Facebook and Instagram Lead Ads: list the Pages the token manages, read their lead forms with the exact question keys a lead's answers are named by, page through submitted leads with their answers and the ad, ad set and campaign that produced each one, and fetch a single lead by the id a leadgen webhook delivers. Webhook subscriptions can be inspected, added and removed, so leads can be pushed rather than polled. Meta deletes lead data after 90 days and this integration says so wherever it matters - an empty result for an older window means the data is gone, not that nobody submitted. Page access tokens that Meta returns alongside page listings are treated as credentials and never appear in results. Creating forms or ads is not offered.
Connect
| Credential field | Required | Where it comes from |
|---|---|---|
Access token (ACCESS_TOKEN) | Yes | A Meta Page access token or (preferred) a Business Manager System User token, with leads_retrieval, pages_show_list and pages_read_engagement. A short-lived user token from the Graph API Explorer will not work - it expires in about an hour and cannot read leads. |
Tools
| Tool | Access | What it does |
|---|---|---|
Whoami (yekar.facebook-lead-ads.whoami) | Read | What this connection's access token belongs to - a Facebook user, or a Page. The distinction is the single most common cause of failures here: reading leads needs a PAGE token (or a System User token with the page assigned), and a plain user token can list pages and nothing else. Use Debug token for the token's scopes and expiry. |
Debug token (yekar.facebook-lead-ads.debug-token) | Read | What this connection's token actually is: its app, type, validity, permission scopes, which pages each granular scope covers, and when it expires - with 'never expires' reported as such rather than as a 1970 date. Check this BEFORE assuming a lead-reading failure is a code problem. Meta may refuse the introspection itself if the token does not administer its own app; that refusal says nothing about whether the token can read leads. |
List pages (yekar.facebook-lead-ads.list-pages) | Read | The Facebook Pages this token can manage, with what it is permitted to do on each (tasks). Every lead form belongs to a page, so this is the first read. Note: Meta returns a page access token with each row - that credential is stripped and never appears in the result. |
List lead forms (yekar.facebook-lead-ads.list-lead-forms) | Read | The lead forms on a Page, with Meta's own count of leads each has collected and how many have already aged out of Meta's 90-day retention. Every leads query needs a form id from here. |
Get lead form (yekar.facebook-lead-ads.get-lead-form) | Read | One lead form with its QUESTIONS - each question's key, label, type and any preset options. The keys matter: a lead's answers are named by these keys, and custom questions get generated keys that look nothing like their labels, so read this before trying to interpret lead field names. |
List leads (yekar.facebook-lead-ads.list-leads) | Read | A page of leads submitted through one form, newest first, each with its answers and the ad, ad set and campaign that produced it. Meta deletes lead data after 90 days - an empty result for an older window means the data is gone, not that nobody submitted, and this tool says which case you are in. |
Get lead (yekar.facebook-lead-ads.get-lead) | Read | One lead by id, with every answer and the ad that produced it. This is what a leadgen webhook is for: the webhook carries only the lead id, and this call fetches the answers. A lead older than Meta's 90-day retention reads as not found because Meta has deleted it. |
List subscribed apps (yekar.facebook-lead-ads.list-subscribed-apps) | Read | Which apps receive this Page's webhooks, and which fields each is subscribed to. receivesLeadgen true means new leads are pushed to that app in real time; false means leads exist only to be polled. Check this before concluding that a missing webhook is a delivery problem. |
Subscribe page webhooks (yekar.facebook-lead-ads.subscribe-page-webhooks) | Write | Subscribe this token's app to a Page's webhooks so new leads are pushed in real time instead of polled. It subscribes the app the token belongs to - there is no app to pick. Delivery also needs a callback URL configured on that app in Meta's settings, which this cannot check. |
Unsubscribe page webhooks (yekar.facebook-lead-ads.unsubscribe-page-webhooks) | Write | Stop this token's app receiving a Page's webhooks. Meta removes the entire subscription rather than one field, so leads stop being pushed and can only be polled afterwards - and only for as long as Meta retains them. |
Notes
- Decide which token to use. For an unattended automation the right answer is almost always a Business Manager SYSTEM USER token: Business settings → Users → System users → Add, assign the Page (with Manage or Lead access) and the ad account, then Generate new token.
- Select these permissions when generating it:
leads_retrieval,pages_show_list,pages_read_engagement, andpages_manage_metadataif Yekar.AI should manage webhook subscriptions.ads_managementis needed to see the ad and campaign a lead came from. - A Page access token works too, provided it is long-lived. A short-lived user token from the Graph API Explorer does NOT - it expires in about an hour and cannot read leads.
- Paste the token here, then call Whoami and Debug token: the first says whether it is a page or system-user token, the second says its scopes and whether it expires.
- Add one credential per Meta business or page set. Remember Meta only retains lead data for 90 days - anything older has to be exported and stored before it disappears.