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:

The ads_management permission

The pages_manage_ads permission

The pages_read_engagement permission

The pages_show_list permission

A Page access token from a person who can perform the ADVERTISE task on the Page

Step 1. Create a campaign

To 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 token

buying_type set to AUCTION

name set to the name for your campaign

objective set to OUTCOME_LEADS

special_ad_categories set to NONE or your special ad catergory

status set to PAUSED

Example Request

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.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.

Step 2. Create an ad set

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 token

bid_amount set to the maximum amout your want to pay

billing_event set to IMPRESSIONS

campaign_id set to the ID for your ad campaign from Step 1

daily_budget set to the amount you want to spend per day

name set to the name for your ad set

optimization_goal set to LEAD_GENERATION, or QUALITY_LEAD

destination_type set to ON_AD

promoted_object – set to the ID for your business’ Facebook Page

status 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.

Example Request

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.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.

Step 3. Create a Lead Form

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 token

name set to the name for your form

questions set to an array of objects defining the type of questions and the order they will appear in the form using the key parameter

a custom question using the label parameter

a custom question using the options parameter with a dropdown menu of answers

Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X POST "https://graph.facebook.com/v25.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 for Messenger Conversations

Forms that you want to use in an ad in a Messenger conversation must contain the following:

The questions.type parameter can only be set to one of the following values:

CUSTOM

EMAIL

FIRST_NAME

FULL_NAME

LAST_NAME

PHONE

If the form has a questions.type that is set to any other value than those listed, the form will be ineligible.

The block_display_for_non_targeted_viewer parameter must be set to false. This marks the form as Open Sharing.

Eligible Messenger Lead Form Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X POST "https://graph.facebook.com/v25.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"},
                   ]}
           ]"
         }'

Additional Question Types

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:

Appointment Scheduling - An appointment scheduling question renders a date and time selector with a limited hour selection and a confirmation message below the question.

National or Government ID – A national ID question renders a question based on a person’s country and validates the format of the ID entered.

Store Locator - A store locator question renders a store locator selector based on a person’s zip code or postal code input.

Appointment Scheduling

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."
               },
...

National ID

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:

Argentina – {“type”: “ID_AR_DNI”}

Brazil – ID_CPF

Chile – ID_CL_RUT

Colombia – ID_CO_CC

Ecuador – ID_EC_CI

Peru – ID_PE_DNI

To add a national ID question, add a question object with the type parameter set to the person’s country type.

Limitations

You can only ask for a single National ID in any given form and are only able to target people in their corresponding country. For example, if you ask for DNI from Peru, your target audience must be limited to Peru. Only ads that match this criteria are approved.

Validation checks for a valid format; it does not verify that the ID actually belongs to a real person.

...
           "questions": "[
               ...
               {"type": "ID_AR_DNI"
               },
...

Store Locator

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"
               },
...

Advanced Form Settings

Get higher quality leads by adding one or more of the following form settings:

Form Performance Tracking to track the source of your leads

Higher Intent Forms to add a review and confirm step in the form flow

Organic Leads Filtering to filter out organic leads

Gated Content to reward consumers with a file download after submitting their lead

Add Performance Tracking

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.

Example Request

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "tracking_parameters": {"your_tracking_parameter_name":"your_tracking_parameter_value"},
           "questions": "[
...

Add Higher Intent Setting

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.

Example Request

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "is_optimized_for_quality": "true",
           "questions": "[
...

Filter Out Organic Leads

To filter out organic leads, add the block_display_for_non_targeted_viewer parameter to true when you create the form.

Example Request

Formatted for readability. Replace bold, italics values with your values.

...
           "name": "YOUR_LEADADS_FORM_NAME",
           "block_display_for_non_targeted_viewer": "true",
           "questions": "[
...

Example Response

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",
}

Gated Content

Reward consumers with a file download after submitting their lead. This file download will appear as a call-to-action button on your thank you page.

To add this feature, you must add the upload_gated_file parameter to your form with the file that you’d like to upload.

In addition, you must create a thank you page using the thank_you_page parameter. Within the thank_you_page parameter, set button_type to VIEW_ON_FACEBOOK.

Example Request

Formatted for readability. Replace bold, italics values with your values.

...
  "name": "YOUR_LEADADS_FORM_NAME",
      "upload_gated_file": "YOUR_FILE",
      "thank_you_page": {
         "body": "Feel free to download our brochure here",
         "title": "Thanks, you're all set.",
         "button_type": "VIEW_ON_FACEBOOK",
         "button_text": "Download"
      }
    ...

Example Response

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",
}

Step 4. Create an Ad Creative

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 token

object_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 ID

description set to the description for your creative

image_hash set to the hash for an image for your ad creative

message set to the text for your ad creative

page_id set to your Facebook Page ID

Note: 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

Example Request

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

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"
         }'

With a Carousel

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

With a Video

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/v25.0/act_<AD_ACCOUNT_ID>/adcreatives

Ad Creative Example Response

On success your app receives the following JSON response with the ID for the ad creative.

{
  "id": "YOUR_AD_CREATIVE_ID"
}

Step 5. Create the Ad

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 token

adset_id (from Step 2)

creative_id (from Step 4)

name

status

Ad with Creative Example Request

Formatted for readability. Replace bold, italics values, such as AD_ACCOUNT_ID, with your values.

curl -X POST "https://graph.facebook.com/v25.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"
}

Step 6. Publish your Ad

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.

Form Management

Get a list of your forms, a specific forms questions, and archive old forms.

Get a List of 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 token

fields (optional) set to a comma separated list of fields to get specific information such as name and form ID

Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.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.

Get a List of Eligible Forms for Messenger

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 token

fields set to is_eligible_for_in_thread_forms

Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.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"
    }
  ],
...
}

Get a List of Questions

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 token

fields set to questions

Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.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.

Archive a Form

You can only archive a lead form since deleting is not supported. Once a form is archived:

The form won’t appear (by default) in the Forms Library

You can’t use an archived form in an ad, attempting to do so can generate an error via the API.

Archived forms won’t be available during ad creation for CF or PE.

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 token

status set to ARCHIVED

Example Request

Formatted for readability. Replace bold, italics values with your values.

curl -X GET "https://graph.facebook.com/v25.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.

Lead Forms for Ads

Before You Start

Step 1. Create a campaign

Example Request

Step 2. Create an ad set

Example Request

Step 3. Create a Lead Form

Example Request

Forms for Messenger Conversations

Eligible Messenger Lead Form Example Request

Additional Question Types

Appointment Scheduling

National ID

Limitations

Store Locator

Advanced Form Settings

Add Performance Tracking

Example Request

Add Higher Intent Setting

Example Request

Filter Out Organic Leads

Example Request

Example Response

Gated Content

Example Request

Example Response

Step 4. Create an Ad Creative

Example Request

With a Carousel

With a Video

Ad Creative Example Response

Step 5. Create the Ad

Ad with Creative Example Request

Step 6. Publish your Ad

Form Management

Get a List of Forms

Example Request

Get a List of Eligible Forms for Messenger

Example Request

Get a List of Questions

Example Request

Archive a Form

Example Request

See Also

Marketing API Developer Documentation

Meta Business Help Center