Marketing API
Graph API Version

Ad Account

Represents a business, person or other entity who creates and manage ads on Facebook. Multiple people can manage an account, and each person can have one or more levels of access to an account, see Business Manager API.

Ad Volume

View the volume of ads running or in review for your ad accounts. These ads will count against the ads limit per page that we will enact in early 2021. Query the number of ads running or in review for a given ad account.

To see the ads volume for your ad account:

curl -G 
  -d "access_token=<access_token>" 
  "https://graph.facebook.com/<API_VERSION>/<ad_account_ID>/ads_volume"

The response looks like this:

{"data":[{"ads_running_or_in_review_count":2}]}

For information on managing ads volume, see About Managing Ad Volume.

Running Or In Review

To see if an ad is running or in review, we check effective_status, configured_status, and the ad account's status:

  • If an ad has effective_status of 1 - active, we consider it a running or in review.
  • If an ad has configured_status of active and effective_status of 9 - pending review, or 17 - pending processing we consider it a running or in review.
  • The ad can be running or in review only if the ad account status is in 1 - active, 8 - pending settlement, 9 - in grace period.

We also determine if an ad is running or in review based on the ad set's schedule.

  • If start time is before current time, and current time is before end time, then we consider the ad running or in review.
  • If start time is before current time and the ad set has no end time, we also consider it running or in review.

For example, if the ad set is scheduled to run in the future, the ads are not running or in review. However if the ad set is scheduled to run from now until three months from now, we consider the ads running or in review.

If you are using special ads scheduling features, such as day-parting, we consider the ad running or in review the whole day, not just for the part of the day when the ad starts running.

Breakdown By Actors

We’ve added the show_breakdown_by_actor parameter to the act_123/ads_volume endpoint so you can query ad volume and ad limits-related information for each page. For more details, see Breakdown by Actors.

Example, Querying

For example, query for all ad sets in this ad account:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdSetFields;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$adsets = $account->getAdSets(array(
  AdSetFields::NAME,
  AdSetFields::CONFIGURED_STATUS,
  AdSetFields::EFFECTIVE_STATUS,
));

