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.

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 /v4.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>/',
    '{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 https://graph.facebook.com/v4.0/act_<AD_ACCOUNT_ID>/?fields=name

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

Field	Description
`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_role` numeric string	Role ID of the user
`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

Edge	Description
`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
`adreportschedules`	All scheduled reports of 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
`businessprojects`	Business projects
`campaigns`	The ad campaigns of this ad account
`campaignsbylabels`	Search campaigns associated with given labels within this ad account
`contextual_targeting_browse`	The context features which is used for contextual targeting
`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
`leadgen_forms`	A list of lead generation forms created for this Ad Account
`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
`partnerdata` Edge	partnerdata
`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
`reportstats` Edge	reportstats
`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

Error	Description
100	Invalid parameter
200	Permissions error
1150	An unknown error occurred.
80004	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.
80005	There have been too many leadgen api calls to this Page account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.
80000	There have been too many calls from 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.
2642	Invalid cursors values
278	Reading advertisements requires an access token with the extended permission ads_read
294	Managing advertisements requires an access token with the extended permission for ads_management

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 ad_accounts edge from the following paths:

/{custom_audience_id}/ad_accounts

When posting to this edge, an AdAccount will be created.

Parameters

Parameter	Description
`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

Error	Description
200	Permissions error

You can make a POST request to product_audiences edge from the following paths:

/act_{ad_account_id}/product_audiences

When posting to this edge, an AdAccount will be created.

Example

Graph API Explorer

POST /v4.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 \
     -d "name=Test+Iphone+Product+Audience" \
     -d "product_set_id=%3CPRODUCT_SET_ID%3E" \
     -d "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" \
     -d "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" \
        https://graph.facebook.com/v4.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

Parameter	Description
`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

Error	Description
200	Permissions error
100	Invalid parameter
2654	Failed to create custom audience

You can make a POST request to agencies edge from the following paths:

/act_{ad_account_id}/agencies

When posting to this edge, an AdAccount will be created.

Parameters

Parameter Description

Parameter	Description
`business` numeric string or integer	SELF_EXPLANATORY Required
`permitted_tasks` array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>	SELF_EXPLANATORY

business

numeric string or integer

SELF_EXPLANATORY

Required

permitted_tasks

array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>

SELF_EXPLANATORY

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.

Struct {

success: bool,

}

Validation Rules

Error	Description
3989	You are trying to assign a duplicated asset to this agency.
100	Invalid parameter
3946	Asset already belongs to this Business Manager.
200	Permissions error

You can make a POST request to client_ad_accounts edge from the following paths:

/{business_id}/client_ad_accounts

When posting to this edge, an AdAccount will be created.

Parameters

Parameter Description

Parameter	Description
`adaccount_id` string	The client's ad account. Required
`permitted_tasks` array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>	Permitted tasks on the ad account, such as `ANALYZE`.

adaccount_id

string

The client's ad account.

Required

permitted_tasks

array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>

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

Error	Description
100	Invalid parameter
3946	Asset already belongs to this Business Manager.
200	Permissions error
3989	You are trying to assign a duplicated asset to this agency.
3945	This 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:

/{business_id}/owned_ad_accounts

When posting to this edge, an AdAccount will be created.

Parameters

Parameter Description

Parameter	Description
`adaccount_id` string	Ad account ID. Required

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

Error	Description
100	Invalid parameter
3994	Personal 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.
3979	You have exceeded the number of allowed ad accounts for your Business Manager at this time.
3980	One 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.
3944	Your Business Manager already has access to this object.
3936	You've already tried to claim this ad account. You'll see a notification if your request is accepted.
5259	This ad account is closed. In order to continue advertising, you will need to create new ads.
200	Permissions error

You can make a POST request to locationclusters edge from the following paths:

/act_{ad_account_id}/locationclusters

When posting to this edge, an AdAccount will be created.

Parameters

Parameter Description

Parameter	Description
`locations` array<string>	locations Required

locations

array<string>

locations

Required

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.

Struct {

id: numeric string,

}

Validation Rules

Error	Description
100	Invalid parameter
200	Permissions error

You can make a POST request to adaccount edge from the following paths:

/{business_id}/adaccount

When posting to this edge, an AdAccount will be created.

Parameters

Parameter	Description
`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	This could be FBMP or FBX parthner 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,

}

Validation Rules

Error	Description
3979	You have exceeded the number of allowed ad accounts for your Business Manager at this time.
100	Invalid parameter
3980	One 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.
200	Permissions error
3902	There was a technical issue and your new ad account wasn't created. Please try again.
23007	This 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.
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
1150	An unknown error occurred.
294	Managing advertisements requires an access token with the extended permission for ads_management

Updating

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

Parameters

Parameter	Description
`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

Error	Description
200	Permissions error
100	Invalid parameter
5250	You cannot update your tax country from India to non-India.
23002	Input params are invalid.
294	Managing advertisements requires an access token with the extended permission for ads_management
2633	This shared login is disabled. Go to Ads Manager for more information.

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

Parameters

Parameter Description

Parameter	Description
`tasks` array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>	AdAccount permission tasks to assign this user
`user` int	Business user id or system user id Required

tasks

array<enum {MANAGE, ADVERTISE, ANALYZE, FB_EMPLOYEE_DSO_ADVERTISE, CREATIVE, DRAFT}>

AdAccount permission tasks to assign this user

user

int

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

Error	Description
100	Invalid parameter
200	Permissions error
5259	This ad account is closed. In order to continue advertising, you will need to create new ads.
2620	Invalid call to update account permissions

Deleting

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

Parameters

Parameter Description

Parameter	Description
`adaccounts` list<numeric string>	Array of ad account IDs to revoke access to the custom audience

adaccounts

list<numeric string>

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

Return Type

Struct {

success: bool,

}

Validation Rules

Error	Description
2652	Failed to share with a bad ad account
2658	You cannot edit this audience
100	Invalid parameter

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

Parameters

Parameter Description

Parameter	Description
`account_id` numeric string	SELF_EXPLANATORY Required
`business` numeric string or integer	SELF_EXPLANATORY Required

account_id

numeric string

SELF_EXPLANATORY

Required

business

numeric string or integer

SELF_EXPLANATORY

Required

Return Type

Struct {

success: bool,

}

Validation Rules

Error	Description
100	Invalid parameter