Custom Audience targeting - Documentation

Marketing API Version

Custom Audience

Build an audience of your customers, website visitors, mobile app visitors or people similar to them.

To add or remove users from a Custom Audience, please see the Custom Audience User guide.

Reading

Custom audiences allow advertisers to target their ads to a specific set of people with whom they have already established a relationship on/off Facebook. Audiences can be defined by either email address, Facebook UIDs, phone numbers, names, date of birth, gender, locations, app user IDs, Apple's Advertising Identifier (IDFA), Android's advertising ID or by a combination of rules used to identify users who took specific actions on your website.

When utilizing Facebook UIDs please ensure you comply with Section II of the Platform Policies. An advertiser must accept Custom Audience's terms of service in order to use the product. You can query which terms a given account accepted by checking the field tos_accepted of a given ad account. You can find more information at the ad account node documentation.

Examples

By audience ID:

use FacebookAds\Object\CustomAudience;

$custom_audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);
$custom_audience->read();

from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience.remote_read()

CustomAudience customAudience2 = new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).get()
  .execute();

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CUSTOM_AUDIENCE_ID>

By ad account edge:

use FacebookAds\Object\AdAccount;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$audiences = $account->getCustomAudiences();

from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.customaudience import CustomAudience

ad_account = AdAccount('act_<AD_ACCOUNT_ID>')
custom_audiences = ad_account.get_custom_audiences(fields=[
    CustomAudience.Field.name
])
for custom_audience in custom_audiences:
    print(custom_audience[CustomAudience.Field.name])

APINodeList<CustomAudience> customAudiences = new AdAccount(act_<AD_ACCOUNT_ID>, context).getCustomAudiences()
  .execute();

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/customaudiences

If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

Field	Description
`id` numeric string	Custom audience ID Default
`account_id` numeric string	Ad Account ID
`approximate_count` int32	Approximate number of people in this audience
`data_source` CustomAudienceDataSource	JSON dictionary of `type`, `sub_type` to indicate by which method the custom audience was created.
`delivery_status` CustomAudienceStatus	JSON dictionary of `code` and `description`. Indicates whether or not an audience can be used in ads. There are two situations that an audience will make ads not deliverable. First, if the size is smaller than 20 people, the audience can't be delivered. Second, if for some reason the audience is disabled (such as violation of policy, expired), validation will fail when it is used in ads.
`description` string	Custom audience description
`external_event_source` AdsPixel	Read-only JSON dictionary with key `id` containing the pixel id whose traffic generated this custom audience
`is_value_based` bool	Whether the audience is used to seed value based lookalike
`lookalike_audience_ids` list<numeric string>	The IDs of the lookalike audiences generated from this audience
`lookalike_spec` LookalikeSpec	Generated only when the subtype is `LOOKALIKE`. More info at Lookalike Audience
`name` string	Custom audience name
`operation_status` CustomAudienceStatus	JSON dictionary of `code` to int value and `description` to a description string. The operation status represents the status of the last operation performed on an audience. In general, it will have following states: * 0: Status not available * 200: Normal: there is no updating or issues found * 400: Warning: there is some message we would like advertisers to know * 410: No upload: no file has been uploaded * 411: Low match rate: low rate of matched people * 412: High invalid rate: high rate of invalid people * 421: No pixel: Your Facebook pixel hasn't been installed on your website yet * 422: Pixel not firing: Your Facebook pixel isn't firing * 423: Invalid pixel: Your Facebook pixel is invalid * 431: Lookalike Audience refresh failed * 432: Lookalike Audience build failed * 433: Lookalike Audience build failed * 434: Lookalike Audience build retrying * 500: Error: there is some error and advertisers need to take action items to fix the error
`opt_out_link` string	Your opt-out URL so people can choose not to be targeted
`permission_for_actions` CustomAudiencePermission	JSON dictionary of permissions (string) to boolean value if the custom audience has that permission
`pixel_id` numeric string	ID of the pixel which is collecting events for this Website Custom audience
`retention_days` int32	Number of days to keep the user in this cluster. You can use any value between 1 and 365 days. Defaults to forever if not specified
`rule` string	Audience rules to be applied on the referrer URL
`rule_aggregation` string	Aggregation on top of the rule, examples of aggregations include: count, sum etc
`subtype` string	Type of custom audience, derived from original data source
`time_content_updated` unsigned int32	Last update of people in this custom audience
`time_created` unsigned int32	Creation time
`time_updated` unsigned int32	Last time this audience metadata was updated

