Meta Ads: leads, audiences and conversions

Lead forms and their leads, audiences, customer lists, and sending conversions to a pixel. 11 tools. This page is generated from the server's own tool list, version 0.1.0, and is not edited by hand. The descriptions are the ones your AI client reads, so they are written for it. All tools lists every page.

meta_ads_list_audiences

Kind: read. It is marked as changing nothing.

List the audiences of a Meta ad account, with Meta's rough size for each and whether it is ready to use.

"custom" lists custom audiences and lookalikes: an audience_id from here goes in an ad set's targeting (custom_audiences, excluded_custom_audiences); one with takes_rows true is a customer list, which meta_ads_upload_customer_list fills. "saved" lists the saved audiences made in Ads Manager, each with its targeting; they can be read but not made or used by id from here.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
kind	text	no	"custom"	"custom" (default; includes lookalikes) or "saved".
limit	whole number	no	25	Rows per page (1-100).
after	text	no	none	next_after from the previous page.

meta_ads_list_lead_forms

Kind: read. It is marked as changing nothing.

List the lead forms (instant forms) of a Facebook Page: each form's id, name, status, language, questions and how many leads it has collected. The form_id is what meta_ads_create_creative takes as lead_form_id and meta_ads_get_leads reads from.

Argument	Type	Required	Default	Description
page_id	text	yes		Facebook Page id from meta_list_accounts.
include_archived	true or false	no	false	Also show archived forms.
limit	whole number	no	25	Rows per page (1-100).
after	text	no	none	next_after from the previous page.

meta_ads_get_leads

Kind: read. It is marked as changing nothing.

Read the leads a lead form, or one ad, has collected: each person's answers, when they sent them, and the ad they came from. Newest first, one page per call.

A lead is a person's contact details. This works only where an administrator has allowed reading leads, for a person with write access whose Meta connection holds leads_retrieval. Nothing is stored on this server: its activity log keeps where the leads were read from and how many. Call it only when the user asks for leads, show them to that user, and send them nowhere else unless the user asks for exactly that. Meta keeps a lead for 90 days.

Argument	Type	Required	Default	Description
form_id	text	no	none	A lead form, from meta_ads_list_lead_forms. Needs page_id. Or:
page_id	text	no	none	The Page the form is on.
ad_id	text	no	none	An ad, from meta_ads_list. Needs ad_account_id.
ad_account_id	text	no	none	The ad account the ad is in.
since	text	no	none	Only leads sent after this time, ISO 8601 with an offset, e.g. 2026-10-01T00:00:00+03:00. Without an offset it is read as UTC.
limit	whole number	no	25	Leads per page (1-100, default 25).
after	text	no	none	next_after from the previous page.

meta_ads_create_lead_form

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a lead form (instant form) on a Facebook Page: the form a lead ad opens, on Meta, in place of a website. Give its id to meta_ads_create_creative as lead_form_id.

The dry run is this server's own preflight: Meta has no validate-only mode for a form and has not seen it, so do not call it validated. A form cannot be edited once made: to change one, create a new form under another name and archive the old one. It cannot be deleted either, only archived.

Argument	Type	Required	Default	Description
page_id	text	yes		Facebook Page id from meta_list_accounts. You need the advertising role on it.
name	text	yes		The form's name, seen only by the people who manage the Page. Unique on the Page.
questions	list of Question	yes		What the form asks, in order. Each is {"type": ...}: a standard type Meta fills in from the person's profile (FULL_NAME, EMAIL, PHONE, COMPANY_NAME, JOB_TITLE, CITY, COUNTRY and others), or CUSTOM with a label, and options for a multiple-choice question. Labels and options may be in any language.
privacy_policy_url	text	yes		The advertiser's privacy policy, which Meta requires on every form.
privacy_link_text	text	no	none	The words of the link to it. The address is shown if left out.
locale	text	no	none	The language of the form's own buttons and labels, e.g. AR_AR, EN_US, EN_GB, FR_FR. Meta chooses if left out.
form_type	text	no	"more_volume"	"more_volume" (default) or "higher_intent", which adds a review step before sending.
intro	Intro	no	none	What is shown before the questions: {"title", and "text" or "bullets"}.
thank_you	ThankYou	no	none	What is shown after sending: {"title", "body", "button", "button_text", "website_url"}. Meta shows its own if left out.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_set_lead_form_status

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Archive a lead form, or make an archived one active again. An archived form collects no leads, so pause the ads that use it first. Meta has no delete for a form, and none is offered here; archiving can be undone.

