Retrieving Leads

Differently from what happens with real estate listings published by users, for partner integrations, leads are sent to partners via lead form, rather than via Messenger chat.

Leads can be downloaded and retrieved in two different ways: manual and via API (webhook). Depending on the size of your catalog, you would choose one of the two ways. For catalogs bigger than 100-200 listings we strongly suggest to automate your leads retrieval flow using our APIs.

In order to make API requests, you have to request an app review. Dev mode is allowed for some time/number of requests, but when your integration is in production, you should request an app review and switch the app to Live mode. An app in Dev mode could stop working as expected at any moment.

Find more info about app review in our FAQs.

Manual download

You must be an admin to access leads through your Facebook page. Go to your page settings. Then click on Publishing Tools at the top of the header bar:

From the Publishing Tools page, click on "Forms Library" under the section "Lead Ads Form", on the left hand side. In the Forms Library table, you will find a form called "Marketplace Real Estate Lead Gen Form":

by clicking "Download", a dialog will appear, asking if you want to download new leads or leads within a specific time range. After selecting your preference, you will be able to download leads in CSV or XLS format.

Using Leads APIs / webhook

Marketplace Real Estate uses the Marketing Leads API which is already in use across our Ads products and Motors partnerships on Marketplace.

Requirements

You must have a Facebook page (with Admin access) attached to your Business Manager.

Retrieving Leads requires app review

You can set up your app to retrieve test leads in dev mode. After the setup is complete, you have to request an app review and switch the app to live mode in order to receive production leads.

Permissions required:

  • manage_pages
  • leads_retrieval
  • ads_management (if you need to retrieve additional listing detail other than just the home_listing_id. See below in the section "Retrieve Rental listing detail information")

The app review process could take up to 1-2 weeks including business verification. Please read this guide and prepare required documents in advance.

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

Using Graph API v3.2 or upper versions

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

Setup Steps

Lead generation is language agnostic

The examples in this guide are in PHP, but you can write your webhook in whatever server-side language you like best.

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

