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.
To use Custom Audiences, the Business’ users must first sign our Terms Of Service contracts. Learn more about Custom Audience Terms Of Service. To improve how advertisers create and manage their audiences, Custom Audiences that have not been used in any active ad sets in over two years will be automatically deleted on a rolling basis. For more information, see the Custom Audiences Overview documentation.
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 Facebook Platform Terms and Developer 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 fieldtos_accepted
of a given ad account. You can find more information at the ad account node documentation.
Starting September 14, 2021, the following fields will throw an error for version 12.0+ calls made by apps that lack the endpoint's required permissions. This change will apply to all versions on December 13, 2021.
external_event_source
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>
Parameter | Description |
---|---|
ad_account_id numeric string | ID of the recipient ad account in which custom audience is used. |
Field | Description |
---|---|
id numeric string | Custom audience ID |
account_id numeric string | Ad Account ID |
approximate_count_lower_bound integer | Lower bound of the approximate number of people in this audience. A call for this field returns |
approximate_count_upper_bound integer | Upper bound of the approximate number of people in this audience. A call for this field returns |
customer_file_source string | Source of customer information in the uploaded file |
data_source | JSON dictionary of |
delivery_status CustomAudienceStatus | 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 LookalikeSpec | Generated only when the subtype is |
name string | Custom audience name |
operation_status CustomAudienceStatus | JSON dictionary of
|
opt_out_link string | Your opt-out URL so people can choose not to be targeted |
permission_for_actions AudiencePermissionForActions | 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. Only available for Customer File Custom Audience, including Custom Audiences created from CRM data. |
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 |
sharing_status CustomAudienceSharingStatus | Sharing status of this custom audience for the ad account |
subtype string | Type of custom audience, derived from original data source. |
time_content_updated unsigned int32 | Last update of people in this custom audience, this field is only supported for Customer List Custom Audiences. |
time_created unsigned int32 | Creation time |
time_updated unsigned int32 | Last time this audience metadata was updated |
Edge | Description |
---|---|
Edge<CustomAudienceAdAccount> | The ad account ids associated with this custom audience |
Edge<Adgroup> | Ads that are using this custom audience |
Edge<CustomAudienceSession> | Data upload sessions of this custom audience |
Edge<CustomAudiencesharedAccountInfo> | List of Ad Accounts and Businesses this Audience is shared to |
Error | Description |
---|---|
100 | Invalid parameter |
80003 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience. |
200 | Permissions error |
190 | Invalid OAuth 2.0 Access Token |
270 | This Ads API request is not allowed for apps with development access level (Development access is by default for all apps, please request for upgrade). Make sure that the access token belongs to a user that is both admin of the app and admin of the ad account |
2500 | Error parsing graph query |
subtype
for engagement custom audiences is only supported for video.POST /{ad-account-id}/adsets
endpoint for iOS 14+ SKAdNetwork campaigns.Create a blank audience:
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/v21.0
/act_<AD_ACCOUNT_ID>/customaudiences
customaudiences
edge from the following paths: POST /v21.0/act_<AD_ACCOUNT_ID>/customaudiences HTTP/1.1
Host: graph.facebook.com
name=My+new+Custom+Audience&subtype=CUSTOM&description=People+who+purchased+on+my+website&customer_file_source=USER_PROVIDED_ONLY
/* 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 new Custom Audience',
'subtype' => 'CUSTOM',
'description' => 'People who purchased on my website',
'customer_file_source' => 'USER_PROVIDED_ONLY',
),
'{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 new Custom Audience",
"subtype": "CUSTOM",
"description": "People who purchased on my website",
"customer_file_source": "USER_PROVIDED_ONLY"
},
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
Bundle params = new Bundle();
params.putString("name", "My new Custom Audience");
params.putString("subtype", "CUSTOM");
params.putString("description", "People who purchased on my website");
params.putString("customer_file_source", "USER_PROVIDED_ONLY");
/* 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();
NSDictionary *params = @{
@"name": @"My new Custom Audience",
@"subtype": @"CUSTOM",
@"description": @"People who purchased on my website",
@"customer_file_source": @"USER_PROVIDED_ONLY",
};
/* 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 \
-F 'name="My new Custom Audience"' \
-F 'subtype="CUSTOM"' \
-F 'description="People who purchased on my website"' \
-F 'customer_file_source="USER_PROVIDED_ONLY"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
Parameter | Description |
---|---|
allowed_domains list<string> | A list of domains that the audience is restricted to. |
claim_objective enum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER} | Specifies the objective of audiences with |
content_type enum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER} | Specifies a mandatory content type for |
customer_file_source enum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED} | Source of customer information in the uploaded file. |
dataset_id numeric string or integer | The offline conversion dataset associated with this audience. |
description string | The description for this custom audience |
enable_fetch_or_create boolean | If |
event_source_group numeric string or integer | Specifies event source group for |
event_sources array<JSON object> | Specifies event sources for |
facebook_page_id numeric string or integer | facebook_page_id |
is_value_based boolean | Whether the audience is used to seed a new value based lookalike audience. |
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 | You can specify |
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 |
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 |
subscription_info list<enum {WHATSAPP, MESSENGER}> | subscription_info |
subtype enum {CUSTOM, PRIMARY, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, MANAGED, PARTNER, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE, BIDDING, SUBSCRIBER_SEGMENT, EXCLUSION, MESSENGER_SUBSCRIBER_LIST} | Type of custom audience, derived from original data source. |
use_for_products list<enum {ADS, MARKETING_MESSAGES}> | Default value: Vec use_for_products |
use_in_campaigns boolean | Default value: true use_in_campaigns |
id
in the return type.id
: numeric string, message
: string, Error | Description |
---|---|
200 | Permissions error |
100 | Invalid parameter |
2654 | Failed to create custom audience |
2663 | Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos |
80003 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience. |
190 | Invalid OAuth 2.0 Access Token |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
2667 | Your account permissions don't allow you to create a custom audience for this event source. |
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 file 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 /v21.0/<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();
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 \
-F 'name="Updated Name for CA"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<CUSTOM_AUDIENCE_ID>/
Parameter | Description |
---|---|
allowed_domains list<string> | A list of domains that the audience is restricted to |
claim_objective enum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER} | Specifies the objective of audiences with |
content_type enum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER} | Specifies a mandatory content type for |
customer_file_source enum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED} | Source of customer information in the uploaded file |
description string | The description for this custom audience |
enable_fetch_or_create boolean | Fetch custom audience instead of create new one when there exists custom audience with identical name, claim_objective, content_type, event_source_group/event_sources/sliced_event_source_group, inclusions, exclusions and rule |
event_source_group numeric string or integer | Specifies a mandatory content type for |
event_sources array<JSON object> | Specifies a mandatory content type for |
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. Only available for Customer File Custom Audience, including Custom Audiences created from CRM data. |
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 |
use_in_campaigns boolean | use_in_campaigns |
success
: bool, message
: string, Error | Description |
---|---|
100 | Invalid parameter |
200 | Permissions error |
2650 | Failed to update the custom audience |
80003 | There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience. |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
190 | Invalid OAuth 2.0 Access Token |
When you delete a Custom Audience, it'll be permanently removed from your account and your ads using it will stop running. You won't be able to restart any ads that used this audience in the past.
/{custom_audience_id}
.DELETE /v21.0/<CUSTOM_AUDIENCE_ID>/ HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
// Returns a `Facebook\FacebookResponse` object
$response = $fb->delete(
'/<CUSTOM_AUDIENCE_ID>/',
array (),
'{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>/",
"DELETE",
function (response) {
if (response && !response.error) {
/* handle the result */
}
}
);
/* make the API call */
new GraphRequest(
AccessToken.getCurrentAccessToken(),
"/<CUSTOM_AUDIENCE_ID>/",
null,
HttpMethod.DELETE,
new GraphRequest.Callback() {
public void onCompleted(GraphResponse response) {
/* handle the result */
}
}
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
initWithGraphPath:@"/<CUSTOM_AUDIENCE_ID>/"
parameters:params
HTTPMethod:@"DELETE"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
id result,
NSError *error) {
// Handle the result
}];
curl -X DELETE -G \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/<CUSTOM_AUDIENCE_ID>/
success
: bool, Error | Description |
---|---|
2656 | Failed to delete custom audience because associated lookalikes exist |
368 | The action attempted has been deemed abusive or is otherwise disallowed |
200 | Permissions error |
100 | Invalid parameter |