The dry run is this server's own preflight: nothing is sent to Meta.

Argument	Type	Required	Default	Description
page_id	text	yes		The Page the form is on.
form_id	text	yes		From meta_ads_list_lead_forms.
status	text	yes		"ARCHIVED" or "ACTIVE".
dry_run	true or false	no	true	true = preflight only (default). false = change it, after the user confirms.

meta_ads_create_custom_audience

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a Meta custom audience: people who already did something, to show ads to or to keep ads away from. It spends nothing by itself.

The dry run is this server's own preflight: Meta has no validate-only mode for an audience and has not seen it, so do not call it validated. An audience of people the advertiser names (a customer list) is meta_ads_create_customer_list.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The audience's name.
source	text	yes		What the people did: "website" - visited the website (pixel_id; optionally url_contains or event). "page" - engaged with the Facebook Page (page_id). "instagram" - engaged with the Instagram account (instagram_user_id). "lead_form" - opened or sent a lead form (lead_form_id and its page_id). "video" - watched videos (video_ids).
retention_days	whole number	no	30	How far back to look: up to 180 for website, 365 for page and video, 730 for instagram, 90 for lead_form. Default 30.
event	text	no	none	Which action counts. website: a pixel event such as Lead (default: any visit). page: page_engaged (default), page_visited, page_liked, page_messaged, page_cta_clicked, page_or_post_save, page_post_interaction. instagram: ig_business_profile_all (default), ig_business_profile_engaged, ig_user_messaged_business, ig_business_profile_visit, ig_business_profile_ad_saved. lead_form: lead_generation_submitted (default), lead_generation_opened, lead_generation_dropoff (opened, not sent). video: video_watched (3 seconds, default), video_view_10s, video_view_15s, video_view_25_percent, video_view_50_percent, video_view_75_percent, video_completed (95%).
pixel_id	text	no	none	website: one of the ad account's pixels.
url_contains	list of text	no	none	website: only visits to an address containing any of these parts.
page_id	text	no	none	page, lead_form: one of the ad account's pages.
instagram_user_id	text	no	none	instagram: one of the ad account's instagram_accounts.
lead_form_id	text	no	none	lead_form: from meta_ads_list_lead_forms.
video_ids	list of text	no	none	video: up to 50 video ids, from meta_ads_list_videos or the Page's videos.
description	text	no	none	A note kept with the audience.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_create_lookalike

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a Meta lookalike audience: the people in one country most similar to those in a custom audience of this ad account. It spends nothing by itself, and takes Meta one to six hours to fill.

The dry run is this server's own preflight: Meta has not seen it, so do not call it validated.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
source_audience_id	text	yes		A custom audience of this account, from meta_ads_list_audiences. Meta needs at least 100 of its people in the country.
country	text	yes		Two-letter country code, e.g. KW. One this installation may target.
ratio	number	no	0.01	The share of the country's people to take: 0.01 (the 1% most similar, default) to 0.20, in steps of 0.01.
name	text	no	none	The audience's name. One is made if left out.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_delete_audience

Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.

Delete a custom or lookalike audience. It cannot be undone, and Meta stops for good any ad that uses a deleted audience - so it is refused while a running ad set uses the audience, or while a lookalike built from it exists. Prefer leaving an unused audience alone: it costs nothing. Delete only when the user asked for a delete.

The dry run is this server's own preflight: it reads the audience and the ad sets that name it, and sends nothing.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
audience_id	text	yes		From meta_ads_list_audiences.
confirm_remove	true or false	no	false	Must be true, and only when the user asked for a delete.
dry_run	true or false	no	true	true = preflight only (default). false = delete it, after the user confirms.

