Retrieving Leads

You can read leads with Webhooks or Bulk Read.

Before You Start

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

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

Note: If this page admin never customized 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 business admins, then it depends on the business admin's configuration, whether a page basic admin has leads access permission or not.

Starting in v9.0, you will not be able to retrieve leads if your app is in Dev Mode. For testing purposes, Dev Mode app users can access leads submitted by someone with a role in that same app. See App Roles. Apps in Live Mode continue to have access to all leads.

Rate Limits

The rate limit is 200 multiplied by 24 multiplied by the number of leads created in the past 30 days for a Facebook Page. If you make more calls than this in a 24 hour period, your request returns 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/v9.0/{lead-id}/
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<LEAD_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; const sample_code = (new Lead(id)).get( fields, params ); logApiCallResult('sample_code api call complete.', sample_code);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<LEAD_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Lead($id))->getSelf( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<LEAD_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Lead(id).get( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<LEAD_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Lead(id, context).get() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<LEAD_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end lead = FacebookAds::Lead.get(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

Bulk Read

Apps created after July 2, 2018 are forced to use leads_retrieval permission 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/v9.0/{adgroup-id}/leads
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Ad = bizSdk.Ad; const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_GROUP_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { }; const leadss = (new Ad(id)).getLeads( fields, params ); logApiCallResult('leadss api call complete.', leadss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Ad; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_GROUP_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( ); echo json_encode((new Ad($id))->getLeads( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.ad import Ad from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { } print Ad(id).get_leads( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_GROUP_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Ad(id, context).getLeads() .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad = FacebookAds::Ad.get(id) leadss = ad.leads({ fields: { }, })

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": 1605555309 } ]' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v9.0/{adgroup-id}/leads
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const Ad = bizSdk.Ad; const Lead = bizSdk.Lead; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_GROUP_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1602826030}], }; const leadss = (new Ad(id)).getLeads( fields, params ); logApiCallResult('leadss api call complete.', leadss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\Ad; use FacebookAds\Object\Lead; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_GROUP_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1602826030)), ); echo json_encode((new Ad($id))->getLeads( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.ad import Ad from facebook_business.adobjects.lead import Lead from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1602826030}], } print Ad(id).get_leads( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_GROUP_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new Ad(id, context).getLeads() .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1602826030}]\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_GROUP_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad = FacebookAds::Ad.get(id) leadss = ad.leads({ fields: { }, filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1602826030}], })

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