foreach ($adsets as $adset) {
  echo $adset->{AdSetFields::NAME}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet

account = AdAccount('act_<AD_ACCOUNT_ID>')
adsets = account.get_ad_sets(fields=[AdSet.Field.name])

for adset in adsets:
    print(adset[AdSet.Field.name])
APINodeList<AdSet> adSets = new AdAccount(act_<AD_ACCOUNT_ID>, context).getAdSets()
  .requestNameField()
  .requestConfiguredStatusField()
  .requestEffectiveStatusField()
  .execute();
curl -G \
  -d 'fields=name,configured_status,effective_status' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

Limits

Limits on number of ad accounts per user do not apply to Business Manager API, <AD_ACCOUNT_ID>/userpermissions. See Business Manager.

Limit Value

Maximum number of ad accounts per person

25

Maximum number of people with access, per ad account

25

Maximum number of ads per regular ad account

6,000 non-archived non-deleted ads

Maximum number of ads per bulk ad account

50,000 non-archived non-deleted ads

Maximum number of archived ads per ad account

100,000 archived ads

Maximum number of ad sets per regular ad account

6,000 non-archived non-deleted ad sets

Maximum number of ad sets per bulk ad account

10,000 non-archived non-deleted ad sets

Maximum number of archived ad sets per ad account

100,000 archived ad sets

Maximum number of ad campaigns per regular ad account

6,000 non-archived non-deleted ad campaigns

Maximum number of ad campaigns per bulk ad account

10,000 non-archived non-deleted ad campaigns

Maximum number of archived ad campaigns per ad account

100,000 archived ad campaigns

Maximum number of images per ad account

Unlimited

Reading

An ad account is an account used for managing ads on Facebook

Finding people with access to this account:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\UserFields;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$users = $account->getUsers();

foreach ($users as $user) {
  echo $user->{UserFields::ID}.PHP_EOL;
}
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adaccountuser import AdAccountUser

account = AdAccount('act_<AD_ACCOUNT_ID>')
users = account.get_users()
for user in users:
    print(user[AdAccountUser.Field.id])
APINodeList<AdAccountUser> adAccountUsers = new AdAccount(act_<AD_ACCOUNT_ID>, context).getUsers()
  .execute();
curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/users

Get list of accepted Terms of Service, where id is the Facebook terms of service content id:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->read(array(
  AdAccountFields::TOS_ACCEPTED,
));

// Dump TOS Accepted info.
var_dump($account->{AdAccountFields::TOS_ACCEPTED});
from facebookads.adobjects.adaccount import AdAccount

account = AdAccount('act_<AD_ACCOUNT_ID>')
account.remote_read(fields=[AdAccount.Field.tos_accepted])

for tos in account[AdAccount.Field.tos_accepted]:
    print(tos)
AdAccount adAccount = new AdAccount(act_<AD_ACCOUNT_ID>, context).get()
  .requestTosAcceptedField()
  .execute();
curl -G \
  -d 'fields=tos_accepted' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>

Example

Graph API Explorer
GET /v8.0/act_<AD_ACCOUNT_ID>/?fields=name HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/act_<AD_ACCOUNT_ID>/?fields=name',
    '{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>/",
    {
        "fields": "name"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "name");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"fields": @"name",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET -G \
  -d 'fields="name"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v8.0/act_<AD_ACCOUNT_ID>/
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

FieldDescription
id
string

The string act_{ad_account_id}.

Default
account_id
numeric string

The ID of the Ad Account.

Default
account_status
unsigned int32

Status of the account:
1 = ACTIVE
2 = DISABLED
3 = UNSETTLED
7 = PENDING_RISK_REVIEW
8 = PENDING_SETTLEMENT
9 = IN_GRACE_PERIOD
100 = PENDING_CLOSURE
101 = CLOSED
201 = ANY_ACTIVE
202 = ANY_CLOSED

ad_account_creation_request
AdAccountCreationRequest

Ad Account creation request associated with this Ad Account.

ad_account_promotable_objects
AdAccountPromotableObjects

Ad Account creation request purchase order fields associated with this Ad Account.

age
float

Amount of time the ad account has been open, in days.

agency_client_declaration
AgencyClientDeclaration

Details of the agency advertising on behalf of this client account, if applicable. Note that you need to be a business admin to access this information.

amount_spent
numeric string

Current total amount spent by the account. This can be reset.

attribution_spec
list<AttributionSpec>

The attribution specification of Ad Account, including click through window length, view through window length, etc.

balance
numeric string

Bill amount due for this Ad Account.

business
Business

The Business Manager, if this ad account is owned by one

business_city
string

City for business address

business_country_code
string

Country code for the business address

business_name
string

The business name for the account

business_state
string

State abbreviation for business address

business_street
string

First line of the business street address for the account

business_street2
string

Second line of the business street address for the account

business_zip
string

Zip code for business address

can_create_brand_lift_study
bool

If we can create a new automated brand lift study under the Ad Account.

capabilities
list<string>

List of capabilities an Ad Account can have. See capabilities

created_time
datetime

The time the account was created in ISO 8601 format.

currency
string

The currency used for the account, based on the corresponding value in the account settings. See supported currencies

direct_deals_tos_accepted
bool

Whether DirectDeals ToS are accepted.

disable_reason
unsigned int32

The reason why the account was disabled. Possible reasons are:
0 = NONE
1 = ADS_INTEGRITY_POLICY
2 = ADS_IP_REVIEW
3 = RISK_PAYMENT
4 = GRAY_ACCOUNT_SHUT_DOWN
5 = ADS_AFC_REVIEW
6 = BUSINESS_INTEGRITY_RAR
7 = PERMANENT_CLOSE
8 = UNUSED_RESELLER_ACCOUNT
9 = UNUSED_ACCOUNT

end_advertiser
numeric string

The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID.

end_advertiser_name
string

The name of the entity the ads will target.

extended_credit_invoice_group
ExtendedCreditInvoiceGroup

The extended credit invoice group that the ad account belongs to

failed_delivery_checks
list<DeliveryCheck>

Failed delivery checks

fb_entity
unsigned int32

fb_entity

funding_source
numeric string

ID of the payment method. If the account does not have a payment method it will still be possible to create ads but these ads will get no delivery. Not available if the account is disabled

funding_source_details
FundingSourceDetails

ID = ID of the payment method
COUPON = Details of the Facebook Ads Coupon from the payment method
AMOUNT = Amount of Facebook Ads Coupon
CURRENCY = Currency of the Facebook Ads Coupon
DISPLAY_AMOUNT = How the amount of Facebook Ads Coupon is displayed
EXPIRATION = When the coupon will expire
DISPLAY_STRING = How the payment method is shown
TYPE = Type of the funding source
0 = UNSET
1 = CREDIT_CARD
2 = FACEBOOK_WALLET
3 = FACEBOOK_PAID_CREDIT
4 = FACEBOOK_EXTENDED_CREDIT
5 = ORDER
6 = INVOICE
7 = FACEBOOK_TOKEN
8 = EXTERNAL_FUNDING
9 = FEE
10 = FX
11 = DISCOUNT
12 = PAYPAL_TOKEN
13 = PAYPAL_BILLING_AGREEMENT
14 = FS_NULL
15 = EXTERNAL_DEPOSIT
16 = TAX
17 = DIRECT_DEBIT
18 = DUMMY
19 = ALTPAY
20 = STORED_BALANCE

has_migrated_permissions
bool

Whether this account has migrated permissions

has_page_authorized_adaccount
bool

Indicates whether a Facebook page has authorized this ad account to place ads with political content. If you try to place an ad with political content using this ad account for this page, and this page has not authorized this ad account for ads with political content, your ad will be disapproved. See Breaking Changes, Marketing API, Ads with Political Content and Facebook Advertising Policies

io_number
numeric string

The Insertion Order (IO) number.

is_attribution_spec_system_default
bool

If the attribution specification of ad account is generated from system default values

is_direct_deals_enabled
bool

Whether the account is enabled to run Direct Deals

is_in_3ds_authorization_enabled_market
bool

If the account is in a market requiring to go through payment process going through 3DS authorization

is_in_middle_of_local_entity_migration
bool

If the account is in the peroid localization project rolling out

is_notifications_enabled
bool

Get the notifications status of the user for this ad account. This will return true or false depending if notifications are enabled or not

is_personal
unsigned int32

Indicates if this ad account is being used for private, non-business purposes. This affects how value added tax (VAT) is assessed. NOTE: This does is not related to whether an Ad Account is attached to a business.

is_prepay_account
bool

If this ad account is a prepay. Other option would be a postpay account.

is_tax_id_required
bool

If tax id for this ad account is required or not

line_numbers
list<integer>

The line numbers

media_agency
numeric string

The agency, this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use NONE or UNFOUND.

min_campaign_group_spend_cap
numeric string

The minimum required spend cap of Ad Campaign.

min_daily_budget
unsigned int32

The minimum daily budget for this Ad Account

name
string

Name of the account. If not set, the name of the first admin visible to the user will be returned.

offsite_pixels_tos_accepted
bool

Indicates whether the offsite pixel Terms Of Service contract was signed. This feature can be accessible before v2.9

owner
numeric string

The ID of the account owner

partner
numeric string

This could be Facebook Marketing Partner, if there is one. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use NONE or UNFOUND.

rf_spec
ReachFrequencySpec

Reach and Frequency limits configuration. See Reach and Frequency

show_checkout_experience
bool

Whether or not to show the pre-paid checkout experience to an advertiser. If true, the advertiser is eligible for checkout, or they are already locked in to checkout and haven't graduated to postpay.

spend_cap
numeric string

The maximum amount that can be spent by this Ad Account. When the amount is reached, related Ad Campaigns are paused. A value of 0 means no spending-cap. Setting a new spend cap only applies to spend AFTER the time at which you set it. Value specified in basic unit of the currency, for example 'cents' for USD.

tax_id
string

Tax ID

tax_id_status
unsigned int32

VAT status code for the account.
0: Unknown
1: VAT not required- US/CA
2: VAT information required
3: VAT information submitted
4: Offline VAT validation failed
5: Account is a personal account

tax_id_type
string

Type of Tax ID

timezone_id
unsigned int32

The timezone ID of this ad account

timezone_name
string

Name for the time zone

timezone_offset_hours_utc
float

Time zone difference from UTC (Coordinated Universal Time).

tos_accepted
map<string, int32>

Checks if this specific ad account has signed the Terms of Service contracts. Returns 1, if terms were accepted.

user_tasks
list<string>

user_tasks

user_tos_accepted
map<string, int32>

Checks if a user has signed the Terms of Service contracts related to the Business that contains a specific ad account. Must include user's access token to get information. This verification is not valid for system users.

Edges

EdgeDescription
activities

The activities of this ad account

ad_place_page_sets

The associated ad place page sets for this ad account

ad_studies

The ad studies containing this ad account

adcreatives

The ad creatives of this ad account

adcreativesbylabels

Search creatives associated with given labels within this ad account

adimages

The images associated with this account

adlabels

The labels associated with this ad account

adrules_history

A list of all ad rule execution history for all scheduled and triggered rules under this account. There will be one entry per object

adrules_library

The ad library rules associated with this ad account

ads

The ads of this ad account

adsbylabels

Search ads associated with given labels within this ad account

adsets

The adsets of this ad account

adsetsbylabels

Search ad sets associated with given labels within this ad account

adspixels

The associated tracking pixels for this ad account

advertisable_applications

All advertisable apps associated with this account

advideos

The videos associated with this account

applications

Applications connected to the ad accounts

assigned_users

Users assigned to this Ad Account

async_requests

The async requests associated with this account

asyncadrequestsets

The async ad request sets associated with this account

broadtargetingcategories

Broad targeting categories (BCTs) can be used for targeting

campaigns

The ad campaigns of this ad account

campaignsbylabels

Search campaigns associated with given labels within this ad account

customaudiences

The custom audiences owned by/shared with this ad account

customaudiencestos

The custom audiences term of services available to the ad account

delivery_estimate

The delivery estimate for a given ad set configuration for this ad account

deprecatedtargetingadsets

Ad sets with deprecating targeting options for this ad account

generatepreviews

Generate previews for a creative specification

impacting_ad_studies

The ad studies that contain this ad account or any of its descendant ad objects

instagram_accounts

Instagram accounts connected to the ad accounts

matched_search_applications

All advertisable apps associated with this account plus apps from app store that matched search input

max_bid

The max allowed bid. The bid's unit is cent for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW.

minimum_budgets

Returns minimum daily budget values by currency

offline_conversion_data_sets

List of Offline Conversion Data Sets available for this Ad Account

onbehalf_requests

The on behalf of requests attached to this Ad Account

promote_pages

All pages that have been promoted under the ad account

publisher_block_lists

Publisher block lists owned by this account. These list are used to block publishers on Audience Network

reachestimate

The reach estimate of a given targeting spec for this ad account

reachfrequencypredictions

The reach and frequency predictions of this ad account

roas

The return on ad spend

targetingbrowse

Unified browse

targetingsearch

Unified search

targetingsentencelines

The targeting description sentence for a given target spec

targetingsuggestions

Unified suggestions

targetingvalidation

Unified validation

tracking

List of tracking specs for this Ad Account

users

Container for the user ID, permissions, and role

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
80004There 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.
1150An unknown error occurred.
190Invalid OAuth 2.0 Access Token
368The action attempted has been deemed abusive or is otherwise disallowed
294Managing advertisements requires an access token with the extended permission for ads_management
2642Invalid cursors values

Creating

To create a new ad account for your business you must specify name, currency, timezone_id, end_advertiser, media_agency, and partner. Provide end_advertiser, media_agency, and partner:

  • They must be Facebook Page Aliases, Facebook Page ID or an Facebook app ID. For example, to provide your company as an end advertiser you specify my company or 20531316728.

  • If your ad account has no End Advertiser, Media Agency, or Partner, specify NONE.

  • If your ad account has an End Advertiser, Media Agency, or Partner, that are not represented on Facebook by Page or app, specify UNFOUND.

Once you set end_advertiser to a value other than NONE or UNFOUND you cannot change it.

Create an ad account: 

curl \
-F "name=MyAdAccount" \
-F "currency=USD" \
-F "timezone_id=1" \
-F "end_advertiser=<END_ADVERTISER_ID>" \
-F "media_agency=<MEDIA_AGENCY_ID>" \
-F "partner=NONE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/adaccount"

If you have an extended credity line with Facebook, you can set invoice to true and we associate your new ad account to this credit line.

The response: 

{
  "id": "act_<ADACCOUNT_ID>",
  "account_id": "<ADACCOUNT_ID>",
  "business_id": "<BUSINESS_ID>",
  "end_advertiser_id": "<END_ADVERTISER_ID>",
  "media_agency_id": "<MEDIA_AGENCY_ID>",
  "partner_id": "NONE"
}

You can make a POST request to product_audiences edge from the following paths:
When posting to this edge, an AdAccount will be created.

Example

Graph API Explorer
POST /v8.0/act_<AD_ACCOUNT_ID>/product_audiences HTTP/1.1
Host: graph.facebook.com

name=Test+Iphone+Product+Audience&product_set_id=%3CPRODUCT_SET_ID%3E&inclusions=%5B%7B%22retention_seconds%22%3A86400%2C%22rule%22%3A%7B%22and%22%3A%5B%7B%22event%22%3A%7B%22eq%22%3A%22AddToCart%22%7D%7D%2C%7B%22userAgent%22%3A%7B%22i_contains%22%3A%22iPhone%22%7D%7D%5D%7D%7D%5D&exclusions=%5B%7B%22retention_seconds%22%3A172800%2C%22rule%22%3A%7B%22event%22%3A%7B%22eq%22%3A%22Purchase%22%7D%7D%7D%5D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/product_audiences',
    array (
      'name' => 'Test Iphone Product Audience',
      'product_set_id' => '<PRODUCT_SET_ID>',
      'inclusions' => '[{"retention_seconds":86400,"rule":{"and":[{"event":{"eq":"AddToCart"}},{"userAgent":{"i_contains":"iPhone"}}]}}]',
      'exclusions' => '[{"retention_seconds":172800,"rule":{"event":{"eq":"Purchase"}}}]',
    ),
    '{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>/product_audiences",
    "POST",
    {
        "name": "Test Iphone Product Audience",
        "product_set_id": "<PRODUCT_SET_ID>",
        "inclusions": "[{\"retention_seconds\":86400,\"rule\":{\"and\":[{\"event\":{\"eq\":\"AddToCart\"}},{\"userAgent\":{\"i_contains\":\"iPhone\"}}]}}]",
        "exclusions": "[{\"retention_seconds\":172800,\"rule\":{\"event\":{\"eq\":\"Purchase\"}}}]"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "Test Iphone Product Audience");
params.putString("product_set_id", "<PRODUCT_SET_ID>");
params.putString("inclusions", "[{\"retention_seconds\":86400,\"rule\":{\"and\":[{\"event\":{\"eq\":\"AddToCart\"}},{\"userAgent\":{\"i_contains\":\"iPhone\"}}]}}]");
params.putString("exclusions", "[{\"retention_seconds\":172800,\"rule\":{\"event\":{\"eq\":\"Purchase\"}}}]");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/product_audiences",
    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": @"Test Iphone Product Audience",
  @"product_set_id": @"<PRODUCT_SET_ID>",
  @"inclusions": @"[{\"retention_seconds\":86400,\"rule\":{\"and\":[{\"event\":{\"eq\":\"AddToCart\"}},{\"userAgent\":{\"i_contains\":\"iPhone\"}}]}}]",
  @"exclusions": @"[{\"retention_seconds\":172800,\"rule\":{\"event\":{\"eq\":\"Purchase\"}}}]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/product_audiences"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'name="Test Iphone Product Audience"' \
  -F 'product_set_id="<PRODUCT_SET_ID>"' \
  -F 'inclusions=[
       {
         "retention_seconds": 86400,
         "rule": {
           "and": [
             {
               "event": {
                 "eq": "AddToCart"
               }
             },
             {
               "userAgent": {
                 "i_contains": "iPhone"
               }
             }
           ]
         }
       }
     ]' \
  -F 'exclusions=[
       {
         "retention_seconds": 172800,
         "rule": {
           "event": {
             "eq": "Purchase"
           }
         }
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v8.0/act_<AD_ACCOUNT_ID>/product_audiences
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
associated_audience_id
int64

SELF_EXPLANATORY

creation_params
dictionary { string : <string> }

SELF_EXPLANATORY

description
string

SELF_EXPLANATORY

enable_fetch_or_create
boolean

enable_fetch_or_create

event_sources
array<JSON object>

event_sources

exclusions
list<Object>

SELF_EXPLANATORY

booking_window
Object

min_seconds
int64

max_seconds
int64

count
Object

event
string

type
enum {CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE}

retention
Object

min_seconds
integer

Required
max_seconds
integer

Required
retention_days
int64

retention_seconds
integer

rule
Object

pixel_id
int64

inclusions
list<Object>

SELF_EXPLANATORY

booking_window
Object

min_seconds
int64

max_seconds
int64

count
Object

event
string

type
enum {CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE}

retention
Object

min_seconds
integer

Required
max_seconds
integer

Required
retention_days
int64

retention_seconds
integer

rule
Object

pixel_id
int64

name
string

SELF_EXPLANATORY

Required
opt_out_link
string

SELF_EXPLANATORY

parent_audience_id
int64

SELF_EXPLANATORY

product_set_id
numeric string or integer

SELF_EXPLANATORY

Required
subtype
enum {CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, PARTNER, MANAGED, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE}

SELF_EXPLANATORY

tags
list<string>

SELF_EXPLANATORY

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: numeric string,
message: string,
}

Validation Rules

ErrorDescription
2654Failed to create custom audience
100Invalid parameter
200Permissions error
You can make a POST request to agencies edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

ParameterDescription
business
numeric string or integer

SELF_EXPLANATORY

Required
permitted_tasks
array<enum {MANAGE, ADVERTISE, ANALYZE}>

SELF_EXPLANATORY

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
3989You are trying to assign a duplicated asset to this agency.
100Invalid parameter
3946Asset already belongs to this Business Manager.
200Permissions error
368The action attempted has been deemed abusive or is otherwise disallowed
You can make a POST request to client_ad_accounts edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

ParameterDescription
adaccount_id
string

The client's ad account.

Required
permitted_tasks
array<enum {MANAGE, ADVERTISE, ANALYZE}>

Permitted tasks on the ad account, such as ANALYZE.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_status: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
3946Asset already belongs to this Business Manager.
200Permissions error
3989You are trying to assign a duplicated asset to this agency.
3945This Business Manager has a pending ownership request to this object. Please cancel or decline it to continue.
You can make a POST request to owned_ad_accounts edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

ParameterDescription
adaccount_id
string

Ad account ID.

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_status: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
3994Personal accounts that do not have any history of activity are not eligible for migration to a business manager. Instead create an ad account inside your business manager.
3979You have exceeded the number of allowed ad accounts for your Business Manager at this time.
3980One or more of the ad accounts in your Business Manager are currently in bad standing or in review. All of your accounts must be in good standing in order to create new ad accounts.
368The action attempted has been deemed abusive or is otherwise disallowed
3944Your Business Manager already has access to this object.
3936You've already tried to claim this ad account. You'll see a notification if your request is accepted.
200Permissions error
You can make a POST request to ad_accounts edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

ParameterDescription
adaccounts
list<numeric string>

Array of new ad account IDs to receive access to the custom audience

permissions
string

targeting or targeting_and_insights. If targeting the recipient ad account can target the audience in ads. targeting_and_insights also allows recipient account to view the audience in Audience Insights tool

relationship_type
array<string>

relationship_type

replace
boolean

true or false. If true the list of adaccounts provided in the call will replace the existing set of ad accounts this audience is shared with.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
sharing_data: List [
Struct {
ad_acct_id: string,
business_id: numeric string,
audience_share_status: string,
errors: List [
string
],
}
],
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to adaccount edge from the following paths:
When posting to this edge, an AdAccount will be created.

Parameters

ParameterDescription
ad_account_created_from_bm_flag
boolean

ad_account_created_from_bm_flag

currency
ISO 4217 Currency Code

The currency used for the account

Required
end_advertiser

The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use NONE or UNFOUND. Note that once a value other than NONE or UNFOUND is set, it cannot be modified any more.

Required
funding_id
numeric string or integer

ID of the payment method. If the account does not have a payment method it will still be possible to create ads but these ads will get no delivery.

invoice
boolean

If business manager has Business Manager Owned Normal Credit Line on file on the FB CRM, it will attach the ad account to that credit line.

invoice_group_id
extended_credit_invoice_group ID

The ID of the invoice group this adaccount should be enrolled in

invoicing_emails
array<string>

Emails addressed where invoices will be sent.

io
boolean

If corporate channel is direct sales.

media_agency
string

The agency, this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use NONE or UNFOUND

Required
name
string

The name of the ad account

Required
partner
string

The advertising partner for this account, if there is one. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID. In absence of one, you can use NONE or UNFOUND.

Required
po_number
string

Purchase order number

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
id: token with structure: AdAccount ID,
account_id: numeric string,
business_id: numeric string,
end_advertiser_id: string,
media_agency_id: string,
partner_id: string,
seer_ad_account_restricted_by_soft_desc_challenge: bool,
soft_desc_challenge_credential_id: string,
soft_desc_challenge_localized_auth_amount: int32,
}