Edges

Edge	Description
`adaccounts`	The ad account ids associated with this custom audience
`ads`	Ads that are using this custom audience
`prefills`	Status of the prefill jobs if they exist
`sessions`	Data upload sessions of this custom audience

Validation Rules

Error	Description
100	Invalid parameter
273	This Ads API call requires the user to be admin of the ad account
275	Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
16000	Specified audience is too small
274	The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API

Creating

Examples

Create a blank audience:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceSubtypes;

$audience = new CustomAudience(null, 'act_<AD_ACCOUNT_ID>');
$audience->setData(array(
  CustomAudienceFields::NAME => 'My new CA',
  CustomAudienceFields::SUBTYPE => CustomAudienceSubtypes::CUSTOM,
  CustomAudienceFields::DESCRIPTION => 'People who bought from my website',
));

$audience->create();

from facebookads.adobjects.customaudience import CustomAudience
from facebookads.adobjects.adaccount import AdAccount

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')

params = {
    CustomAudience.Field.subtype: CustomAudience.Subtype.custom,
    CustomAudience.Field.name: 'My new CA',
    CustomAudience.Field.description: 'People who bought on my website',
}
audience = ad_account.create_custom_audience(params=params)

CustomAudience customAudience = new AdAccount(act_<AD_ACCOUNT_ID>, context).createCustomAudience()
  .setName("My new CA")
  .setSubtype(CustomAudience.EnumSubtype.VALUE_CUSTOM)
  .setDescription("People who bought from my website")
  .execute();

curl \
  -F 'name=My new CA' \
  -F 'subtype=CUSTOM' \
  -F 'description=People who bought from my website' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/customaudiences

You can make a POST request to customaudiences edge from the following paths:

/act_{ad_account_id}/customaudiences

When posting to this edge, a CustomAudience will be created.

Parameters

Name	Description
`allowed_domains` list<string>	A list of domains that the audience is restricted to
`claim_objective` enum {AUTO_OFFER, HOME_LISTING, PRODUCT, TRAVEL}	Specifies the objective of audiences with subtype = CLAIM
`content_type` enum {AUTO_OFFER, DESTINATION, FLIGHT, HOME_LISTING, HOTEL}	Specifies a mandatory content type for claim_objective = TRAVEL
`dataset_id` numeric string or integer	The offline conversion dataset associated with this audience
`description` string	The description for this custom audience
`event_source_group` numeric string or integer	Specifies event source group for claim_objective = TRAVEL
`is_value_based` boolean	Whether the audience is used to seed value based lookalike
`list_of_accounts` list<int64>	List of user and page accounts
`lookalike_spec` JSON-encoded string	The specification for creating a lookalike audience
`name` string	The name of this custom audience
`opt_out_link` string	Your opt-out URL so people can choose not to be targeted
`origin_audience_id` numeric string or integer	The ID of origin Custom Audience. The origin audience you create must have a minimum size of 100.
`pixel_id` numeric string or integer	The pixel associated with this audience
`prefill` boolean	`true`: Include website traffic recorded prior to the audience creation. `false`: Only include website traffic beginning at the time of the audience creation.
`product_set_id` numeric string or integer	The Product Set to target with this audience
`retention_days` int64	Number of days to keep the user in this cluster. You can use any value between 1 and 365 days. Defaults to forever if not specified
`rule` string	Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences.
`rule_aggregation` string	Aggregation rule
`subtype` enum {CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, DATA_SET, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX}	Type of custom audience, derived from original data source. Note: `COMBINATION` subtype is only used by Power Editor and Ads Manager, and not available through the API. Audience size limit for selected subtype: CUSTOM: 500 WEBSITE: 200 APP: 200 LOOKALIKE: 10000 CLAIM: 500

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

