Marketing API

Advanced Targeting

Use these advanced options, your own in Custom Audiences and Lookalikes. Use any combination of targeting; by default Facebook ORs combinations together. For "core", or basic targeting, see Targeting. Advanced targeting includes:

If you use flexible_spec, you must also provide one of the following under targeting:

  • geo_locations: geographical targeting field from country, region, city or zip
  • custom_audiences
  • product_audience_specs
  • dynamic_audience_ids

See Limits.

Advertisers running housing, employment and credit ads, who are based in the United States or running ads targeted to the United States have different sets of restrictions. See Special Ad Category.

Mobile

This is useful for Mobile App Install ads.

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

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array(
        'US',
      ),
    ),
    TargetingFields::USER_DEVICE => array(
      'Galaxy S6',
      'One m9',
    ),
    TargetingFields::USER_OS => array('android'),
  )),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My AdSet',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'user_device': [
            'galaxy s6',
            'one m9',
        ],
        'user_os': ['android'],
    },
})
adset.remote_create(params={
    'status': AdSet.Status.active,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
      .setFieldUserDevice(Arrays.asList("Galaxy S6", "One m9"))
      .setFieldUserOs(Arrays.asList("android"))
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "user_device": ["Galaxy S6","One m9"], 
    "user_os": ["android"] 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

You can combine categories, such as iPod OR iPad OR iPhone.

These categories are not mutually exclusive. If you select iOS you target all devices running iOS, including iPhone and iPod, without specifying user_device.

For Brand Awareness Objective ads, you can't target based on mobile device type, such as feature phones or Samsung, or based on iOS version number. You can only choose Android or iOS, or all mobile phones.

Available Fields

Field Description

user_os

type: array

Required.

One or more values from OS option table below. Possible values are at Targeting Search API with type=adTargetingCategory and class=user_os. You cannot target the minimum version of one platform with the other platform. However you can target both platforms without specifying minimal versions of either.


Valid:
- ['iOS', 'Android']
- ['iOS']
- ['Android_ver_4.2_and_above']
- ['iOS_ver_8.0_to_9.0']
Invalid:
- ['Android', 'iOS_ver_8.0_and_above']
- ['iOS', 'Android_ver_4.0_and_above']

user_device

type: array

Optional.

Devices must match the value in user_os. Get possible values at Targeting Search API with type=adTargetingCategory and class=user_device.

excluded_user_device

type: array

Optional.

Devices to exclude. Devices must match the value in user_os. Get possible values at Targeting Search API with type=adTargetingCategory and class=user_device.

wireless_carrier

type: array

Optional.

Allowed value is Wifi. Target mobile users currently on wifi networks.

Operating System Options

Field Description

iOS

type: string

iOS devices, including iPhone, iPad, and iPod

iOS_ver_x.x_and_above

type: string

iOS devices running OS version x.x and above.


Options: 2.0, 3.0, 4.0, 4.3, 5.0, 6.0, 7.0, 8.0, 9.0. Example: iOS_ver_4.0_and_above

iOS_ver_x.x_to y.y

type: string

iOS devices running OS versions x.x to y.y.


Options: 2.0, 3.0, 4.0, 4.3, 5.0, 6.0, 7.0, 8.0, 9.0.

Example: iOS_ver_8.0_to_9.0, where x.x must be less than y.y

Android

type: string

Android devices

Android_ver_x.x_and_above

type: string

Android devices running version x.x and above.


Options: 2.0, 2.1, 2.2, 2.3, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2., 4.3, 4.4, 5.0, 5.1, 6.0, 7.0, 7.1, and 8.0.

Example: Android_ver_4.0_and_above

Android_ver_x.x_to y.y

type: string

Android devices running versions x.x to y.y.


Options: 2.0, 2.1, 2.2, 2.3, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2., 4.3, 4.4, 5.0, 5.1, 6.0, 7.0, 7.1, and 8.0.

Example: Android_ver_4.2_to_8.0, where x.x must be less than y.y

Facebook Connections

Target people who connected or did not connect with your brand.

Available Fields

Name Description

app_install_state

type: String

Only for app-related objectives: mobile_app_*, canvas_app_*. You must use with the ad set's promoted_object. You can apply to both link and video app ads.


Options:

  • installed: target people with promoted object/app installed.
  • not_installed: target people without promoted object/app installed
  • none: same as not specifying.

Example: 'app_install_state': 'not_installed'

connections

type: array of 'id' to value

Array of Facebook IDs. Target fans of your Page, people who RSVP’d to your Event, people who logged into your app with Facebook Login, or authorized your Canvas app. To set this, you must be an admin of the page or event, or developer of the app you're advertising. You can't target on past events.


Example: [{'id':123}, {'id':456}, 789]

excluded_connections

type: array of 'id' to value.

Array of Facebook IDs. Target people who are not fans of your page, have not authorized your Canvas App or have not logged into your mobile app with Facebook Login. You can also target people who did not RSVP to a future event. If you have global page and you want to exclude page fans, you can only target people who are not fans of this global page, instead of people who are not fans of your local page. To set this, you need to be an admin of the Page or event, or developer of the app being advertised. For a 'Page Likes' campaign, you must exclude your page from targeting.


Restrictions: Limited to 100 values.

Example: [{'id':123}, {'id':456}, 789]

friends_of_connections

type: array of 'id's plus values, values or both

Array of Facebook Object IDs. Target friends of people connected to your object. Connections are fans of your Page and people who interacted with your app. To set this, you must be to be an admin of the Page or a developer of the app being advertised. Limit is 100 IDs.


Example: [{'id':123}, {'id':456}, 789]

Advanced Demographic Targeting

Target based on relationships, education, finances, and life events.

Examples

First query life_events:

use FacebookAds\Object\TargetingSearch;
use FacebookAds\Object\Search\TargetingSearchTypes;
use FacebookAds\Object\Search\DemographicSearchClasses;

$result = TargetingSearch::search(
  TargetingSearchTypes::TARGETING_CATEGORY,
  DemographicSearchClasses::LIFE_EVENTS);
from facebookads.adobjects.targetingsearch import TargetingSearch
params = {
    'type': TargetingSearch.TargetingSearchTypes.targeting_category,
    'class': TargetingSearch.DemographicSearchClasses.life_events,
}

resp = TargetingSearch.search(params=params)
print(resp)
curl -G \
  -d 'type=adTargetingCategory' \
  -d 'class=life_events' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/search

Add these to targeting_spec:

curl -X POST \
  -F 'name="My First AdSet"' \
  -F 'daily_budget=10000' \
  -F 'bid_amount=300' \
  -F 'billing_event="IMPRESSIONS"' \
  -F 'optimization_goal="REACH"' \
  -F 'campaign_id="<AD_CAMPAIGN_ID>"' \
  -F 'promoted_object={
       "page_id": "<PAGE_ID>"
     }' \
  -F 'targeting={
       "facebook_positions": [
         "feed"
       ],
       "age_max": 24,
       "age_min": 20,
       "behaviors": [
         {
           "id": 6002714895372,
           "name": "All travelers"
         }
       ],
       "device_platforms": [
         "mobile"
       ],
       "genders": [
         1
       ],
       "geo_locations": {
         "countries": [
           "US"
         ],
         "regions": [
           {
             "key": "4081"
           }
         ],
         "cities": [
           {
             "key": 777934,
             "radius": 10,
             "distance_unit": "mile"
           }
         ]
       },
       "interests": [
         {
           "id": "<INTEREST_ID>",
           "name": "<INTEREST_NAME>"
         }
       ],
       "life_events": [
         {
           "id": 6002714398172,
           "name": "Newlywed (1 year)"
         }
       ],
       "publisher_platforms": [
         "facebook",
         "audience_network"
       ]
     }' \
  -F 'status="PAUSED"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v9.0/act_<AD_ACCOUNT_ID>/adsets
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const AdSet = bizSdk.AdSet;

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 First AdSet',
  'daily_budget' : '10000',
  'bid_amount' : '300',
  'billing_event' : 'IMPRESSIONS',
  'optimization_goal' : 'REACH',
  'campaign_id' : '<adCampaignLinkClicksID>',
  'promoted_object' : {'page_id':'<pageID>'},
  'targeting' : {'facebook_positions':['feed'],'age_max':24,'age_min':20,'behaviors':[{'id':6002714895372,'name':'All travelers'}],'device_platforms':['mobile'],'genders':[1],'geo_locations':{'countries':['US'],'regions':[{'key':'4081'}],'cities':[{'key':777934,'radius':10,'distance_unit':'mile'}]},'interests':[{'id':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']},
  'status' : 'PAUSED',
};
const adsets = (new AdAccount(id)).createAdSet(
  fields,
  params
);
logApiCallResult('adsets api call complete.', adsets);
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdSet;
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 First AdSet',
  'daily_budget' => '10000',
  'bid_amount' => '300',
  'billing_event' => 'IMPRESSIONS',
  'optimization_goal' => 'REACH',
  'campaign_id' => '<adCampaignLinkClicksID>',
  'promoted_object' => array('page_id' => '<pageID>'),
  'targeting' => array('facebook_positions' => array('feed'),'age_max' => 24,'age_min' => 20,'behaviors' => array(array('id' => 6002714895372,'name' => 'All travelers')),'device_platforms' => array('mobile'),'genders' => array(1),'geo_locations' => array('countries' => array('US'),'regions' => array(array('key' => '4081')),'cities' => array(array('key' => 777934,'radius' => 10,'distance_unit' => 'mile'))),'interests' => array(array('id' => '<adsInterestID>','name' => '<adsInterestName>')),'life_events' => array(array('id' => 6002714398172,'name' => 'Newlywed (1 year)')),'publisher_platforms' => array('facebook','audience_network')),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAdSet(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.adset import AdSet
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 First AdSet',
  'daily_budget': '10000',
  'bid_amount': '300',
  'billing_event': 'IMPRESSIONS',
  'optimization_goal': 'REACH',
  'campaign_id': '<adCampaignLinkClicksID>',
  'promoted_object': {'page_id':'<pageID>'},
  'targeting': {'facebook_positions':['feed'],'age_max':24,'age_min':20,'behaviors':[{'id':6002714895372,'name':'All travelers'}],'device_platforms':['mobile'],'genders':[1],'geo_locations':{'countries':['US'],'regions':[{'key':'4081'}],'cities':[{'key':777934,'radius':10,'distance_unit':'mile'}]},'interests':[{'id':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad_set(
  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).createAdSet()
      .setName(\"My First AdSet\")
      .setDailyBudget(10000L)
      .setBidAmount(300L)
      .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
      .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
      .setCampaignId(\"<adCampaignLinkClicksID>\")
      .setPromotedObject(\"{\\"page_id\\":\\"<pageID>\\"}\")
      .setTargeting(
          new Targeting()
            .setFieldAgeMax(24L)
            .setFieldAgeMin(20L)
            .setFieldBehaviors(Arrays.asList(
              new IDName()
                .setFieldId(6002714895372L)
                .setFieldName(\"All travelers\")
            ))
            .setFieldDevicePlatforms(Arrays.asList(Targeting.EnumDevicePlatforms.VALUE_MOBILE))
            .setFieldFacebookPositions(Arrays.asList(\"feed\"))
            .setFieldGenders(Arrays.asList(1L))
            .setFieldGeoLocations(
              new TargetingGeoLocation()
                .setFieldCities(Arrays.asList(
                  new TargetingGeoLocationCity()
                    .setFieldDistanceUnit(\"mile\")
                    .setFieldKey(777934L)
                    .setFieldRadius(10L)
                ))
                .setFieldCountries(Arrays.asList(\"US\"))
                .setFieldRegions(Arrays.asList(
                  new TargetingGeoLocationRegion()
                    .setFieldKey(\"4081\")
                ))
            )
            .setFieldInterests(Arrays.asList(
              new IDName()
                .setFieldId(\"<adsInterestID>\")
                .setFieldName(\"<adsInterestName>\")
            ))
            .setFieldLifeEvents(Arrays.asList(
              new IDName()
                .setFieldId(6002714398172L)
                .setFieldName(\"Newlywed (1 year)\")
            ))
            .setFieldPublisherPlatforms(Arrays.asList(\"facebook\", \"audience_network\"))
        )
      .setStatus(AdSet.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)
adsets = ad_account.adsets.create({
    name: 'My First AdSet',
    daily_budget: '10000',
    bid_amount: '300',
    billing_event: 'IMPRESSIONS',
    optimization_goal: 'REACH',
    campaign_id: '<adCampaignLinkClicksID>',
    promoted_object: {'page_id':'<pageID>'},
    targeting: {'facebook_positions':['feed'],'age_max':24,'age_min':20,'behaviors':[{'id':6002714895372,'name':'All travelers'}],'device_platforms':['mobile'],'genders':[1],'geo_locations':{'countries':['US'],'regions':[{'key':'4081'}],'cities':[{'key':777934,'radius':10,'distance_unit':'mile'}]},'interests':[{'id':'<adsInterestID>','name':'<adsInterestName>'}],'life_events':[{'id':6002714398172,'name':'Newlywed (1 year)'}],'publisher_platforms':['facebook','audience_network']},
    status: 'PAUSED',
})

We now target:

  • Location: Japan or United States: Menlo Park (+10 mi) California or United States: Texas
  • Age: 20 - 24
  • Gender: male
  • Interests: Association football (Soccer)
  • Behaviors: All frequent travelers
  • Life Event: Newlywed (1 year)
  • Home Ownership: Renters

Here's another example targeting by location, demographic, relationship status and interests:

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

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'regions' => array(
        array(
          'key' => '3847',
        ),
      ),
      'cities' => array(
        array(
          'key' => '2430536',
          'radius' => 12,
          'distance_unit' => 'mile'
        ),
      ),
    ),
    TargetingFields::GENDERS => array(1,),
    TargetingFields::RELATIONSHIP_STATUSES => array(2, 3, 4,),
    TargetingFields::AGE_MIN => 18,
    TargetingFields::AGE_MAX => 43,
    TargetingFields::INTERESTS => array(
      array(
        'id' => 6003139266461,
        'name' => 'Movies',
      ),
    ),
  )),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My AdSet',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.targeting: {
        'geo_locations': {
            'regions': [{'key': '3847'}],
            'cities': [
                {
                    'key': '2430536',
                    'radius': '12',
                    'distance_unit': 'mile',
                },
            ],
        },
        'genders': [1],
        'relationship_statuses': [2, 3, 4],
        'age_min': 18,
        'age_max': 43,
        'interests': [
            {
                'id': 6003139266461,
                'name': 'Movies',
            },
        ],
    },
})
adset.remote_create(params={
    'status': AdSet.Status.active,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldAgeMax(43L)
      .setFieldAgeMin(18L)
      .setFieldGenders(Arrays.asList(1L))
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCities(Arrays.asList(
            new TargetingGeoLocationCity()
              .setFieldDistanceUnit("mile")
              .setFieldKey("2430536")
              .setFieldRadius(12L)
          ))
          .setFieldRegions(Arrays.asList(
            new TargetingGeoLocationRegion()
              .setFieldKey("3847")
          ))
      )
      .setFieldInterests(Arrays.asList(
        new IDName()
          .setFieldId("6003139266461")
          .setFieldName("Movies")
      ))
      .setFieldRelationshipStatuses(Arrays.asList(2L, 3L, 4L))
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "age_max": 43, 
    "age_min": 18, 
    "genders": [1], 
    "geo_locations": { 
      "regions": [{"key":"3847"}], 
      "cities": [ 
        { 
          "key": "2430536", 
          "radius": 12, 
          "distance_unit": "mile" 
        } 
      ] 
    }, 
    "interests": [{"id":6003139266461,"name":"Movies"}], 
    "relationship_statuses": [ 
      2, 
      3, 
      4 
    ] 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

Possible options

Name Description

relationship_statuses

type: array

Array of integers representing relationship status.

1: single

2: in_relationship

3: married

4: engaged

6: not specified

7: in a civil union

8: in a domestic partnership

9: In an open relationship

10: It's complicated

11: Separated

12: Divorced

13: Widowed


Default: ALL, if you specify Null or do not provide a value.

Restrictions: Do not use 0.

life_events

type: array

Array of objects with 'id' and optional 'name' fields: [{'id': 123, 'name': 'foo'}, {'id': 456}, 789]

industries

type: array

Array of objects with 'id' and optional 'name' fields

income

type: array

Array of objects with 'id' and optional 'name' fields

family_statuses

type: array

Array of objects with 'id' and (optional) 'name' fields

Education and Work

Use Targeting Search API for all options.

Name Description

education_schools

type: array

Schools, colleges, and institutions.


Limit: 200 education schools.

Example: [{id: 105930651606, 'name': 'Harvard University'}, {id: 105930651607}, 105930651608]

education_statuses

type: array

Array of integers to target based on education level.

1: HIGH_SCHOOL

2: UNDERGRAD

3: ALUM

4: HIGH_SCHOOL_GRAD

5: SOME_COLLEGE

6: ASSOCIATE_DEGREE

7: IN_GRAD_SCHOOL

8: SOME_GRAD_SCHOOL

9: MASTER_DEGREE

10: PROFESSIONAL_DEGREE

11: DOCTORATE_DEGREE

12: UNSPECIFIED

13: SOME_HIGH_SCHOOL

college_years

type: array

Array of integers. College graduation


Limit: Earliest year allowed is 1980

education_majors

type: array

Majors.


Example: [{'id': 123, 'name': 'Computer Science'}, {'id': 456}, 789]

Limit: 200

work_employers

type: array

Company, organization, or workplace


Example: [{'id':'50431654','name':'Microsoft'}, {'id':50431655}, 50431656]

Limit: 200

work_positions

type: array

Self-declared work.


Example: [{'id':105763692790962, 'name':'Contractor'}, {'id':105763692790963}, 105763692790964]

Limit: 200

Custom Audiences

Create a custom audience and add users. You can use the audience in targeting, either for inclusion or exclusion. Include up to 500 custom audiences in custom_audiences and 500 custom audiences in excluded_custom_audiences.

excluded_custom_audiences in targeting_specs is different than excluded_custom_audiences in APP_COMBINATION` Custom Audience.

Field Description

custom_audiences

type: array

Array of audience IDs or audience objects. 'id' field only: [123, 456] or [{'id': 123}, {'id': 456}]

excluded_custom_audiences

type: array

Array of audience IDs or audience objects. 'id' field only: [123, 456] or [{'id': 123}, {'id': 456}]

targeting:{
     "geo_locations":{
       "countries":["US"],
     },
     "age_min":25,
     "age_max":40,
     "custom_audiences":[{"id":6004192254512}]}
     "excluded_custom_audiences":
       [{"id":6004192252847}],
 }

Locales

Provide granular targeting on locale:

Field Description

locales

type: array

Locales, see Targeting Search, Locales. Indices in a sub-array 'locales'. Target people with language other than common language for a location. Provide an ID for the language, such as 5 for German. Limit: 50. See mapping of virtual 'locales' to language sets at Targeting Search, Locale with type=adlocale.

Custom Broad Category Targeting

Use Broad Categories for custom targeting created or permissioned specifically for your account. To include the cooking category and small business owner category:

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

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array(
        'US',
      ),
    ),
    TargetingFields::USER_ADCLUSTERS => array(
      array(
        'id' => 6002714885172,
        'name' => 'Cooking',
      ),
      array(
        'id' => 6002714898572,
        'name' => 'Small Business Owners',
      ),
    ),
  )),
));
$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My AdSet',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'user_adclusters': [
            {
                'id': 6002714885172,
                'name': 'Cooking',
            },
            {
                'id': 6002714898572,
                'name': 'Small Business Owners',
            },
        ],
    },
})
adset.remote_create(params={
    'status': AdSet.Status.active,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
      .setFieldUserAdclusters(Arrays.asList(
        new IDName()
          .setFieldId("6002714885172")
          .setFieldName("Cooking")
      , 
        new IDName()
          .setFieldId("6002714898572")
          .setFieldName("Small Business Owners")
      ))
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "user_adclusters": [ 
      {"id":6002714885172,"name":"Cooking"}, 
      {"id":6002714898572,"name":"Small Business Owners"} 
    ] 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

To exclude the cooking category and small business owner category:

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

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array(
        'US',
      ),
    ),
    TargetingFields::EXCLUSIONS => array(
      TargetingFields::USER_ADCLUSTERS => array(
        array(
         'id' => 6002714885172,
         'name' => 'Cooking',
        ),
        array(
         'id' => 6002714898572,
         'name' => 'Small Business Owners',
        ),
      ),
    ),
  )),
));
$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My AdSet',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'exclusions': {
            'user_adclusters': [
                {
                    'id': 6002714885172,
                    'name': 'Cooking',
                },
                {
                    'id': 6002714898572,
                    'name': 'Small Business Owners',
                },
            ],
        },
    },
})
adset.remote_create(params={
    'status': AdSet.Status.active,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldExclusions(
        new FlexibleTargeting()
          .setFieldUserAdclusters(Arrays.asList(
            new IDName()
              .setFieldId("6002714885172")
              .setFieldName("Cooking")
          , 
            new IDName()
              .setFieldId("6002714898572")
              .setFieldName("Small Business Owners")
          ))
      )
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "exclusions": { 
      "user_adclusters": [ 
        {"id":6002714885172,"name":"Cooking"}, 
        {"id":6002714898572,"name":"Small Business Owners"} 
      ] 
    }, 
    "geo_locations": {"countries":["US"]} 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

To target based on BCT plus location and demographics:

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

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'My AdSet',
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::REACH,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::BID_AMOUNT => 2,
  AdSetFields::DAILY_BUDGET => 1000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array(
        'US',
      ),
    ),
    TargetingFields::RELATIONSHIP_STATUSES => array (2),
    TargetingFields::USER_ADCLUSTERS => array(
      array(
        'id' => 6002714886772,
        'name' => 'Food & Dining',
      ),
    ),
  )),
));
$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_ACTIVE,
));
from facebookads.adobjects.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    AdSet.Field.name: 'My AdSet',
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.reach,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 150,
    AdSet.Field.daily_budget: 2000,
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'relationship_statuses': [2],
        'user_adclusters': [
            {
                'id': 6002714886772,
                'name': 'Food & Dining',
            },
        ],
    },
})
adset.remote_create(params={
    'status': AdSet.Status.active,
})
AdSet adSet = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdSet()
  .setName("My AdSet")
  .setOptimizationGoal(AdSet.EnumOptimizationGoal.VALUE_REACH)
  .setBillingEvent(AdSet.EnumBillingEvent.VALUE_IMPRESSIONS)
  .setBidAmount(2L)
  .setDailyBudget(1000L)
  .setCampaignId(<CAMPAIGN_ID>)
  .setTargeting(
    new Targeting()
      .setFieldGeoLocations(
        new TargetingGeoLocation()
          .setFieldCountries(Arrays.asList("US"))
      )
      .setFieldRelationshipStatuses(Arrays.asList(2L))
      .setFieldUserAdclusters(Arrays.asList(
        new IDName()
          .setFieldId("6002714886772")
          .setFieldName("Food & Dining")
      ))
  )
  .setStatus(AdSet.EnumStatus.VALUE_ACTIVE)
  .execute();
String ad_set_id = adSet.getId();
curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "relationship_statuses": [2], 
    "user_adclusters": [{"id":6002714886772,"name":"Food & Dining"}] 
  }' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

You have options:

Name Description

user_adclusters

type: array

Array of ID-name pairs for BCT clusters. See below for information on retrieving BCT's. Limit: 50 ID-name pairs.

To query this targeting for Ad account, make an HTTP GET:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/broadtargetingcategories

The response is an array of JSON key-value pairs:

Name Description

id

type: long

ID of broad category is used for ad targeting spec

name

type: string

Name of broad category

parent_category

type: string

Parent category of broad category

size

type: int

Audience size of broad category

type

type: int

6=BCT

type_name

type: string

BCT

Resources