Validation Rules

ErrorDescription
100Invalid parameter
3979You have exceeded the number of allowed ad accounts for your Business Manager at this time.
3980One or more of the ad accounts in your Business Manager are currently in bad standing or in review. All of your accounts must be in good standing in order to create new ad accounts.
23007This credit card can't be set as your account's primary payment method, because your account is set up to be billed after your ads have delivered. This setup can't be changed. Please try a different card or payment method.
3902There was a technical issue and your new ad account wasn't created. Please try again.
200Permissions error
270This 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
368The action attempted has been deemed abusive or is otherwise disallowed
1150An unknown error occurred.

Updating

You can update an AdAccount by making a POST request to /act_{ad_account_id}.

Parameters

ParameterDescription
agency_client_declaration
dictionary { string : <string> }

Details of the agency advertising on behalf of this client account

attribution_spec
list<Object>

The account attribution specification.
1. CLICK_THROUGH element must be present
2. If VIEW_THROUGH is present, window_days of VIEW_THROUGH must be smaller than or equal to that of CLICK_THROUGH

event_type
enum {CLICK_THROUGH, VIEW_THROUGH}

Required
window_days
int64

Required
business_info
dictionary { string : <string> }

Business Info

end_advertiser
numeric string

The entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or an Facebook App ID.

