Ad Account

Marketing API Version

An ad account is an account used to manage ads on Facebook. Each ad account can be managed by multiple people, and each person can have one or more different levels of access to an account, configured by specifying roles for each user.

Limits

The following are the limits on ad account.

This limit for number of ad accounts per user does not apply in context of the Business Manager when using the <AD_ACCOUNT_ID>/userpermissions API. More information available here.

Limit	Value
Maximum number of ad accounts per user	25
Maximum number of users per ad account	25
Maximum number of ads per regular ad account	5000 non-archived non-deleted ads
Maximum number of ads per bulk ad account	50000 non-archived non-deleted ads
Maximum number of archived ads per ad account	50k archived ads
Maximum number of ad sets per regular ad account	5000 non-archived non-deleted ad sets
Maximum number of ad sets per bulk ad account	10000 non-archived non-deleted ad sets
Maximum number of archived ad sets per ad account	50k archived ad sets
Maximum number of ad campaigns per regular ad account	5000 non-archived non-deleted ad campaigns
Maximum number of ad campaigns per bulk ad account	10000 non-archived non-deleted ad campaigns
Maximum number of archived ad campaigns per ad account	50k archived ad campaigns
Maximum number of images per ad account	Unlimited

Reading

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

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_groups` list<AdAccountGroupResult>	Container for the ID, name, and status of the ad account groups which contain this account
`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` `9 = IN_GRACE_PERIOD` `100 = PENDING_CLOSURE` `101 = CLOSED` `102 = PENDING_SETTLEMENT` `201 = ANY_ACTIVE` `202 = ANY_CLOSED`
`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
`amount_spent` numeric string	Current total amount spent by the account. This can be reset.
`balance` numeric string	Bill amount due
`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>	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
`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`
`end_advertiser` numeric string	The ID of a Facebook Page or Facebook App
`end_advertiser_name` string	The name of a Facebook Page or Facebook App
`failed_delivery_checks` list<DeliveryCheck>	Failed delivery checks
`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.
`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
`has_migrated_permissions` bool	Whether this account has migrated permissions
`io_number` numeric string	The IO number
`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 that this ad account is being used for private, non-business purposes which affects how value added tax (VAT) is assessed.
`is_prepay_account` bool	If this ad account is a prepay or 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 ID of a Facebook Page or Facebook Application
`min_campaign_group_spend_cap` numeric string	The minimum required spend cap of campaign group
`min_daily_budget` unsigned int32	The minimum daily budget for this ad account
`name` string	Name of the account. If the account name is 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. More details on offsite-pixels can be found here
`owner` numeric string	The ID of the account owner
`partner` numeric string	The ID of a Facebook Page or Facebook App
`rf_spec` ReachFrequencySpec	Reach and Frequency limits configuration. See Reach and Frequency
`spend_cap` numeric string	The maximum that can be spent by this account after which campaigns will be paused. 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 basic unit of the currency, e.g. 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
`tos_accepted` map<string, int32>	IDs of Terms of Service contracts signed
`user_role` numeric string	Role ID of the user

Edges

Edge	Description
`activities`	The activities of this ad account
`ad_place_page_sets`	The associated ad place page sets for 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
`adreportruns`	All bookmarked async runs of this ad account
`adreportschedules`	All scheduled reports of 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
`an_roas`	The audience network return on ad spend
`asyncadrequestsets`	The async ad request sets associated with this account
`broadtargetingcategories`	Broad targeting categories (BCTs) can be used for targeting
`business_activities`	The business activities related to this adaccount
`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
`generatepreviews`	Generate previews for a creative specification
`insights`	Insights on advertising performance of this ad account
`instagram_accounts`	Instagram accounts connected to the ad accounts
`minimum_budgets`	Returns minimum daily budget values by currency.
`offsitepixels`	Offsite pixels for this ad account
`partnercategories`	Partner categories can be used for targeting
`partners`	The ad partners of this ad account
`publisher_block_lists`	Publisher block lists owned by this account. These list are used to block publishers on Audience Network
`ratecard`	Rate card of an ad account
`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
`targetingsentencelines`	The targeting description sentence for a given target spec
`transactions`	The transactions of this ad account
`users`	Container for the user ID, permissions, and role

Validation Rules

Error	Description
100	Invalid parameter
278	Reading advertisements requires an access token with the extended permission ads_read

Creating

To create a new ad account for your business you must specify a name , currency , timezone_id, end_advertiser , media_agency , and partner . The latter 3 must be a Facebook Page Alias, Facebook Page ID or an Facebook app ID (for instance if you were going to mark your company as an end advertiser you would either specify my company or 20531316728 ). If your ad account doesn't have an End Advertiser, Media Agency, or Partner, please specify NONE . If your ad account has an End Advertiser, Media Agency, or Partner, but they are not represented on Facebook by either a Page or an app please specify UNFOUND . Note that for End Advertiser field, once a value other than NONE or UNFOUND is set it cannot be modified any more.

Examples

Sample call to 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"

Optionally, you may set the invoice to true. If you do your new ad account will be associated with your extended credit line. You must have already set up an extended credit line with Facebook to use this feature.

The response of this create call will be like this:

{
  "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 adaccounts edge from the following paths:

/{offsite_pixel_id}/adaccounts

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

Parameters

Name	Description
`adaccounts` list<string>	List of ad account IDs to add Required

Return Type

Struct {

success: bool,

}

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

Name	Description
`currency` ISO 4217 Currency Code	The currency used for the account Required
`end_advertiser` The type of this param is undocumented. If you are the owner of this param, please specify a developer-friendly type for it	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.
`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
`timezone_id` unsigned int32	ID for the timezone. See here. Required

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,

}

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

/{custom_audience_id}/adaccounts

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

Parameters

Name	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
`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

Struct {

success: bool,

}

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

/{business_id}/adaccounts

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

Parameters

Name	Description
`access_type` enum {OWNER, AGENCY}	access type Required
`adaccount_id` string	ID of ad account Required
`permitted_roles` list<enum {ADMIN, GENERAL_USER, REPORTS_ONLY, INSTAGRAM_ADVERTISER, INSTAGRAM_MANAGER, FB_EMPLOYEE_DSO_ADVERTISER}>	permitted roles

Return Type

Struct {

access_status: string,

}

You may perform a POST request to the following edges from this node:

Validation Rules

Error	Description
100	Invalid parameter
274	The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272	This Ads API call requires the user to be admin of the application

Updating

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

Parameters

Name	Description
`agency_client_declaration` dictionary	Details of the agency advertising on behalf of this client account
`business_info` dictionary	Business Info
`end_advertiser` 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
`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
`name` string	The name of the ad account
`partner` numeric string	The ID of a Facebook Page or Facebook App
`redownload` boolean	Allows you to specify that you would like toretrieve all fields of the set in your response.False by default.
`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 lowest denomination of the currency, e.g. cents for USD.
`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

Struct {

success: bool,

}

Validation Rules

Error	Description
100	Invalid parameter
274	The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
272	This Ads API call requires the user to be admin of the application

Deleting

You can dissociate an AdAccount from an AdAccountGroup by making a DELETE request to /{ad_account_group_id}/adaccounts.

Parameters

Name	Description
`account_id` numeric string	ID of the ad account Required

Return Type

Struct {

success: bool,

}

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

Parameters

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

Return Type

Struct {

success: bool,

}

You may perform a DELETE request to the following edges from this node:

Validation Rules

Error	Description
100	Invalid parameter