1
Create a new PHP file
You need to set up an endpoint that reads two variables (hub.challenge and hub.verify_token). If the verify code is fine, you should reply with the challenge. You can put any string as $token value, this will be used just 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 at a URL of your convenience, e.g. https://yourdomain.com/facebook/webhook_verify.php. Check more details in this guide.
2
Create / edit your Facebook app, adding the webhook
If you don't have a Facebook app, you should create one. After that, you'll be able to add the webhook product:
Select Page from the dropdown menu, then click on Subscribe to this object.
Enter the information required:
  • Callback URL: the path to your webhook
  • Verify Token: a token you can choose to verify the request that Facebook will send to the webhook (see above)
  • You should now see a list of possible fields to subscribe. Scroll down, and click on the Subscribe button next to leadgen field.
    You can test your webhooks using the test button next to leadgen. Check on your server if you received the request, for example by:
  • checking access logs
  • reading the raw content of the request body:
    $request_body = file_get_contents('php://input')
  • 3
    Get Business System User Access Token

    Create a system user. Go to your Business Manager > Business Settings > Users > System Users and create a new system user.

    Install app and generate a new Token. You will need to select your app and these permission:

    • manage_pages
    • leads_retrieval
    • ads_management (if you need to retrieve additional listing detail other than just the home_listing_id. See below in the section "Retrieve Rental listing detail information")

    Copy and save this token as it won't be stored at Facebook. You will use this token to access pages of dealers under your business.

    4
    Assign a page to the system user you created

    In Business Manager > Users > System Users, select your system admin. Click Assign Assets button and then select Page.

    Select a page with Page Admin role.

    5
    Get Page Access Tokens

    You will get all page access tokens assigned to the system admin.

    curl -G \
     -d "access_token=<access-token>" \
     "https://graph.facebook.com/v4.0/me/accounts"

    The response example:

    {
      "data": [
        {
            "access_token": "...",
            "category": "Business and Pages",
            "category_list": [
                {
                    "id": "123688294262123",
                    "name": "Real Estate Partner"
                }
            ],
            "name": "Test page",
            "id": "132337234248833",
            "tasks": [
                "ANALYZE",
                "ADVERTISE",
                "MODERATE",
                "CREATE_CONTENT",
                "MANAGE"
            ]
        },
      ]
    }

    This access tokens in the response are long-lived page tokens which has no expiration date and you can hard-code it in simple RTU integrations to get leads data.

    6
    Subscribe pages to the app

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

    use FacebookAds\Api;
    use FacebookAds\Http\RequestInterface;
    
    Api::instance()->call(
      '/' . <PAGE_ID> . '/subscribed_apps',
      RequestInterface::METHOD_POST);
    curl \
      -F 'access_token=<ACCESS_TOKEN>' \
      https://graph.facebook.com/v2.11/<PAGE_ID>/subscribed_apps

    If you are using Graph API v3.2 or upper version, please add one additional 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 app ID.

    On success, real time pings occur on events with a delay of up to a few minutes. See Troubleshooting Real-time Integrations.

    Receive leads via webhooks

    One way is to use Lead Ads Testing Tool to send test leads. Please notice that this tool will send a test payload, different than the one you will receive from testing with a real listing.

    The best way to test is to go to your Catalog Manager, and under Home Listings, click on the green dot "Marketplace Enabled" under any of your listings. This will open the Marketplace view for that listing. Click con "Contact", and send yourself a test lead.

    The payload you will receive in your webhook is structured as follows:

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

    Use leadgen_id to retrieve data associated with the lead.

    Use page access token of the page associated with the lead. Leads will be 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. The new lead id will be notified to you.

    curl -G \
        -d "access_token=<access-token>" \
        "https://graph.facebook.com/v4.0/<lead-id>"

    Marketplace Rentals Lead Gen response:

    {
      "created_time": "2019-03-19T04:32:34+0000",
      "id": "2219139835001024",
      "field_data": [{
          "name": "email",
          "values": [
            "joe@fbtest.com"
          ]
        },
        {
          "name": "phone_number",
          "values": [
            "12345678"
          ]
        },
        {
          "name": "free_form_text",
          "values": [
            "Hi!"
          ]
        },
        {
          "name": "first_name",
          "values": [
            "Joe"
          ]
        },
        {
          "name": "last_name",
          "values": [
            "Smith"
          ]
        }
      ],
      "retailer_item_id": "Property_id_400454"
    }

    Retrieve Rental listing detail information

    You can add home_listing parameter in the request to retrieve additional fields of the home listing.

    If you want to retrieve the home listing information, you will need an additional permission, ads_management.

    Read the supported fields list.

    curl -G \
        -d "access_token=<access-token>" \
        -d "fields=id,field_data,home_listing{id,name,property_type,price,address}" \
        "https://graph.facebook.com/v4.0/<lead-id>"

    The response:

    {
      "field_data": [
        {
          "name": "email",
          "values": [
            "joe@fbtest.com"
          ]
        },
        {
          "name": "phone_number",
          "values": [
            "12345678"
          ]
        },
        {
          "name": "free_form_text",
          "values": [
            "Hi!"
          ]
        },
        {
          "name": "first_name",
          "values": [
            "Joe"
          ]
        },
        {
          "name": "last_name",
          "values": [
            "Smith"
          ]
        }
      ],
      "home_listing": {
        "id": "2791933954211104",
        "name": "My second test home sale listing",
        "property_type": "other",
        "price": "$700.00",
        "address": {
          "city": "Menlo Park",
          "country": "USA",
          "latitude": 37.48514,
          "longitude": -122.148387,
          "postal_code": "94025",
          "region": "California",
          "street_address": "1 Hacker Way"
        }
      },
      "id": "345213352829655"
    }

    You can manually download leads in CSV format from Page Settings. Read this guide.

    You can also retrieve all leads you received. You can find {form-id} from this API.

    curl -G \
        -d "access_token=<access-token>"
        "https://graph.facebook.com/v4.0/<form-id>/leads"

    You can also delete a lead you created. Please notice that you need to use a user token and not a page token. As above, we recommend to use a system user. In your Business Manager, please make sure that the user is an admin of the page that owns the lead, otherwise you won't have the permission to to delete it. See this API reference.

    curl -i -X DELETE \
     "https://graph.facebook.com/v4.0/<lead-id>?access_token=<access_token>"

    Troubleshooting

    If you do not receive leads in your webhook:

    • Go to your app dashboard, under App Review > My Permissions and Features, and check that you have manage_pages and leads_retrieval approved.
    • Check that your app is set to live mode.
    • Delete existing leads in order to receive webhooks again from the same listing, or try with another listing.
    • Check if you have a custom Leads Access Management (LAM) enabled. Go to your Business Manager > Business Settings > Integrations > Leads Access. If you don't see a button "Customize Access", you have enabled LAM. You will need to select your Facebook page in this screen, click on CRMs, and add your app. You must be an admin of the business in order to do this.
    • In your Business Manager, check that the system user is added as admin of your app (Business Manager > Business Settings > Accounts > Apps).

    Need help?

    You can contact Facebook's Support team any time you have questions.

    Contact us