Marketing API

Retrieving Leads

You can retrieve leads with Webhooks or Bulk Read.

Before You Start

To read ad specific fields, such as ad_id or campaign_id, you will need:

To retrieve all lead data and ad level data, you will need:

Note: If the Page admin did not customize leads, nor given access permission with the Leads Access Manager, then all Page admins will have leads access permission. If leads access permission is customized by the business admins, then it depends on the business admin's configuration for whether a Page basic admin has leads access permission or not.

Rate Limits

The rate limit is 200 multiplied by 24 then multiplied by the number of leads created in the past 90 days for a Facebook Page. If you make more calls than this in a 24-hour period, your request will return an error.

Filter By Date Range

Send a GET request to the /ads/lead_gen/export_csv/ endpoint where date formats are either POSIX or UNIX timestamps.

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

Caveats

  • If from_date is not set or is less than the form creation time, the form creation time is used.

  • If to_date is not set or is greater than the present time, current time is used.

  • If any entries lack Ad IDs or Adgroup IDs in the TSV, it can be due to the following reasons:

    • The lead is generated from organic reach. In this case, is_organic in the TSV displays 1; otherwise, the value is 0.
    • The lead may be submitted from an Ad Preview.
    • The person requesting leads does not have advertiser privileges on the Ad Account.

Webhooks

Get real-time updates for lead ads.

Step 1: Get Started

Visit our Webhooks Get Started guide to set up your endpoint and configure your webhook.

Step 2: Get a Long-Lived Page Access Token

Generate a single, long-lived Page token to continuously fetch data without worrying about it expiring.

Step 3: Install Your App on the Page

Visit our Webhooks for Pages guide to learn how to install your app on a Page.

Webhook Response

On leadgen creation, your app receives the following webhook response:

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

You can use leadgen_id to retrieve data associated with the lead:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<LEAD_ID>

On success, your app receives the following response:

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
	...
}

Learn More

You can see an example of this implementation in our Github repo.

Bulk Read

The leads_retrieval permission is required to read leads.

The leads exists on both ad group and form nodes. This returns all data associated with their respective objects. Because a form can be re-used for many ads, your form could contain far more leads than an ad using it.

To read in-bulk by ad:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<AD_ID>/leads

To read by form:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

The response:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Reading Store Locator Question Value

Store locator question is not any different than any other question. A store locator question will also have a field ID that's going to mapped against them during the form creation. They are also going to be sent similarly as other questions. The value passed will come from the Store Number of the selected location.

For example, let's say you have a store locator question with selected_dealer as the field ID. To fetch the leads in bulk, you can call:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

The response:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Reading Custom Disclaimer Responses

The field_data does not contain the responses to optional custom disclaimer check boxes that the user would have filled out. To retrieve the responses, use the custom_disclaimer_responses field.

curl -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

Response:

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

Filtering Leads

This example filters leads based on timestamps. Timestamps should be a Unix timestamp.

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1761945743
       }
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<AD_ID>/leads

The operator has one of the following values.

OperatorMeaning

LESS_THAN

Filters for values less than the timestamp.

GREATER_THAN

Filters for values greater than the timestamp.

GREATER_THAN_OR_EQUAL

Filters for values greater than or equal to the timestamp.

Tokenization

If the form has customized field IDs, the fields and values returned will be the specified fields and values.

Resources