Retrieving Leads

Updated: May 21, 2026

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:

A Page or User access token requested by a person who can advertise on the ad account and on the Page
The ads_management permission
The pages_read_engagement permission
The pages_show_list permission
The pages_manage_metadata permission - if using webhooks

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

A Page or User access token requested by a person who can advertise on the ad account and on the Page
The ads_management permission
The leads_retrieval permission
The pages_show_list permission
The pages_read_engagement permission
The pages_manage_ads permission

Note: If the Page admin did not customize leads and has not granted 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/v25.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

Many CRMs provide real-time updates to migrate lead ads data into the CRMs. See Available CRM Integration⁠.
The ping for real-time updates is structured as follows. Read more at Real Time Updates, Blog.
On success, real-time pings occur on events with a delay of up to a few minutes. See Troubleshooting Real-time Integrations.

You can see an example of this implementation in our GitHub repository⁠.

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/v25.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

A store locator question is no different from any other question. A store locator question will also have a field ID that's going to be 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. Each timestamp must 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/v25.0/<AD_ID>/leads

The operator has one of the following values.

Operator	Meaning
`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

Marketplace Platform: Vehicles, Leads
Lead Access Manager: Please refer to the Help Center articles on About Leads Access Manager⁠ and Assign or Remove Permissions in Leads Access Manager⁠ for more details.

Manage Catalog Items

Facebook Account-Level Permissioning

Instagram Partnership Ads with a New Ad Creative

Threads Ads

Targeting Expansion

Managed Partner Ads: Integration

Managed Partner Ads API Guide

Generate an Access Token for the Admin System User

Quickstart

Retrieving Leads ​

Before You Start ​

Rate Limits ​

Filter By Date Range ​

Caveats ​

Webhooks ​

Step 1: Get Started ​

Step 2: Get a Long-Lived Page Access Token ​

Step 3: Install Your App on the Page ​

Webhook Response ​

Learn More ​

Bulk Read ​

Reading Store Locator Question Value ​

Reading Custom Disclaimer Responses ​

Filtering Leads ​

Tokenization ​

Resources ​