Marketing API

Advantage+ Catalog Ads for Lead Generation

Generate leads with your Advantage+ catalog ads. If you have a product catalog ready and run Advantage+ catalog ads, you can collect leads with your ads on Facebook. Facebook selects the most relevant items in your product set, as we do with all Advantage+ catalog ads, and displays a lead generation form when someone clicks on an item.

When you download leads via the API or as a file, we include a retailer_item_id. This indicates which items someone clicked on and submitted their lead information for.

Create Advantage+ Catalog Ads for Lead Generation

Create a campaign with the objective set to LEAD_GENERATION.

curl -X POST \
  -F 'name="Lead generation campaign"' \
  -F 'objective="OUTCOME_LEADS"' \
  -F 'status="PAUSED"' \
  -F 'special_ad_categories=[]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/campaigns
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Campaign = bizSdk.Campaign;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'Lead generation campaign',
  'objective' : 'OUTCOME_LEADS',
  'status' : 'PAUSED',
  'special_ad_categories' : [],
};
const campaigns = (new AdAccount(id)).createCampaign(
  fields,
  params
);
logApiCallResult('campaigns api call complete.', campaigns);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Campaign;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Lead generation campaign',
  'objective' => 'OUTCOME_LEADS',
  'status' => 'PAUSED',
  'special_ad_categories' => array(),
);
echo json_encode((new AdAccount($id))->createCampaign(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.campaign import Campaign
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Lead generation campaign',
  'objective': 'OUTCOME_LEADS',
  'status': 'PAUSED',
  'special_ad_categories': [],
}
print AdAccount(id).create_campaign(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createCampaign()
      .setName(\"Lead generation campaign\")
      .setObjective(Campaign.EnumObjective.VALUE_OUTCOME_LEADS)
      .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
      .setParam(\"special_ad_categories\", \"[]\")
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
campaigns = ad_account.campaigns.create({
    name: 'Lead generation campaign',
    objective: 'OUTCOME_LEADS',
    status: 'PAUSED',
    special_ad_categories: [],
})

This returns a campaign_id you can use for your ad set.

As with all Advantage+ catalog ads, you must specify a product_set_id in promoted_object for your ad set. This enables you to advertise products from that set. For lead generation, set the optimization_goal to LEAD_GENERATION.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');

$adset->setData(array(
  AdSetFields::NAME => 'Product Catalog Sales Adset',
  AdSetFields::BID_AMOUNT => 3000,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL =>
    AdSetOptimizationGoalValues::LEAD_GENERATION,
  AdSetFields::DAILY_BUDGET => 15000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::DYNAMIC_AUDIENCE_IDS => array(<DYNAMIC_AUDIENCE_ID>),
  ),
  AdSetFields::PROMOTED_OBJECT => array(
    'product_set_id' => <PRODUCT_SET_ID>,
    'page_id' => <PAGE_ID>,
  ),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
curl \
  -F 'name=Product Catalog Sales Adset' \
  -F 'bid_amount=3000' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=LEAD_GENERATION' \
  -F 'daily_budget=15000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "dynamic_audience_ids": ["<DYNAMIC_AUDIENCE_ID>"] 
  }' \
  -F 'promoted_object={"product_set_id":"<PRODUCT_SET_ID>","page_id":"<PAGE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

DYNAMIC_AUDIENCE_ID refers to a Product Audience that views your ads. You can omit DYNAMIC_AUDIENCE_IDs and instead set behavioral or demographic-based targeting to reach an audience by providing the product_audience_specs or excluded_product_audience_specs parameter.

See Advantage+ catalog ads for more information.

Providing the Ad and Creative

First, provide ad creative:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::TEMPLATE_DATA =>
    (new AdCreativeLinkData())->setData(array(
      AdCreativeLinkDataFields::CALL_TO_ACTION => array(
        'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
        'value' => array(
          'lead_gen_form_id' => <FORM_ID>,
        ),
      ),
      AdCreativeLinkDataFields::MESSAGE => 'Test {{product.name | titleize}}',
      AdCreativeLinkDataFields::LINK => '<LINK>',
      AdCreativeLinkDataFields::NAME => 'Headline {{product.price}}',
      AdCreativeLinkDataFields::DESCRIPTION =>
        'Description {{product.description}}',
      AdCreativeLinkDataFields::MULTI_SHARE_END_CARD => false,
    )),
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Dynamic Ad With Leadgen Template Creative Sample',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
  AdCreativeFields::PRODUCT_SET_ID => <PRODUCT_SET_ID>,
));

$creative->create();
curl \
  -F 'name=Dynamic Ad With Leadgen Template Creative Sample' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "template_data": { 
      "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}}, 
      "description": "Description {{product.description}}", 
      "link": "<LINK>", 
      "message": "Test {{product.name | titleize}}", 
      "multi_share_end_card": false, 
      "name": "Headline {{product.price}}" 
    } 
  }' \
  -F 'product_set_id=<PRODUCT_SET_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/adcreatives

This returns the creative_id you can use to create or update an ad:

curl -X POST \
  -F 'name="My Ad"' \
  -F 'adset_id="<AD_SET_ID>"' \
  -F 'creative={
       "creative_id": "<CREATIVE_ID>"
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/ads
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const Ad = bizSdk.Ad;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
const ads = (new AdAccount(id)).createAd(
  fields,
  params
);
logApiCallResult('ads api call complete.', ads);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.ad import Ad
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
ads = ad_account.ads.create({
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
})

Fetching Leads

If you have the lead id from a CRM integration you can ask for the details including item_id.

use FacebookAds\Object\Lead;

$form = new Lead(<LEAD_ID>);
$form->read(array(
    LeadFields::FIELD_DATA,
    "retailer_item_id",
));
curl -G \
  -d 'fields=field_data,retailer_item_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<LEAD_ID>

You can also bulk query all the leads for a form:

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$leads = $form->getLeads(array(
    LeadFields::FIELD_DATA,
    "retailer_item_id",
));
curl -G \
  -d 'fields=field_data,retailer_item_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>/leads

Or for an ad:

curl -X GET \
  -d 'fields="field_data,retailer_item_id"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v19.0/{adgroup-id}/leads
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
  'field_data',
  'retailer_item_id',
];
params = {
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'field_data',
  'retailer_item_id',
);
$params = array(
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'field_data',
  'retailer_item_id',
]
params = {
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .requestFieldDataField()
      .requestRetailerItemIdField()
      .execute();

  }
}
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: { 'field_data''retailer_item_id' },
})