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.
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.ads_management
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.11/<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.11/act_<AD_ACCOUNT_ID>/customaudiences
Field | Description |
---|---|
id numeric string | Custom audience ID |
account_id numeric string | Ad Account ID |
approximate_count int32 | Approximate number of people in this audience |
data_source | JSON dictionary of |
delivery_status | JSON dictionary of |
description string | Custom audience description |
external_event_source | Read-only JSON dictionary with key |
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 | Generated only when the subtype is |
name string | Custom audience name |
operation_status | JSON dictionary of |
opt_out_link string | Your opt-out URL so people can choose not to be targeted |
permission_for_actions | 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 180 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 |
Edge | Description |
---|---|
The ad account ids associated with this custom audience | |
Ads that are using this custom audience | |
Status of the prefill jobs if they exist | |
Data upload sessions of this custom audience |
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. |
200 | Permissions error |
272 | This Ads API call requires the user to be admin of the application |
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.11/act_<AD_ACCOUNT_ID>/customaudiences
customaudiences
edge from the following paths: /act_{ad_account_id}
/customaudiences
POST /v2.12/act_{ad-account-id}/customaudiences HTTP/1.1
Host: graph.facebook.com
name=My+Test+Website+Custom+Audience&subtype=WEBSITE&retention_days=15&rule=%7B%22url%22%3A%7B%22i_contains%22%3A%22shoes%22%7D%7D&prefill=1&pixel_id=%7Bads-pixel-id%7D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->post(
'/act_{ad-account-id}/customaudiences',
array (
'name' => 'My Test Website Custom Audience',
'subtype' => 'WEBSITE',
'retention_days' => '15',
'rule' => '{"url":{"i_contains":"shoes"}}',
'prefill' => '1',
'pixel_id' => '{ads-pixel-id}',
),
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/act_{ad-account-id}/customaudiences",
"POST",
{
"name": "My Test Website Custom Audience",
"subtype": "WEBSITE",
"retention_days": "15",
"rule": "{\"url\":{\"i_contains\":\"shoes\"}}",
"prefill": "1",
"pixel_id": "{ads-pixel-id}"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My Test Website Custom Audience");
params.putString("subtype", "WEBSITE");
params.putString("retention_days", "15");
params.putString("rule", "{\"url\":{\"i_contains\":\"shoes\"}}");
params.putString("prefill", "1");
params.putString("pixel_id", "{ads-pixel-id}");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/act_{ad-account-id}/customaudiences",
params,
HttpMethod.POST,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
@"name": @"My Test Website Custom Audience",
@"subtype": @"WEBSITE",
@"retention_days": @"15",
@"rule": @"{\"url\":{\"i_contains\":\"shoes\"}}",
@"prefill": @"1",
@"pixel_id": @"{ads-pixel-id}",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/act_{ad-account-id}/customaudiences"
parameters:params
HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X POST \
-d "name=My+Test+Website+Custom+Audience" \
-d "subtype=WEBSITE" \
-d "retention_days=15" \
-d "rule=%7B%22url%22%3A%7B%22i_contains%22%3A%22shoes%22%7D%7D" \
-d "prefill=1" \
-d "pixel_id=%7Bads-pixel-id%7D" \
https://graph.facebook.com/v2.12/act_{ad-account-id}/customaudiences
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, VEHICLE} | Specifies the objective of audiences with subtype = CLAIM |
content_type enum {AUTO_OFFER, DESTINATION, FLIGHT, HOME_LISTING, HOTEL, VEHICLE, VEHICLE_OFFER} | 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 |
|
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 180 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. |
id
in the return type.id
: numeric string, Error | Description |
---|---|
100 | Invalid parameter |
16004 | Study has too many StudyRules |
2654 | Failed to create custom audience |
200 | Permissions error |
2651 | Failed to create lookalike custom audience |
2650 | Failed to update the custom audience |
2658 | You cannot edit this audience |
16002 | Study is estimated as too broad |
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.
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.11/<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.11/<CUSTOM_AUDIENCE_ID>
/{custom_audience_id}
.POST /v2.12/{custom-audience-id}/ HTTP/1.1
Host: graph.facebook.com
name=Updated+Name+for+CA
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->post(
'/{custom-audience-id}/',
array (
'name' => 'Updated Name for CA',
),
'{access-token}'
);
} catch(Facebook\Exceptions\FacebookResponseException $e) {
echo 'Graph returned an error: ' . $e->getMessage();
exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
echo 'Facebook SDK returned an error: ' . $e->getMessage();
exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
"/{custom-audience-id}/",
"POST",
{
"name": "Updated Name for CA"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "Updated Name for CA");
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/{custom-audience-id}/",
params,
HttpMethod.POST,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
@"name": @"Updated Name for CA",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/{custom-audience-id}/"
parameters:params
HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X POST \
-d "name=Updated+Name+for+CA" \
https://graph.facebook.com/v2.12/{custom-audience-id}/
ads_management
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, VEHICLE} | Specifies the objective of audiences with subtype = CLAIM |
content_type enum {AUTO_OFFER, DESTINATION, FLIGHT, HOME_LISTING, HOTEL, VEHICLE, VEHICLE_OFFER} | 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 180 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 |
success
: bool, Error | Description |
---|---|
100 | Invalid parameter |
16004 | Study has too many StudyRules |
2654 | Failed to create custom audience |
200 | Permissions error |
2651 | Failed to create lookalike custom audience |
2650 | Failed to update the custom audience |
2658 | You cannot edit this audience |
16002 | Study is estimated as too broad |
/{custom_audience_id}
.ads_management
success
: bool, Error | Description |
---|---|
2656 | Failed to delete custom audience because associated lookalikes exist |
200 | Permissions error |
100 | Invalid parameter |
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 |