is_notifications_enabled
boolean

If notifications are enabled or not for this account

media_agency
numeric string

The ID of a Facebook Page or Facebook App. Once it is set to any values other than NONE or UNFOUND, it cannot be modified any more

name
string

The name of the ad account

partner
numeric string

The ID of a Facebook Page or Facebook App. Once it is set to any values other than NONE or UNFOUND, it cannot be modified any more

spend_cap
float

The total amount that this account can spend, after which all campaigns will be paused, based on amount_spent. A value of 0 signifies no spending-cap and setting a new spend cap only applies to spend AFTER the time at which you set it. Value specified in standard denomination of the currency, e.g. 23.50 for USD $23.50.

spend_cap_action
string

Setting this parameter to reset sets the amount_spent back to 0. Setting it to delete removes the spend_cap from the account.

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
5274Please make sure you've entered a valid tax info.
5250You cannot update your tax country from India to non-India.
190Invalid OAuth 2.0 Access Token
23002Input params are invalid.
1150An unknown error occurred.
You can update an AdAccount by making a POST request to /act_{ad_account_id}/assigned_users.

Parameters

ParameterDescription
tasks
array<enum {MANAGE, ADVERTISE, ANALYZE}>

AdAccount permission tasks to assign this user

user
UID

Business user id or system user id

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
294Managing advertisements requires an access token with the extended permission for ads_management
2620Invalid call to update account permissions

Deleting

You can dissociate an AdAccount from an AdsPixel by making a DELETE request to /{ads_pixel_id}/shared_accounts.

Parameters

ParameterDescription
account_id
numeric string

SELF_EXPLANATORY

Required
business
numeric string or integer

SELF_EXPLANATORY

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate an AdAccount from a CustomAudience by making a DELETE request to /{custom_audience_id}/ad_accounts.

Parameters

ParameterDescription
adaccounts
list<numeric string>

Array of ad account IDs to revoke access to the custom audience

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
294Managing advertisements requires an access token with the extended permission for ads_management