Retrieve Leads

If you chose Lead Ads Form as the communication channel, you can access Vehicles leads generated on Marketplace in different ways.

How it Works

Depending on the size of your catalog, you can retrieve leads by these methods:

For catalogs larger than 100-200 listings, we strongly suggest to automate your leads retrieval flow using our APIs.

Learn more about how to Retrieve Leads, Marketing API.

Download Leads (Manually)

As a Page admin, you can view and download leads from Marketplace (at the top of your page, you should see Publishing Tools).

On the Publishing Tools page, on the left side (under Lead Ads Form), click Forms Library.

In the Forms Library table, find the Marketplace Autos Lead Gen Form:

Click Download to download all available leads or leads within a specific time range, in CSV or XLS format.

Connect Your CRM System to Facebook

To learn how to connect your CRM system to your Facebook page, see Connect Your CRM System to Facebook, Business Help Center.

Learn how you can set up your leads to be instantly updated into your CRM system.

Use Lead APIs and Webhook

Lead ads make forms simple for people and more valuable for businesses. Set up a Lead ad where prospective customers can sign up for what you're offering, and you'll get accurate contact information to follow up.

Learn more about how you can retrieve leads by setting up a webhook.

Requirements

Before you begin your setup, ensure that you meet the following requirements:

Admin Access to Dealer Pages

Ensure that your Dealer pages have Admin access with the Manage Page role.

Register an App and Submit for App Review

Register an app to retrieve test leads in dev mode.
After the setup is complete, you must request an App Review and switch the app to Live Mode to receive production leads.

Permissions required:

