Marketing API Version

Lead Ads

Capture leads in Facebook ads. Provide people with a quick and privacy-safe way to sign up to receive information from your business.

Quickstart

Lead Ads make forms simple for people and more valuable for businesses. Set up a Lead Ad, where potential customers can sign up for what you're offering, and you'll get accurate contact info to follow up.

The form is mobile-device friendly and uses information people already shared with Facebook. It's easier and faster for people to reach you – and advertisers gets accurate, actionable information. See Lead Ads

Requirements

  • Facebook Page - This gives your business a presence on Facebook, and helps you connect with customers. See Facebook for Business or create a new page. All leads generated via a lead ad belong to the Page.

  • Instagram Account - Optional, if you want to run a lead ad on Instagram. The leads generated via the ad still belong to the Facebook Page.

  • Facebook App - Which is any third-party app, such as website, mobile app or script. The App Marketing APIs, enabling integration with Facebook. Each app has an App ID you use whenever you use one of our SDKs or Open Graph tags for sharing. Find your app ID in your apps dashboard. Read more about how to create an App and App ID

  • Test App - Optional. Quickly create Facebook App IDs for use during development, testing, staging or QA phases. Test Apps have their own App ID and independent settings, and are helpful in pre-production, see Test Apps

  • App Review - We review your app to ensure a high-quality experience. See App Review.

Implementing

All apps that access Facebook need an access token. See Access Tokens. Or get a token when you create your new app on Marketing API. An access token is an opaque string that identifies a user, app, or page and can be used by the app to make graph API calls. Access tokens are obtained via a number of methods, each of which are covered in access tokens Docs. Access tokens can be short- or long lived. Short-lived tokens usually have a lifetime of about an hour or two, while long-lived tokens usually have a lifetime of about 60 days. You should not depend on these lifetimes remaining the same - the lifetime may change without warning or expire early.

We cover the basics of Graph and Marketing API in Graph API Overview and Using Graph API.

Integrating CRMs

With Facebook lead ads, you can set up your leads to be instantly updated into your CRM system. Your options include:

  • CRM Partners supporting Lead Ads.
  • Custom integration - Using Webhooks and Facebook Graph API. A WebHook is an HTTP callback that occurs when something happens which in turn invokes a simple event-notification via the HTTP POST call. See Lead Ads Webhooks
  • Graph API - Which is the primary way to get data in and out of Facebook. It's a low-level HTTP-based API that you can use to retrieve new lead ads in real-time. Read more about the Graph API

Creating a new Lead Ad

  • Create a form to use for the lead ad.
  • Create the ad in [Power Editor](https://www.facebook.com/ads/manage/powereditor/) | Create Campaign | Create leads or Marketing API and associate the form ID, see Lead Ads, Creating

Retrieving Leads

To read lead data, you need Page Admin Access or flexible permissions. With the latter you retrieve leads without Page Admin access, see Lead Ads Flexible Permissioning Endpoint. Ways to retrieve leads are:

  • CSV Download - CSV's can be downloaded on a Form level and an Ad level. You can perform form-level download on the Publishing Tools tab in your Page panel or using the API. See CSV Download.
  • Ad Level Download - Manually through the download lead form option in Power Editor under the Results column. Or you can use the CSV link in the link column. Finally you can manually downlooad leads in the download lead form option in Ads Manager under the Results column.
  • Bulk-read with the Graph API - Retrieve the Leads as JSON objects, making it easy to integrate and map data. This is suitable if you want to fetch new leads a few times a day. For more frequent updates use Webhooks. Read more on Bulk-read -Webhooks - Good for CRM integration with Facebook to receive leads in real time. Retrieve every new Lead in real-time. Every time a new Lead is submitted, we send an update to your endpoint to notify you that a new Lead is available. You can fetch the information of the Lead by accessing the API. Webhooks enables you to query our Read API to retrieve the lead information only when you know there are new Leads. See How to use our Webhooks

Resources