This document describes how to use the Marketing API to can create ads for lead generation using the Graph API.
To create and publish a lead ad you will follow these steps:
This guide assumes you have read the Messenger Platform Overview and implemented the needed components for sending and receiving messages and notifications.
You will need the following:
ads_management
permissionpages_manage_ads
permissionpages_read_engagement
permissionpages_show_list
permissionADVERTISE
task on the PageTo create an ad campaign for your lead generation ads, send a POST
request to the /
act_AD_ACCOUNT_ID
/campaigns
endpoint with the following parameters:
access_token
set to your Page access tokenbuying_type
set to AUCTION
name
set to the name for your campaignobjective
set to OUTCOME_LEADS
status
set to PAUSED
curl -X POST "https://graph.facebook.com/v21.0
/act_AD_ACCOUNT_ID/campaigns" \
-H "Content-Type: application/json" \
-d '{
"access_token":"YOUR_PAGE_ACCESS_TOKEN",
"buying_type":"AUCTION",
"name":"YOUR_LEADADS_CAMPAIGN_NAME",
"objective":"OUTCOME_LEADS",
"special_ad_categories":["NONE"],
"status":"PAUSED"
}'
On success, your app will receive a JSON object with the ID for your campaign. This ID will be used when creating an ad set in the next step.
{ "id": "YOUR_CAMPAIGN_ID" }
Visit the Ad Campaigns reference to learn more.
To create an ad set, send a POST
request to the act_ad_account_id/adsets
endpoint where ad_account_id is the ID for your Meta ad account. Your request must include:
access_token
set to your Page access tokenbid_amount
set to the maximum amout your want to paybilling_event
set to IMPRESSIONS
campaign_id
set to the ID for your ad campaign from Step 1daily_budget
set to the amount you want to spend per dayname
set to the name for your ad setoptimization_goal
set to LEAD_GENERATION
, or QUALITY_LEAD
destination_type
set to ON_AD
promoted_object
– set to the ID for your business' Facebook Pagestatus
set to PAUSED
Note: If you have set up a CRM data source and choose QUALITY_LEAD
as an optimization goal, you may add the pixel_id
to the promoted_object
for further optimization on quality. Note that you do not need to supply a pixel_rule
alongside with the pixel_id
.
curl -X POST "https://graph.facebook.com/v21.0
/act_AD_ACCOUNT_ID/adsets"
-H "Content-Type: application/json"
-d '{
"access_token":"YOUR_PAGE_ACCESS_TOKEN",
"bid_amount":"YOUR_BID_AMOUNT",
"billing_event":"IMPRESSIONS",
"campaign_id":"YOUR_CAMPAIGN_ID",
"daily_budget":"YOUR_DAILY_BUDGET",
"name:"YOUR_LEADADS_ADSET_NAME",
"optimization_goal":"LEAD_GENERATION",
"destination_type":"ON_AD",
"promoted_object":"YOUR_PAGE_ID",
"status":"PAUSED"
}'
On success your app receives the following JSON response with the ID for the ad set.
{ "id": "YOUR_ADSET_ID" }
Visit the Ad Sets reference to learn more.
To create a form send a POST
request to the /
PAGE_ID
/leadgen_forms
endpoint with the following parameters:
access_token
set to your Page access tokenname
set to the name for your formquestions
set to an array of objects defining the type of questions and the order they will appear in the form using the key
parameter
label
parameteroptions
parameter with a dropdown menu of answers
curl -X POST "https://graph.facebook.com/v21.0
/PAGE_ID/leadgen_forms" \
-H "Content-Type: application/json" \
-d '{
"access_token": "YOUR_PAGE_ACCESS_TOKEN",
"name": "YOUR_LEADADS_FORM_NAME",
"questions": "[
{"type":"FULL_NAME", "key": "question1"},
{"type":"EMAIL", "key": "question2"},
{"type":"PHONE", "key": "question3"},
{"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
{"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?",
"options": [
{value: "Red", key: "key1"},
{value: "Green", key: "key2"},
{value: "Blue", key: "key2"},
]}
]"
}'
Forms that you want to use in an ad in a Messenger conversation must contain the following:
questions.type
parameter can only be set to one of the following values:
|
|
|
If the form has a questions.type
that is set to any other value than those listed, the form will be ineligible.
block_display_for_non_targeted_viewer
parameter must be set to false
. This marks the form as Open Sharing.
curl -X POST "https://graph.facebook.com/v21.0
/PAGE_ID/leadgen_forms" \
-H "Content-Type: application/json" \
-d '{
"access_token": "YOUR_PAGE_ACCESS_TOKEN"
"block_display_for_non_targeted_viewer": "false"
"name": "LeadAds Form for Messenger Conversation Name"
"questions": "[
{"type":"FULL_NAME", "key": "question1"},
{"type":"EMAIL", "key": "question2"},
{"type":"PHONE", "key": "question3"},
{"type":"CUSTOM", "key": "question4" "label": "Do you like rainbows?"}
{"type":"CUSTOM", "key": "question5" "label": "What is your favorite color?",
"options": [
{value: "Red", key: "key1"},
{value: "Green", key: "key2"},
{value: "Blue", key: "key2"},
]}
]"
}'
In addition to the typical question types shown in the [Create a Lead Form section]{#create-a-lead-form}, you can add more speciaized question types for the following use cases:
An appointment scheduling question renders a date and time selector with a limited hour selection and a confirmation message below the question.
To add an appointment scheduling question, add a question object with the type
parameter set to DATE_TIME
. Optionally, you can also add a confirmation message in the inline_context
parameter that will be rendered directly below the question field for further context, if needed.
... "questions": "[ ... {"type": "DATE_TIME", "label": "Appointment time", "inline_context": "We will verify and call you to confirm your appointment." }, ...
A national ID question renders a question based on a person's country and validates the format of the ID entered. This question can be rendered for the following countries:
ID_AR_DNI
"}ID_CPF
ID_CL_RUT
ID_CO_CC
ID_EC_CI
ID_PE_DNI
To add a national ID question, add a question object with the type
parameter set to the person's country type.
DNI
from Peru, your target audience must be limited to Peru. Only ads that match this criteria are approved.... "questions": "[ ... {"type": "ID_AR_DNI" }, ...
A store locator question renders a store locator selector based on a person's zip code or postal code input.
You will need to set up a Store Pages Structure to use this question. Learn how in Set Up a Store Pages Structure on Facebook – Meta Business Help Center
To add a store locator question, add a question object with the type
parameter set to STORE_LOOKUP
and the context_provider_type
parameter to LOCATION_MANAGER
.
... "questions": "[ ... {"type": "STORE_LOOKUP", "label": "Which store do you want to visit?", "context_provider_type": "LOCATION_MANAGER" }, ...
Get higher quality leads by adding one or more of the following form settings:
To help you track the source of your leads, add the tracking_parameters
field, set to a list of key-value pairs of parameters you want to track, to your form. These parameters do not appear in your ad but allow Meta to provide you with metadata about leads generated from a form.
... "name": "YOUR_LEADADS_FORM_NAME", "tracking_parameters": {"your_tracking_parameter_name":"your_tracking_parameter_value"}, "questions": "[ ...
By default, lead ads are optimized for the volume of leads, however, you can create forms that result in higher intent leads. These types of leads can be for people who may be interested in a specific product or service, such as booking a test drive at a dealership. This form setting adds a step to the form submission flow where a person reviews and confirms their answers before the person submits the form.
To add this confirmation flow to your form, add the is_optimized_for_quality
parameter set to true
when creating the form.
... "name": "YOUR_LEADADS_FORM_NAME", "is_optimized_for_quality": "true", "questions": "[ ...
To filter out organic leads, add the block_display_for_non_targeted_viewer
parameter to true
when you create the form.
... "name": "YOUR_LEADADS_FORM_NAME", "block_display_for_non_targeted_viewer": "true", "questions": "[ ...
On success your app will receive a JSON response containing the ID for your form to be used when creating your ad.
{ "id": "leadgen_form_id", }
To create an ad creative with an image and your form, send a POST
request to the /act_AD_ACCOUNT_ID/adcreatives
endpoint with the following parameters:
access_token
set to your Page access tokenobject_story_spec
that includes a link_data
object with the following parameters:
call_to_action
set to an object containing type
andvalue
set to your lead form IDdescription
set to the description for your creativeimage_hash
set to the hash for an image for your ad creativemessage
set to the text for your ad creativepage_id
set to your Facebook Page IDNote: While creating the link_data
, the value associated with the link
field can only be https//fb.me/
.
The link_data.call_to_action
parameter must be set to one of the following values:
APPLY_NOW
DOWNLOAD
GET_QUOTE
LEARN_MORE
SIGN_UP
SUBSCRIBE
curl -X POST "https://graph.facebook.com/LATEST-API-VERSION/act_AD_ACCOUNT_ID/adcreatives" \ -H "Content-Type: application/json" \ -d '{ "access_token":"YOUR_PAGE_ACCESS_TOKEN", "object_story_spec":{ "link_data": { "call_to_action": { "type":"SIGN_UP", "value":{ "lead_gen_form_id":"YOUR_FORM_ID" } }, "description": "YOUR_AD_CREATIVE_DESCRIPTION", "image_hash": "YOUR_IMAGE_HASH", "link": "http:\/\/fb.me\/", "message": "YOUR_AD_CREATIVE_MESSAGE" }, "page_id": "YOUR_PAGE_ID" }'
You can create a carousel lead ad using the same object_story_spec
, but with an additional lead_gen_form_id
field defined in the child_attachments
parameter.
You can only specify the same <FORM_ID>
for all child attachments.
curl \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "link_data": { "message": "My description", "link": "http:\/\/www.google.com", "caption": "WWW.EXAMPLE.COM", "child_attachments": [ { "link": "http:\/\/www.google.com", "image_hash": "<IMAGE_HASH>", "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} }, { "link": "http:\/\/www.google.com", "image_hash": "<IMAGE_HASH>", "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} }, { "link": "http:\/\/www.google.com", "image_hash": "<IMAGE_HASH>", "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} }, { "link": "http:\/\/www.google.com", "image_hash": "<IMAGE_HASH>", "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} } ], "multi_share_optimized": true, "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}} } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/LATEST-API-VERSION/act_<AD_ACCOUNT_ID>/adcreatives
You can also use a video in the lead ad creative instead of a photo. First, upload the video to your ad video library, then use it in the object_story_spec
parameter:
curl -X POST \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"link_description": "try it out",
"image_url": "<IMAGE_URL>",
"video_id": "<VIDEO_ID>",
"call_to_action": {
"type": "SIGN_UP",
"value": {
"link": "http://fb.me/",
"lead_gen_form_id": "<FORM_ID>"
}
}
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0
/act_<AD_ACCOUNT_ID>/adcreatives
On success your app receives the following JSON response with the ID for the ad creative.
{ "id": "YOUR_AD_CREATIVE_ID" }
To create the ad you need to associate the ad creative and the ad set. To create the ad, send a POST
request to the /act_AD_ACCOUNT_ID/ads
endpoint. Your request must included:
access_token
set to your Page access tokenadset_id
(from Step 2)creative_id
(from Step 4)
curl -X POST "https://graph.facebook.com/v21.0
/act_AD_ACCOUNT_ID/ads"
-H "Content-Type: application/json"
-d '{
"access_token"="YOUR_PAGE_ACCESS_TOKEN",
"name":"YOUR_LEADADS_AD_NAME",
"adset_id"="YOUR_AD_SET_ID",
"creative"={ "creative_id": "YOUR_AD_CREATIVE_ID" },
"status"="PAUSED"
}'
On success your app receives the following JSON response with the ID for the ad.
{ "id": "YOUR_AD_ID" }
Verify that your ad exists in the ads manager . Click the Review and publish button in the upper right corner. Select your campaign, the ad set for the campaign, and the ad.
You can publish your ad from the ads manager or using the API. To publish using the API, repeat Step 4 with the status
parameter set to ACTIVE
.
Your ad will be reviewed by Meta and the status will be PENDING_REVIEW
. Once approved, the status will be ACTIVE
and your ad will be delivered.
Get a list of your forms, a specific forms questions, and archive old forms.
To get a list of your lead gen forms, send a GET
request to the /
page_id
/leadgen_forms
endpoint with the following parameters:
access_token
set to your Page access tokenfields
(optional) set to a comma separated list of fields to get specific information such as name and form ID
curl -X GET "https://graph.facebook.com/v21.0
/PAGE_ID/leadgen_forms
?fields=name,id
&access_token": "YOUR_PAGE_ACCESS_TOKEN"
On success your app will receive a JSON response containing a list of your forms. You can use a form ID to get the questions for that form or to archive the form.
Only forms containing specific requirements are eligible to be sent in a Messenger conversation.
To get a list of eligible lead forms send a GET
request to the /
page_id
/leadgen_forms
endpoint with the following parameters:
access_token
set to your Page access tokenfields
set to is_eligible_for_in_thread_forms
curl -X GET "https://graph.facebook.com/v21.0
/PAGE_ID/leadgen_forms
?fields=is_eligible_for_in_thread_forms
&access_token": "YOUR_PAGE_ACCESS_TOKEN"
On success your app will receive a JSON response containing a list of IDs for eligible forms.
{ "data": [ { "id": "eligible_form_1_id" }, { "id": "eligible_form_2_id" } ], ... }
To get a list of questions for a specific lead gen form, send a GET
request to the /
page_id
/
leadgen_form_id
endpoint with the following parameters:
access_token
set to your Page access tokenfields
set to questions
curl -X GET "https://graph.facebook.com/v21.0
/page_id/leadgen_form_id
?fields=questions
&access_token=page_access_token"
On success your app will receive a JSON response containing a list of questions.
You can only archive a lead form since deleting is not supported. Once a form is archived:
To archive a specific lead gen form, send a POST
request to the /
page_id
/
leadgen_form_id
endpoint with the following parameters:
access_token
set to your Page access tokenstatus
set to ARCHIVED
curl -X GET "https://graph.facebook.com/v21.0
/page_id/leadgen_form_id
?status=ARCHIVED
&access_token=page_access_token"
On success your app will receive a JSON response containing an object with success
set to true
.
An archived form can be reactivated by sending a request with status
set to ACTIVE
.
Visit our other guides to learn more about the components in this document.