meta_ads_send_conversion_events

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Tell Meta which leads became customers: send conversions from the advertiser's own records (a CRM, a sales sheet) to a pixel (dataset) of the ad account, through Meta's Conversions API, so Meta can count them for the ads that brought them.

hashed=true keeps plain contact details out of this conversation altogether: give email, phone, names and places already SHA-256 hashed by Meta's rules and they are checked to be hashes and passed on. Better still, give Meta's own lead_id (from meta_ads_get_leads or leads_export) and no contact detail at all. Otherwise the details are normalised and hashed on this server before they are sent. Either way nothing of a row is stored: the activity log keeps how many rows went in, how many were sent or left out and why, and a file's hash and size. These are people's contact details: send them only when the user asked for this file or list to be sent, and never repeat them elsewhere.

A row with a lead_id is sent as a stage of that lead in the CRM: event_name is the stage in the CRM's own words ("Qualified", "Converted") and crm_name the system it comes from. A row without one needs an email or a phone and one of Meta's standard events as event_name (Lead, Purchase, CompleteRegistration, Contact, Schedule, SubmitApplication, Subscribe, StartTrial ...; a Purchase needs a value).

Sending the same events twice may count them twice: Meta does not remove a duplicate sent this way. A file already sent to the pixel from here is refused unless resend=true; a list given in events cannot be recognised again, so never send one a second time without the user saying so. If the answer is partly_applied, some batches went and some did not: say which rows, and send only those again.

The dry run is this server's own preflight: nothing is sent, and Meta has validated nothing. A test_event_code is not a dry run: it needs dry_run=false, really sends, and Meta counts those events too. Works only where an administrator has allowed sending conversions, for a person with write access.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
pixel_id	text	yes		A pixel of that ad account, from meta_ads_list_pixels.
events	list of object	no	none	Up to 2,000 rows in the call, each {"event_name", "event_time", "lead_id"?, "email"?, "phone"?, "first_name"?, "last_name"?, "city"?, "state"?, "zip"?, "country"?, "external_id"?, "value"?, "currency"?, "event_id"?, "crm_name"?}. event_time is ISO 8601 with an offset (2026-10-01T09:30:00+03:00; without one it is UTC) or a Unix time, within the last 7 days (62 for physical_store): an older row refuses the call by its number. value is in currency, else the ad account's currency. country is two letters. external_id is the advertiser's own id for the person, in the form the website's pixel sends it.
path	text	no	none	Instead of events: a UTF-8 CSV with those columns in its first row, inside one of the server's data folders (server_status lists them).
hashed	true or false	no	false	The email, phone, names and places are SHA-256 hashes already.
calling_code	text	no	none	The country's dialling code (966, 20) for phone numbers written without one. A number with + or 00 in front is taken as it is.
event_name	text	no	none	For rows that have none of their own.
crm_name	text	no	none	The system the lead stages come from (HubSpot, Odoo, "In-house CRM"), for rows that have none of their own. Needed with a lead_id.
action_source	text	no	"system_generated"	Where the conversions of rows without a lead_id happened: system_generated (default), physical_store, phone_call, email, chat or other.
test_event_code	text	no	none	The code Events Manager shows under Test Events. Still a send.
resend	true or false	no	false	Send a file again that was already sent to this pixel from here.
dry_run	true or false	no	true	true = preflight only (default). false = send, after the user confirms.

meta_ads_create_customer_list

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create an empty Meta customer list: an audience of people the advertiser names from its own records, to keep ads away from existing customers, to reach them, or to build a lookalike from. It spends nothing; fill it with meta_ads_upload_customer_list.

