Appearance
lead-ads
8 endpoints.
GET /api/v1/lead-ads/pages/{account_id}
List Pages
List Facebook Pages with their connected Instagram accounts.
Cache-first: the page picker needs to render fast and shouldn't re-hit Meta (and risk rate-limiting) on every open, so a recent result is served straight from Redis. Pass ?refresh=1 to force a live re-fetch. On the cold path the per-page Instagram lookups run concurrently instead of one-at-a-time.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
refresh | query | no | boolean |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/lead-ads/sync/{account_id}
Sync Lead Forms
Import all lead forms from Meta for every Page the user manages.
Uses each Page's own access token so that forms created via both Facebook and Instagram lead ads are returned.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/lead-ads/forms/{account_id}
List Lead Forms
List locally stored lead forms for an account.
Each form's usage_status reflects whether it is attached to an ad: ACTIVE (delivering ad), PAUSED (attached only to paused ads), or NOT_IN_USE (no ad references it). The Meta form status is returned separately and still drives archive/selectable-for-ads logic.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/lead-ads/forms/{account_id}/{page_id}
Create Lead Form
Create a lead generation form on a Facebook Page.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
page_id | path | yes | string |
Request body
json
{
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"questions": {
"items": {
"properties": {
"type": {
"type": "string",
"title": "Type"
},
"key": {
"type": "string",
"title": "Key"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label"
},
"options": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/QuestionOption"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Options"
}
},
"type": "object",
"required": [
"type",
"key"
],
"title": "Question"
},
"type": "array",
"title": "Questions"
},
"privacy_policy": {
"properties": {
"url": {
"type": "string",
"title": "Url"
},
"link_text": {
"type": "string",
"title": "Link Text",
"default": "Privacy Policy"
}
},
"type": "object",
"required": [
"url"
],
"title": "PrivacyPolicy"
},
"locale": {
"type": "string",
"title": "Locale",
"default": "en_US"
},
"follow_up_action_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Follow Up Action Url"
},
"thank_you_page": {
"anyOf": [
{
"properties": {
"title": {
"type": "string",
"title": "Title"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Body"
},
"button_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Button Type"
},
"button_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Button Text"
},
"website_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Website Url"
},
"enable_messenger": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Messenger"
}
},
"type": "object",
"required": [
"title"
],
"title": "ThankYouPage"
},
{
"type": "null"
}
]
},
"context_card": {
"anyOf": [
{
"properties": {
"title": {
"type": "string",
"title": "Title"
},
"content": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Content"
},
"style": {
"type": "string",
"title": "Style",
"default": "PARAGRAPH_STYLE"
}
},
"type": "object",
"required": [
"title"
],
"title": "ContextCard"
},
{
"type": "null"
}
]
},
"is_optimized_for_quality": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Optimized For Quality"
},
"block_display_for_non_targeted_viewer": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Block Display For Non Targeted Viewer"
},
"tracking_parameters": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tracking Parameters"
}
},
"type": "object",
"required": [
"name",
"questions",
"privacy_policy"
],
"title": "LeadFormCreate"
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/lead-ads/forms/{account_id}/{page_id}/{form_id}/archive
Archive Lead Form
Archive a lead form (cannot be deleted, only archived/reactivated).
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
page_id | path | yes | string | |
form_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/lead-ads/forms/{account_id}/{form_id}/leads
Get Form Leads
Retrieve submitted leads for a specific lead form.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
form_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}GET /api/v1/lead-ads/forms/{account_id}/{form_id}/details
Get Form Details
Fetch a lead form's complete definition live from Meta.
Returns the full question set (prefilled + custom, with labels and multiple-choice options) so the View modal shows every question the form asks — even if the locally-stored copy is partial or stale. The fresh questions are written back to the local record so the grid stays in sync.
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string | |
form_id | path | yes | string |
200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}POST /api/v1/lead-ads/create/{account_id}
Create Lead Ad
Create a complete lead ad in one call:
- Lead generation form on the Page
- Campaign with OUTCOME_LEADS objective
- Ad set with LEAD_GENERATION optimization
- Ad creative referencing the lead form
- Ad linking creative to the ad set
Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
account_id | path | yes | string |
Request body
json
{
"properties": {
"form_name": {
"type": "string",
"title": "Form Name"
},
"questions": {
"items": {
"properties": {
"type": {
"type": "string",
"title": "Type"
},
"key": {
"type": "string",
"title": "Key"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Label"
},
"options": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/QuestionOption"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Options"
}
},
"type": "object",
"required": [
"type",
"key"
],
"title": "Question"
},
"type": "array",
"title": "Questions"
},
"privacy_policy": {
"properties": {
"url": {
"type": "string",
"title": "Url"
},
"link_text": {
"type": "string",
"title": "Link Text",
"default": "Privacy Policy"
}
},
"type": "object",
"required": [
"url"
],
"title": "PrivacyPolicy"
},
"locale": {
"type": "string",
"title": "Locale",
"default": "en_US"
},
"follow_up_action_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Follow Up Action Url"
},
"thank_you_page": {
"anyOf": [
{
"properties": {
"title": {
"type": "string",
"title": "Title"
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Body"
},
"button_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Button Type"
},
"button_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Button Text"
},
"website_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Website Url"
},
"enable_messenger": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Messenger"
}
},
"type": "object",
"required": [
"title"
],
"title": "ThankYouPage"
},
{
"type": "null"
}
]
},
"context_card": {
"anyOf": [
{
"properties": {
"title": {
"type": "string",
"title": "Title"
},
"content": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Content"
},
"style": {
"type": "string",
"title": "Style",
"default": "PARAGRAPH_STYLE"
}
},
"type": "object",
"required": [
"title"
],
"title": "ContextCard"
},
{
"type": "null"
}
]
},
"is_optimized_for_quality": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Optimized For Quality"
},
"block_display_for_non_targeted_viewer": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Block Display For Non Targeted Viewer"
},
"tracking_parameters": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Tracking Parameters"
},
"campaign_name": {
"type": "string",
"title": "Campaign Name"
},
"daily_budget": {
"type": "integer",
"title": "Daily Budget"
},
"special_ad_categories": {
"items": {
"type": "string"
},
"type": "array",
"title": "Special Ad Categories",
"default": []
},
"adset_name": {
"type": "string",
"title": "Adset Name"
},
"targeting": {
"properties": {
"geo_locations": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Geo Locations"
},
"age_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Age Min"
},
"age_max": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Age Max"
},
"genders": {
"anyOf": [
{
"items": {
"type": "integer"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Genders"
},
"publisher_platforms": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Publisher Platforms"
},
"custom_audiences": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Custom Audiences"
},
"interests": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Interests"
}
},
"type": "object",
"title": "TargetingSpec"
},
"billing_event": {
"type": "string",
"title": "Billing Event",
"default": "IMPRESSIONS"
},
"optimization_goal": {
"type": "string",
"title": "Optimization Goal",
"default": "LEAD_GENERATION"
},
"bid_amount": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Bid Amount"
},
"start_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Start Time"
},
"end_time": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "End Time"
},
"ad_name": {
"type": "string",
"title": "Ad Name"
},
"page_id": {
"type": "string",
"title": "Page Id"
},
"creative_message": {
"type": "string",
"title": "Creative Message"
},
"creative_link": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative Link"
},
"creative_image_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative Image Hash"
},
"creative_image_url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Creative Image Url"
},
"call_to_action_type": {
"type": "string",
"title": "Call To Action Type",
"default": "SIGN_UP"
}
},
"type": "object",
"required": [
"form_name",
"questions",
"privacy_policy",
"campaign_name",
"daily_budget",
"adset_name",
"targeting",
"ad_name",
"page_id",
"creative_message"
],
"title": "LeadAdCreate",
"description": "Full lead ad creation: form + campaign + ad set + creative + ad."
}200 — Successful Response
json
{}422 — Validation Error
json
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}