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. |
id
Custom audience ID
account_id
Ad Account ID
approximate_count_lower_bound
Lower bound of the approximate number of people in this audience. A call for this field returns -1
for inactive lookalikes
.
approximate_count_upper_bound
Upper bound of the approximate number of people in this audience. A call for this field returns -1
for inactive lookalikes
.
customer_file_source
Source of customer information in the uploaded file
data_source
JSON dictionary of type
, sub_type
to indicate by which method the custom audience was created.
Note: Subtypes IG_BUSINESS_EVENTS
, FB_EVENT_SIGNALS
and MULTI_DATA_EVENTS
can only be created through Ads Manager, Audience Manager, and not through the API.
delivery_status
JSON dictionary of code
and description
. It indicates whether or not an audience can be used in ads. Possible values include:
200
: Returned if the audience is active and ready to be used.300
: Returned if the audience is smaller than it should be. This audience is currently inactive and cannot be used.400
and above: Returned if the audience is not usable for a variety of reasons, including policy violation.description
Custom audience description
external_event_source
Read-only JSON dictionary with key id
containing the pixel id whose
traffic generated this custom audience
is_value_based
Whether the audience is used to seed value based lookalike
lookalike_audience_ids
The IDs of the lookalike audiences generated from this audience
lookalike_spec
Generated only when the subtype is LOOKALIKE
. More info at Lookalike Audience
name
Custom audience name
operation_status
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 available100
: If an audience hasn't been used in an active ad set for over 2 years, it will begin to expire. Expiring audiences that remain unused for 90 days will be deleted.200
: Normal. There is no updating or issues found400
: Warning. There is some message we would like advertisers to know410
: No upload. No file has been uploaded411
: Low match rate. Low rate of matched people412
: High rate of invalid entries in the last upload session. Customer file has unusable data414
: Replace in progress415
: Replace failed421
: No pixel. Your Facebook pixel hasn't been installed on your website yet422
: Pixel not firing. Your Facebook pixel isn't firing423
: Invalid pixel. Your Facebook pixel is invalid431
: Lookalike Audience refresh failed432
: Lookalike Audience build failed433
: Lookalike Audience build failed434
: Lookalike Audience build retrying441
: We're finding people who fit your audience criteria. You can start running ads with this audience right away, but be aware that your audience size will increase as the audience is populated442
: Your Custom Audience could not be prefilled450
: This audience either hasn't been used in an ad for at least 30 days or was created over 90 days ago and has never been used. For this reason, your audience is out of date.470
: The account that created this audience is no longer active500
: Error: there is some error and advertisers need to take action items to fix the erroropt_out_link
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
ID of the pixel which is collecting events for this Website Custom audience
retention_days
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
Audience rules to be applied on the referrer URL
rule_aggregation
Aggregation on top of the rule, examples of aggregations include: count, sum etc
sharing_status
Sharing status of this custom audience for the ad account
subtype
Type of custom audience, derived from original data source.
Note: Subtypes IG_BUSINESS
, FB_EVENT
, EXPERIMENTAL
and MULTI_DATA
can only be created through Ads Manager, Audience Manager, and not through the API.
time_content_updated
Last update of people in this custom audience, this field is only supported for Customer List Custom Audiences.
time_created
Creation time
time_updated
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/ v20.0
/act_<AD_ACCOUNT_ID>/customaudiences
customaudiences
edge from the following paths:
POST /v20.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/v20.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 |
id
int64
|
id Required
|
type
enum {APP, OFFLINE_EVENTS, PAGE, PIXEL}
|
type Required
|
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 |
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}
|
Type of custom audience, derived from original data source. |
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 |
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. |
2663 | Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos |
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 /v20.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/v20.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 |
id
int64
|
id Required
|
type
enum {APP, OFFLINE_EVENTS, PAGE, PIXEL}
|
type Required
|
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 /v20.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/v20.0/<CUSTOM_AUDIENCE_ID>/
success
: bool,Error | Description |
---|---|
368 | The action attempted has been deemed abusive or is otherwise disallowed |
2656 | Failed to delete custom audience because associated lookalikes exist |
200 | Permissions error |
100 | Invalid parameter |