The people put in it must be people the advertiser may lawfully target, which is the user's to confirm, and you must have accepted Meta's Custom Audience terms for the ad account (the refusal carries Meta's link). Meta flags a list whose name suggests a health condition or a financial status. The dry run is this server's own preflight: Meta has not seen it, so do not call it validated. Works only where an administrator has allowed customer lists, for a person with write access.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
name	text	yes		The list's name, for what it is to the business ("Customers 2026").
description	text	no	none	A note kept with the list.
customer_file_source	text	no	"USER_PROVIDED_ONLY"	Where the list's data came from, as Meta is told: USER_PROVIDED_ONLY (default: collected by the advertiser directly from its customers), PARTNER_PROVIDED_ONLY or BOTH_USER_AND_PARTNER_PROVIDED. Ask the user if it is not their own customers' data.
dry_run	true or false	no	true	true = check here without sending anything (default). false = create it, only after the user confirms.

meta_ads_upload_customer_list

Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.

Add people to a Meta customer list, take them out, or replace everyone in it.

hashed=true keeps plain contact details out of this conversation altogether: give email, phone, names and places already SHA-256 hashed by Meta's rules and they are checked to be hashes and passed on. A path to a CSV in one of the server's data folders does the same. Otherwise the details are normalised and hashed on this server before they are sent. Either way nothing of a row is stored: the activity log keeps how many rows went in, how many were sent or left out and why, and a file's hash and size. These are people's contact details: send them only when the user asked for this file or list to be uploaded, and never repeat them elsewhere. The people must be ones the advertiser may lawfully target; that is the user's to confirm.

Adding a person already in the list changes nothing. mode="remove" takes the rows' people out, and mode="replace" takes out everyone who is not in the rows: both need confirm_remove=true, because running ads may be using the list. If the answer is partly_applied, some batches went and some did not: say which rows and what the note says. Meta says nothing back about who it matched, and shows ads to a list only once it has matched 100 people.

The dry run is this server's own preflight: nothing is sent, and Meta has validated nothing. Works only where an administrator has allowed customer lists, for a person with write access who has accepted Meta's Custom Audience terms for the ad account.

Argument	Type	Required	Default	Description
ad_account_id	text	yes		From meta_ads_list_accounts.
audience_id	text	yes		A customer list of that account: one with takes_rows true in meta_ads_list_audiences, or made with meta_ads_create_customer_list.
rows	list of object	no	none	Up to 2,000 rows in the call, each {"email"?, "phone"?, "first_name"?, "last_name"?, "city"?, "state"?, "zip"?, "country"?}: a row needs an email or a phone number. country is two letters.
path	text	no	none	Instead of rows: a UTF-8 CSV with those columns in its first row, inside one of the server's data folders (server_status lists them).
hashed	true or false	no	false	The values are SHA-256 hashes already.
calling_code	text	no	none	The country's dialling code (966, 20) for phone numbers written without one. A number with + or 00 in front is taken as it is.
mode	text	no	"add"	"add" (default), "remove" or "replace".
confirm_remove	true or false	no	false	Must be true to remove or replace, and only when the user asked.
dry_run	true or false	no	true	true = preflight only (default). false = send, after the user confirms.

Objects the arguments take

An argument whose type is a name takes an object with these fields.

Question

One question of a lead form.

Field	Type	Required	Default	Description
type	text	yes		FULL_NAME, FIRST_NAME, LAST_NAME, EMAIL, WORK_EMAIL, PHONE, WORK_PHONE_NUMBER, COMPANY_NAME, JOB_TITLE, CITY, STATE, PROVINCE, COUNTRY, POST_CODE, ZIP, STREET_ADDRESS, DOB, GENDER or WEBSITE (Meta fills these in from the person's profile), or CUSTOM for a question of your own.
label	text	no	none	CUSTOM only: the question as the person reads it, in any language.
options	list of text	no	none	CUSTOM only: the answers to choose from. Left out, the person types a short answer.
key	text	no	none	CUSTOM only: the name the answer carries in a lead (lower-case letters, digits, underscores). Made up if left out.

Intro

What the form shows before its questions.

Field	Type	Required	Default	Description
title	text	yes
text	text	no	none	One paragraph. Or:
bullets	list of text	no	none	Up to five short points.
button_text	text	no	none

ThankYou

What the form shows after it is sent.

Field	Type	Required	Default	Description
title	text	yes
body	text	no	none
button	text	no	"VIEW_WEBSITE"	VIEW_WEBSITE (needs website_url), CALL_BUSINESS (needs phone_number and country_code) or VIEW_ON_FACEBOOK.
button_text	text	no	none
website_url	text	no	none
phone_number	text	no	none
country_code	text	no	none	The phone number's country, two letters, e.g. KW.