pages_manage_ads
pages_manage_metadata
pages_read_engagement
leads_retrieval
business_management (to request dealers' page permissions)
ads_management (to retrieve additional listing detail other than just the vehicle_id)

The App Review process can take up to 1-2 weeks including business verification. Please read this guide and prepare required documents in advance.

Host on Public HTTP Server

To receive webhook events from the Facebook Platform, your code must be hosted on a public HTTP server that meets has the following:

HTTPS support
A valid SSL certificate
An open port that accepts GET and POST requests

Use Graph API v4.0 or Higher

The Facebook Platform supports versioning and each version is guaranteed to operate for at least 2 years. A version is no longer usable 2 years after the date that the subsequent version is released. We highly recommend developers to use the most recent API version.

Lead APIs and Webhook — Setup

Lead generation is language-agnostic. The examples in this guide are in PHP, but you can write your webhook in a preferred server-side language.

Before you begin, make sure your server meets all of the requirements listed above.

Step 1: Create a New PHP File

Set up an endpoint that reads these variables: hub.challenge and hub.verify_token.
If the verify code is fine, reply with the challenge. You can put any string as the $token value. This is simply used to verify your endpoint.

<?php
  $token = "<YOUR_VERIFY_TOKEN>";
  $challenge = $_REQUEST['hub.challenge'];
  $verify_token = $_REQUEST['hub.verify_token'];

  if ($verify_token === $token) {
    echo $challenge;
  }
?>

Save the file and make it reachable from a convenient path URL; for example, https://yourdomain.com/facebook/webhook_verify.php. Learn how to create an endpoint.

Step 2: Add the Webhook to Your Facebook App

From the Facebook app dashboard > Products, select your app and add the webhook item.

From the dropdown, select Page and click Subscribe to this object.

On the Edit Page Subscription dialog, enter the Callback URL (path URL you created to reach your webhook) and the Verify Token (token you can set to verify the request that Facebook sends to the webhook).
Click Verify and Save.

Scroll down to find the leadgen field and click Subscribe.

Next to Test (leadgen), click Test to test your webhooks.
On your server, verify that you received the request:
- Check access logs
- Read the raw content of the request body:
```
$request_body = file_get_contents('php://input')
```

Step 3: Get Business System User Access Token

Go to your Business Manager > Business Settings > Users > System Users and create a new system user. Learn more about how to Create a system user.
Install app and generate a new token.
Select your app and these permissions, then click Generate Token:

business_management
manage_pages
leads_retrieval

Copy and save this token (as it won't be stored at Facebook) and click OK. Use this token to access dealer pages under your business.

Step 4: Assign Dealer Pages to the System User

Go to Business Manager > Users > System Users and select your system admin.
Click Assign Assets and select Page.

Select Page admin to assign dealers pages with access, and click Save Changes.
Verify that those dealer pages are visible/assigned when you integrate new dealers. Alternatively, you can use API similar with this guide.

Make sure you include MANAGE role in tasks.
Get the BUSINESS_ID of your system user with the following request:

Graph API Explorer

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{BUSINESS_ID}/system_users

GET /{BUSINESS_ID}/system_users HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{BUSINESS_ID}/system_users',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{BUSINESS_ID}/system_users",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

After you obtain the BUSINESS_ID of your system user, you can run the following code to give the system user access to the page (PAGE_ID):

Graph API Explorer

curl -X POST \
  -F 'user={BUSINESS_SCOPED_USER_ID}' \
  -F 'tasks=[
       "CREATE_CONTENT",
       "MODERATE",
       "ADVERTISE",
       "ANALYZE",
       "MANAGE"
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{PAGE_ID}/assigned_users

POST /{PAGE_ID}/assigned_users HTTP/1.1
Host: graph.facebook.com

user=%7BBUSINESS_SCOPED_USER_ID%7D&tasks%5B0%5D=CREATE_CONTENT&tasks%5B1%5D=MODERATE&tasks%5B2%5D=ADVERTISE&tasks%5B3%5D=ANALYZE&tasks%5B4%5D=MANAGE

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{PAGE_ID}/assigned_users',
    array (
      'user' => '{BUSINESS_SCOPED_USER_ID}',
      'tasks' => 
      array (
      0 => 'CREATE_CONTENT',
      1 => 'MODERATE',
      2 => 'ADVERTISE',
      3 => 'ANALYZE',
      4 => 'MANAGE',
      ),
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{PAGE_ID}/assigned_users",
    "POST",
    {
        "user": "{BUSINESS_SCOPED_USER_ID}",
        "tasks": [
            "CREATE_CONTENT",
            "MODERATE",
            "ADVERTISE",
            "ANALYZE",
            "MANAGE"
        ]
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Step 5: Get Page Access Tokens

By default, you will get all page access tokens assigned to the system admin.

Use the Business Manager System User token you saved before as access_token.

Graph API Explorer

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/me/accounts

GET /me/accounts HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/me/accounts',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/me/accounts",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Sample Response:

{
  "data": [
    {
        "access_token": "...",
        "category": "Automotive Dealership",
        "category_list": [
            {
                "id": "123688294262123",
                "name": "Automotive Dealership"
            }
        ],
        "name": "Test dealer page",
        "id": "132337234248833",
        "tasks": [
            "ANALYZE",
            "ADVERTISE",
            "MODERATE",
            "CREATE_CONTENT",
            "MANAGE"
        ]
    },
  ]
}

The access tokens in the response are long-lived page tokens that have no expiration date. You can hard-code the date in simple RTU integrations to get leads data.

Step 6: Subscribe Pages to the App

Using the page access tokens, your app must subscribe pages so that Facebook can send webhooks to your webserver.

Graph API Explorer

curl -X POST \
  -F 'subscribed_fields="leadgen"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{PAGE_ID}/subscribed_apps

POST /{PAGE_ID}/subscribed_apps HTTP/1.1
Host: graph.facebook.com

subscribed_fields=leadgen

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{PAGE_ID}/subscribed_apps',
    array (
      'subscribed_fields' => 'leadgen',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{PAGE_ID}/subscribed_apps",
    "POST",
    {
        "subscribed_fields": "leadgen"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

If you are using Graph API v3.2 or higher, add the following parameter in the POST request (read more):

subscribed_fields=leadgen

The Facebook app associated with your token is authenticated for page updates; you do not need to specify an app ID.

On success, real-time pings occur on events with a delay of up to a few minutes. If you need help with the integration, see Troubleshooting Real-time Integrations.

Step 7: Receive Leads via Webhooks

Test Your Webhook

Test your webhook by sending leads from your Marketplace listings.

If you do not receive leads in your webhook:

Make sure you changed your app to public mode.
Delete existing leads to receive them again from the same listings.

The payload sent to the webhook has the following structure:

{
  "changes": [{
    "field": "leadgen",
    "value": {
      "created_time": 1540269154,
      "page_id": "1935718636547237",
      "form_id": "2217161425198865",
      "leadgen_id": "2219139835001024"
    }
  }],
  "id": "1935718636547237",
  "time": 1540269155
}

Step 8: Retrieve Data Associated with the Lead

Use leadgen_id to retrieve data associated with the lead.

Leads are available for 90 days. If you receive a non-existent lead response, the lead has been modified by the user, and has a new ID. You will be notified of the new lead ID.

Use the page access token of the page associated with the lead:

Graph API Explorer

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

GET /{LEAD_ID} HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{LEAD_ID}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{LEAD_ID}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

...to get the following response:

{
  "created_time": "2018-10-23T04:32:34+0000",
  "id": "2219139835001024",
  "field_data": [{
      "name": "email",
      "values": [
        "joe@fbtest.com"
      ]
    },
    {
      "name": "phone_number",
      "values": [
        "12345678"
      ]
    },
    {
      "name": "full_name",
      "values": [
        "Joe"
      ]
    }
  ],
  "retailer_item_id": "Vehicle_id_4"
}

Step 9: Retrieve Additional Vehicle Information (Optional)

In Business Manager, ensure that the system user who owns the access token is an admin of the catalog.

You can add vehicle parameter in the request (see supported Vehicles fields).

Graph API Explorer

curl -X GET -G \
  -d 'fields="id,field_data,vehicle{id,vin,vehicle_registration_plate,title,price,address,mileage}"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{LEAD_ID}

GET /{LEAD_ID}?fields=id%2Cfield_data%2Cvehicle%7Bid%2Cvin%2Cvehicle_registration_plate%2Ctitle%2Cprice%2Caddress%2Cmileage%7D HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{LEAD_ID}?fields=id%2Cfield_data%2Cvehicle%7Bid%2Cvin%2Cvehicle_registration_plate%2Ctitle%2Cprice%2Caddress%2Cmileage%7D',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{LEAD_ID}",
    {
        "fields": "id,field_data,vehicle{id,vin,vehicle_registration_plate,title,price,address,mileage}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

...to get the following response:

{
  "id": "2219139835001024",
  "field_data": [{
      "name": "email",
      "values": [
        "joe@fbtest.com"
      ]
    },
    {
      "name": "phone_number",
      "values": [
        "12345678"
      ]
    },
    {
      "name": "full_name",
      "values": [
        "Joe"
      ]
    }
  ],
  "vehicle": {
    "id": "2561003667307302",
    "vin": "TEST1234453254321",
    "title": "Title1",
    "price": "$1,500.00",
    "mileage": {
      "value": 1000,
      "unit": "MILES"
    },
    "address": {
      "city": "Menlo Park",
      "country": "US",
      "latitude": 37.4435997,
      "longitude": -122.1615219,
      "postal_code": "94025",
      "region": "Menlo Park, CA",
      "street_address": "1234 Example St"
    }
  }
}

Step 10: Retrieve All Leads Received (Optional)

To use this option, you need an the catalog_management permission.

You can also retrieve all leads you received by using {FORM_ID}, which can be found using the Page Leadgen Forms API:

Graph API Explorer

curl -X GET -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{FORM_ID}/leads

GET /{FORM_ID}/leads HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{FORM_ID}/leads',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{FORM_ID}/leads",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Step 11: Delete Leads (Optional)

To delete a lead, you need to use a user token, not a page token. You can only delete leads that you own (for example, test).

Graph API Explorer

curl -X DELETE -G \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/{LEAD_ID}

DELETE /{LEAD_ID} HTTP/1.1
Host: graph.facebook.com

/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->delete(
    '/{LEAD_ID}',
    array (),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */

/* make the API call */
FB.api(
    "/{LEAD_ID}",
    "DELETE",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);

Learn how to delete a UserLeadGenInfo by making a DELETE request to /{user_lead_gen_info_id}.

Contact Us

Contact Facebook's Support team

Retrieve Leads

How it Works

Download Leads (Manually)

Connect Your CRM System to Facebook

Use Lead APIs and Webhook

Requirements

Admin Access to Dealer Pages

Register an App and Submit for App Review

Host on Public HTTP Server

Use Graph API v4.0 or Higher

Lead APIs and Webhook — Setup

Step 1: Create a New PHP File

Step 2: Add the Webhook to Your Facebook App

Step 3: Get Business System User Access Token

Step 4: Assign Dealer Pages to the System User

Step 5: Get Page Access Tokens

Step 6: Subscribe Pages to the App

Step 7: Receive Leads via Webhooks

Test Your Webhook

Step 8: Retrieve Data Associated with the Lead

Step 9: Retrieve Additional Vehicle Information (Optional)

Step 10: Retrieve All Leads Received (Optional)

Step 11: Delete Leads (Optional)

Contact Us

Learn More