Beginning September 2, 2025, we will start to roll out more proactive restrictions on custom audiences that may suggest information not permitted under our terms. For example, any custom audience or lookalike audience suggesting specific health conditions (e.g., "arthritis", "diabetes") or financial status (e.g., "credit score", "high income") will be flagged and prevented from being used to run ad campaigns.
What these restrictions mean for your campaigns:
For API developers:
operation_status will return 471 to signal if your custom audiences have been flagged.More information on this update and how to resolve flagged custom audiences can be found here.
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, see the Custom Audience User reference.
To use custom audiences, business users must first sign our Terms Of Service.
To improve how audiences are created and managed, custom audiences that have not been used in any active ad sets in over two years will be deleted on a rolling basis automatically. See the Custom Audiences: Overview: Deletion for more information.
If one or more custom or lookalike audience is flagged with an operation_status of 471, the effective_status field of the ad set will change to WITH_ISSUES and the issues_info list will be populated with one issue per flagged audience. The fields_violating_integrity_policy field will be populated with the list of flagged fields.
Attempting to edit a flagged custom audience without changing the custom audience fields listed in the fields_violating_integrity_policy field will result in an error.
{
"error": {
"message": "Invalid parameter",
"code": 100,
"error_subcode": 1713231,
"error_user_title": "Update Restricted Fields and Rule",
"error_user_msg": "This custom audience has integrity restrictions. To continue, you must update the restricted fields and the rule in your current edit",
},
}
Attempting to edit a flagged lookalike audience or customer file custom audience (DFCA) will result in an error.
{
"error": {
"message": "Invalid parameter",
"code": 100,
"error_subcode": 1713228,
"error_user_title": "Custom Audience Cannot Be Edited",
"error_user_msg": "This audience cannot be edited due to integrity restrictions. Please appeal the restrictions or create a new audience",
},
}
Example
{
"account_id": "<OWNER_ACCOUNT_ID>",
"approximate_count": 5000,
"approximate_count_lower_bound": 4900,
"approximate_count_upper_bound": 5100,
"customer_file_source": "USER_PROVIDED_ONLY",
"description": "Audience Description",
"fields_violating_integrity_policy": ["<FIELD>", ...],
"id": "<CUSTOM_AUDIENCE_ID>",
"name": "Audience Name",
"operation_status": {
"code": 471,
"description": "The custom audience or lookalike is blocked because it suggests the use of information (e.g., health, financial) not allowed under Meta's terms, and is restricted from running ads. Review the audience and remove prohibited information, or choose a different one."
},
"retention_days": 0,
"subtype": "CUSTOM",
"time_created": 1755083743,
"time_updated": 1755083943,
"time_content_updated": 1755083943,
"owner_account_info": {
"account_id": "<OWNER_ACCOUNT_ID>",
"account_name": "Account Name",
"business_id": "<OWNER_BUSINESS_ID>",
"business_name": "Business Name"
},
...
}
If your custom or lookalike audiences are flagged, consider these options.
To resolve flagged custom audiences:
To resolve flagged lookalike audiences:
If you believe your custom audience or lookalike audience has been flagged in error and doesn't include non-permitted information, you can request a review via Ads Manager under the campaigns table or, or in Audience Manager by clicking on individual audiences and under the summary tab of the impacted audience.
Custom audiences are designed to provide advertisers the ability to target their ads to a specific set of people with whom they have already established a relationship on and off Facebook. Advertisers may choose to define audiences by email address, Facebook User IDs, 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 their website.
When utilizing Facebook User IDs please ensure you comply with Facebook Platform Terms and Developer Policies. You must accept the Custom Audience Terms of Service in order to use custom audiences. You can query which terms have been accepted by checking the tos_accepted field of a given ad account. See Ad Account for more information.
curl -G \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<CUSTOM_AUDIENCE_ID>
| Parameter | Description |
|---|---|
ad_account_idnumeric string | ID of the recipient ad account in which custom audience is used. |
special_ad_categorieslist<string> | special_ad_categories |
special_ad_category_countrieslist<string> | special_ad_category_countries |
| Field | Description |
|---|---|
idnumeric string | Custom audience ID |
account_idnumeric string | Ad Account ID |
approximate_count_lower_boundinteger | Lower bound of the approximate number of people in this audience. A call for this field returns |
approximate_count_upper_boundinteger | Upper bound of the approximate number of people in this audience. A call for this field returns |
customer_file_sourcestring | Source of customer information in the uploaded file |
data_source | JSON dictionary of |
delivery_statusCustomAudienceStatus | JSON dictionary of
|
descriptionstring | Custom audience description |
external_event_source | Read-only JSON dictionary with |
fields_violating_integrity_policylist<string> | A list of custom audience fields (either name, description or rule) that are flagged for a custom audience that may suggest information not permitted under our terms. |
is_value_basedbool | Whether the audience is used to seed value based lookalike |
lookalike_audience_idslist<numeric string> | The IDs of the lookalike audiences generated from this audience |
lookalike_specLookalikeSpec | Generated only when the subtype is |
namestring | Custom audience name |
operation_statusCustomAudienceStatus | JSON dictionary of
|
opt_out_linkstring | Your opt-out URL so people can choose not to be targeted |
permission_for_actionsAudiencePermissionForActions | JSON dictionary of permissions (string) to boolean value if the custom audience has that permission |
pixel_idnumeric string | ID of the pixel which is collecting events for this Website Custom audience |
retention_daysint32 | 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. |
rulestring | Audience rules to be applied on the referrer URL |
rule_aggregationstring | Aggregation on top of the rule, examples of aggregations include: count, sum etc |
sharing_statusCustomAudienceSharingStatus | Sharing status of this custom audience for the ad account |
subtypestring | Type of custom audience, derived from original data source. |
time_content_updatedunsigned int32 | Last update of people in this custom audience, this field is only supported for Customer List Custom Audiences. |
time_createdunsigned int32 | Creation time |
time_updatedunsigned 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<CustomAudienceHealth> | health |
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 field 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/v24.0/act_<AD_ACCOUNT_ID>/customaudiences
customaudiences edge from the following paths: POST /v24.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/v24.0/act_<AD_ACCOUNT_ID>/customaudiences| Parameter | Description |
|---|---|
allowed_domainslist<string> | A list of domains that the audience is restricted to. |
claim_objectiveenum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER} | Specifies the objective of audiences with |
content_typeenum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER} | Specifies a mandatory content type for |
customer_file_sourceenum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED} | Source of customer information in the uploaded file. |
dataset_idnumeric string or integer | The offline conversion dataset associated with this audience. |
descriptionstring | The description for this custom audience |
enable_fetch_or_createboolean | If |
event_source_groupnumeric string or integer | Specifies event source group for |
event_sourcesarray<JSON object> | Specifies event sources for |
facebook_page_idnumeric string or integer | facebook_page_id |
is_value_basedboolean | Whether the audience is used to seed a new value based lookalike audience. |
list_of_accountslist<int64> | List of user and page accounts |
lookalike_specJSON-encoded string | The specification for creating a lookalike audience. |
namestring | The name of this custom audience. |
opt_out_linkstring | Your opt-out URL so people can choose not to be targeted. |
origin_audience_idnumeric string or integer | The ID of origin Custom Audience.The origin audience you create must have a minimum size of 100. |
pixel_idnumeric string or integer | The pixel associated with this audience |
prefillboolean | You can specify |
product_set_idnumeric string or integer | The Product Set to target with this audience |
retention_daysint64 | Number of days to keep the user in this cluster. You can use any value between |
rulestring | Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences. |
rule_aggregationstring | Aggregation rule |
subscription_infolist<enum {WHATSAPP, MESSENGER}> | subscription_info |
subtypeenum {CUSTOM, PRIMARY, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, MANAGED, PARTNER, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE, BIDDING, EXCLUSION, MESSENGER_SUBSCRIBER_LIST} | Type of custom audience, derived from original data source. |
use_for_productslist<enum {ADS, MARKETING_MESSAGES}> | use_for_products |
use_in_campaignsboolean | Default value: trueuse_in_campaigns |
id in the return type.id: numeric string, message: string, | Error | Description |
|---|---|
| 200 | Permissions error |
| 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. |
| 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 |
| 190 | Invalid OAuth 2.0 Access Token |
| 368 | The action attempted has been deemed abusive or is otherwise disallowed |
| 2664 | The corporate terms of service has not been accepted. To accept, go to https://business.facebook.com/ads/manage/customaudiences/tos.php |
If a person opted out of being targeted, you must remove them from all custom audiences in which they appear. To opt-out a person from an audience after they have clicked through to your opt-out URL, make an HTTP DELETE call to:
https://graph.facebook.com/v24.0/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:
curl \
-F 'name=Updated Name for CA' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<CUSTOM_AUDIENCE_ID>
To edit an opt-out link:
curl \
-F 'opt_out_link=http://www.yourdomain.com/optout' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v24.0/<CUSTOM_AUDIENCE_ID>
/{custom_audience_id}.POST /v24.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/v24.0/<CUSTOM_AUDIENCE_ID>/| Parameter | Description |
|---|---|
allowed_domainslist<string> | A list of domains that the audience is restricted to |
claim_objectiveenum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER} | Specifies the objective of audiences with |
content_typeenum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER} | Specifies a mandatory content type for |
customer_file_sourceenum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED} | Source of customer information in the uploaded file |
descriptionstring | The description for this custom audience |
enable_fetch_or_createboolean | 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_groupnumeric string or integer | Specifies a mandatory content type for |
event_sourcesarray<JSON object> | Specifies a mandatory content type for |
lookalike_specJSON-encoded string | The specification for creating a lookalike audience |
namestring | The name of this custom audience |
opt_out_linkstring | Your opt-out URL so people can choose not to be targeted |
product_set_idnumeric string or integer | The Product Set to target with this audience |
rulestring | Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences. |
rule_aggregationstring | Aggregation rule |
use_in_campaignsboolean | 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. |
| 190 | Invalid OAuth 2.0 Access Token |
| 368 | The action attempted has been deemed abusive or is otherwise disallowed |
When you delete a custom audience, it will 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 /v24.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/v24.0/<CUSTOM_AUDIENCE_ID>/success: bool, | Error | Description |
|---|---|
| 200 | Permissions error |
| 2656 | Failed to delete custom audience because associated lookalikes exist |
| 368 | The action attempted has been deemed abusive or is otherwise disallowed |
| 100 | Invalid parameter |
| 613 | Calls to this api have exceeded the rate limit. |