Meta Marketing API

Lead Ads

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

How it Works

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.

The form is mobile-friendly and uses information people already shared with Facebook. It's easier and faster for people to reach businesses — and advertisers get accurate, actionable information. Learn more about Lead Ads.

Requirements

To get started with lead ads, you will need:

  • A Facebook Page — 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 Facebook Page.

  • An Instagram Account (optional) — This is required if you want to run a lead ad on Instagram. The leads generated via the ad still belong to the Facebook Page.

  • A Facebook App — Can be any third-party app, such as a website, mobile app, or script. The Marketing API apps enable 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 App Dashboard. Learn more about how to create an App and app ID.

  • A 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 — To retrieve lead data, your app must undergo App Review. You must include the leads_retrieval and pages_manage_ads permissions in your submission. Check our Submission Guide for details. After approval, you will be asked to complete Business Verification.

Limitations

Starting in Marketing API v9.0, you will not be able to retrieve leads if your app is in Development mode. For testing purposes, Development 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.

Implementation

All apps that access Facebook need an access token, or you can get a token when you create your new app on the 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. You can obtain access tokens via a number of methods. See the access tokens documentaiton for more information on the different types and how to get them.

Access tokens can be short or long-lived. Short-lived tokens typically 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 as they may change without warning or expire early.

User access tokens are rate-limited based on active users on the app, which is usually ONE for lead ad integrations.

We strongly recommend using Page access tokens because they're rate-limited based on active users on the Page.

Create a New Lead Ad

  1. Create a form to use for the lead ad.
  2. Create the ad in the Ads Manager or with the Marketing API and associate the form ID. See Lead Ads, Creating.

Integrating CRMs

With Facebook lead ads, you can set up the leads you receive from Facebook 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 for more information.
  • Graph API - 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.

Conversions API integration

To see a better performance in your lead ads, you can choose to share your CRM data about your leads back to Facebook to unlock quality lead optimization. This allows Facebook to better optimize for quality leads by using data on which generated lead turned out to be quality leads from your CRM directly.

  1. Create or choose a Facebook Pixel.
    Your Pixel is where you can see the CRM events that make up your sales funnel.
  2. Connect your CRM to the Conversions API.
    This lets your CRM share events to your Pixel. Click here to see the payload specifications for CRM integration.
  3. Define your sales funnel.
    Once we begin receiving events from your CRM, tell us which sales funnel events you'd like to optimize for.

Note: Steps 1 and 3 are currently only available via the Events Manager.

See more information about connecting your CRM to the Conversions API in the CRM Integration guide.

Retrieve Leads

To read lead data, you need Page Admin access or flexible permissions. With the latter, you retrieve leads without Page Admin access.

Ways to Retrieve Leads

  • Ads Manager — See Download Your Leads Data from Ads Manager for more information.
  • 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. Learn more about bulk reading.
  • 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, an update is sent to your endpoint to notify you that a new lead is available. You can then fetch the information of the lead by accessing the Marketing API. See How to use our Webhooks for more information.

Learn More