You may perform a POST request to the following edge from this node:

/{custom_audience_id}/adaccounts

Validation Rules

Error	Description
16004	Study has too many StudyRules
100	Invalid parameter
2650	Failed to update the custom audience
200	Permissions error
2654	Failed to create custom audience
16002	Study is estimated as too broad
2651	Failed to create lookalike custom audience

Updating

If a person opted out of being targeted, you must remove the person from all custom audiences containing this person. To opt-out a person from audience after they have clicked through to your opt-out URL, make an HTTP DELETE call to:

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

Provide the same fields as you do in a user update.

This will remove the people you specify from ALL custom audiences belonging to the specified ad account.

Examples

To update the audience name:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;

$audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);

$audience->setData(array(
  CustomAudienceFields::NAME => 'Updated Name for CA',
));

$audience->update();

echo $audience->{CustomAudienceFields::NAME}.PHP_EOL;

from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience[CustomAudience.Field.name] = 'Updated name for CA'
audience.remote_update()

new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).update()
  .setName("Updated Name for CA")
  .execute();

curl \
  -F 'name=Updated Name for CA' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CUSTOM_AUDIENCE_ID>

To edit an Opt-out link:

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;

$audience = new CustomAudience(<CUSTOM_AUDIENCE_ID>);
$audience->setData(array(
  CustomAudienceFields::OPT_OUT_LINK => 'http://www.yourdomain.com/optout',
));

$audience->update();

echo $audience->{CustomAudienceFields::OPT_OUT_LINK}.PHP_EOL;

from facebookads.adobjects.customaudience import CustomAudience

audience = CustomAudience('<CUSTOM_AUDIENCE_ID>')
audience[CustomAudience.Field.opt_out_link] = \
    'http://www.yourdomain.com/optout'
audience.remote_update()

new CustomAudience(<CUSTOM_AUDIENCE_ID>, context).update()
  .setOptOutLink("http://www.yourdomain.com/optout")
  .execute();

curl \
  -F 'opt_out_link=http://www.yourdomain.com/optout' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/<CUSTOM_AUDIENCE_ID>

You can update a CustomAudience by making a POST request to /{custom_audience_id}.

Parameters

Name	Description
`allowed_domains` list<string>	A list of domains that the audience is restricted to
`claim_objective` enum {AUTO_OFFER, HOME_LISTING, PRODUCT, TRAVEL}	Specifies the objective of audiences with subtype = CLAIM
`content_type` enum {AUTO_OFFER, DESTINATION, FLIGHT, HOME_LISTING, HOTEL}	Specifies a mandatory content type for claim_objective = TRAVEL
`description` string	The description for this custom audience
`event_source_group` numeric string or integer	Specifies event source group for claim_objective = TRAVEL
`lookalike_spec` JSON-encoded string	The specification for creating a lookalike audience
`name` string	The name of this custom audience
`opt_out_link` string	Your opt-out URL so people can choose not to be targeted
`product_set_id` numeric string or integer	The Product Set to target with this audience
`retention_days` int64	Number of days to keep the user in this cluster. You can use any value between 1 and 365 days. Defaults to forever if not specified
`rule` string	Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences.
`rule_aggregation` string	Aggregation rule

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

You may perform a POST request to the following edge from this node:

/{custom_audience_id}/users

Validation Rules

Error	Description
16004	Study has too many StudyRules
100	Invalid parameter
2650	Failed to update the custom audience
200	Permissions error
2654	Failed to create custom audience
16002	Study is estimated as too broad
2651	Failed to create lookalike custom audience

Deleting

You can delete a CustomAudience by making a DELETE request to /{custom_audience_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps

ads_management

Page management Apps

No data

Other Apps

No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {

success: bool,

}

You may perform a DELETE request to the following edges from this node:

Validation Rules

Error	Description
2656	Failed to delete custom audience because associated lookalikes exist
200	Permissions error
100	Invalid parameter