Business Asset Management

A business can access multiple assets—your business owns them or your business accesses them as an agency. You can use Facebook's Business Management Asset APIs to add, remove, or query the relationship between a business and its assets, and to manage business assets and access to them.

Ad Accounts

As a business admin, you can claim ad accounts that belong to a business. This enables you to easily assign people to the ad accounts they should access. You can then also assign Shared Funding Sources to your ad accounts.

Ad account groups cannot be claimed by a business. Users with access to certain ad account groups will still have access to them after those users are added to a Business Manager.

Claim Accounts

If you manage ad accounts outside of a Business Manager with the "Admin" role, you can claim them for your business. This is a one-time procedure. Once claimed, you can only manage the ad accounts in that Business Manager.

To claim an ad account for your business, you need the ad account ID, in the form act_###, send a POST:

curl \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_ad_accounts"

If you are an Admin of the ad account, we immediately approve this claim request. Facebook returns access_status set to CONFIRMED.

If you are a user who does not have the proper permissions on the ad account, we send an ownership request ad account Admins. Once we send the request, the response contains access_status set to PENDING.

To accept an ownership request, you must be an ad account admin, and you should log in and accept the request in Ads Manager.

Request Account Access

Most marketing companies won't need to claim ad accounts from their clients. See Business-to-Business Functions to request access to assets owned by other business managers.

Create Ad Accounts

You must be an admin for a business to create new ad accounts. You can't use shared logins of business admins to create new ad accounts or perform other actions.

To use this API, you must have a valid business and page setup. If you have any incomplete ad accounts or pages unpublished by Facebook, your calls fail.

The fields available are:

Name Description Type

name

Name of the ad account

string

timezone_id

ID of the timezone

int

currency

Currency abbrevation used for this ad account

string

partner

FBMP or FBX partner (if there is one). Must be a Facebook Page Alias, Facebook Page ID or a Facebook App ID. If unavailable, use NONE or UNFOUND.

long or string

end_advertiser

Entity the ads will target. Must be a Facebook Page Alias, Facebook Page ID or a Facebook App ID. If unavailable, use NONE or UNFOUND.

long or string

media_agency

Agency; this could be your own business. Must be a Facebook Page Alias, Facebook Page ID or a Facebook App ID. If unavailable, use NONE or UNFOUND.

long or string

invoice

If a business has a Business Manager-Owned Normal Credit Line with Facebook, we attach the ad account to that credit line.

boolean

To create a new ad account for a business, you must specify name, currency, timezone_id, end_advertiser, media_agency, and partner, where end_advertiser, media_agency, and partner must be a Facebook Page Alias, Facebook Page ID or a Facebook app ID. For example, to identify your company as an advertiser for itself, specify my company or 20531316728.

If your ad account doesn't have an advertiser, Media Agency, or Partner, specify NONE. If your ad account has an advertiser, Media Agency, or Partner, but they are not on Facebook as a Page or an app, specify UNFOUND .

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"

If you already have an extended credit line with Facebook, you can set invoice to true. We then associate your new ad account with your extended credit line.

The response looks 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"
}

View Owned Accounts

See all the ad accounts your business has access to with a GET call:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_ad_accounts"

This returns all ad accounts owned by a business. Some fields are specific to the business and ad account relationship. Look at access_status to see if your access is CONFIRMED or PENDING.

  • permitted_roles is an array of the roles you can assign for that particular ad account.

  • access_type defines if your business is acting as an OWNER or an AGENCY of the ad account.

To see ad accounts where the access is still pending, you can make this GET call:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_owned_ad_accounts"

Remove Accounts

You cannot remove ad accounts from your business if you're OWNER and if the accounts are CONFIRMED. If you have a PENDING access request or you have AGENCY access to the ad account, you can make this DELETE call:

curl \
-X DELETE \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_accounts"

View Account Access

See the ad accounts that someone has permission on with this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_SCOPED_USER_ID/assigned_ad_accounts"

To see permissions someone has for an ad account, make this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/act_AD_ACCOUNT_ID/assigned_users"

Add People to Accounts

After your Business Manager has an ad account, you can now assign your fellow business users roles on it, as follows:

Name API Constant Description

Reports Only

REPORTS_ONLY

Can see ad performance

General User

GENERAL_USER

Can see and edit ads and set up ads using the funding source associated with the ad account, but can't set account level

Admin

ADMIN

Can manage all aspects of campaigns, reporting, billing and account permissions

You need:

  • adaccount_id—Ad account ID (in act_123 form)
  • user_id—User ID to add
  • Role to assign

To add a new user as Admin, make this POST call:

curl \
-F "user=BUSINESS_SCOPED_USER_ID" \
-F "role=ADMIN" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/assigned_users"

Change Permissions on Accounts

Use the same POST call to change an existing user's role as you do to add a new user:

curl \
-F "user=BUSINESS_SCOPED_USER_ID" \
-F "role=REPORTS_ONLY" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/act_AD_ACCOUNT_ID/assigned_users"

Remove People from Ad Accounts

To remove someone from an account, you need:

  • adaccount_id—Ad account ID (in act_123 form)
  • user_id—User ID to remove

The DELETE call is:

curl \
-X DELETE \
-F "user=<BUSINESS_SCOPED_USER_ID>" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION>/act_AD_ACCOUNT_ID/assigned_users"

Pages

Businesses can claim pages that belong to them. This enables admins to easily assign people to pages they should have access too.

Claim Pages

To claim a page for your business as the OWNER, you need the page ID, and then send a POST request:

curl \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_pages"

To claim a page for your business as an AGENCY, you need the page ID, and then send a POST request:

curl \
-F "page_id=<PAGE_ID>" \
-F "permitted_roles=['ADVERTISER','INSIGHTS_ANALYST']" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages"

If you use AGENCY, you must provide permitted_roles.

This API request needs to use the access token of an Admin user or Admin system user of your business. If the user who makes the call is a Page Admin, or MANAGER, of the page for more than 7 days, the business immediately owns the Page. Facebook returns access_status in the response set to CONFIRMED. If someone becomes the Page Admin, or MANAGER, of the page in less than or equal to 7 days, we do not automatically approve the API request.

If the user who makes an OWNER claim call does not have the proper permissions on the Page, the call fails. Unlike claiming an ad account, no request is sent to the Page admins to be approved.

If you make an AGENCY claim, but do not have proper Page permissions, the response is PENDING. The Admin for that Page can log in and grant the access, deny it, or report the claim as a spam. If a business has too many Page access requests reported as spam, we lock the Business Manager.

To see all client pages you requested access to but are pending approval, make this GET call (note that the access token of the Admin system user token must be used):

curl -G \
-d "access_token=<ADMIN_SYSTEM_USER_ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_client_pages"

View Business-Owned Pages

To see all pages that your business owns, use this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_ID/owned_pages"

To see all pages your business is an agency of, use this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_ID/client_pages"

This returns a list of pages that belong to clients of a Business Manager. permitted_roles is an array of roles you can assign for that particular page.

Remove Pages

To remove a Page from the Business, make this DELETE call:

curl \
-X DELETE \
-F "page_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pages"

Add People to Pages

After your business has a page you can assign people roles on it. Roles include:

API Constant Description

MANAGER

Can manage admin roles, send messages and post as the Page, create ads and view insights.

CONTENT_CREATOR

Can edit the Page, send messages and post as the Page, create ads, and view insights.

ADVERTISER

Can create ads for the Page and view insights.

MODERATOR

Can respond to and delete comments on the Page, send messages as the Page, create ads, and view insights.

INSIGHTS_ANALYST

Can view insights.

You need:

  • page_id—ID of the page
  • user_id—User ID to add
  • Role to assign

Make this POST call to add someone as to a page Manager:

curl \
-F "user=BUSINESS_SCOPED_USER_ID" \
-F "role=MANAGER" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/PAGE_ID/assigned_users"

Change Pages Access

To change an existing user's role as you do to add a new user, use the same POST call:

curl \
-F "user=BUSINESS_SCOPED_USER_ID" \
-F "role=ADVERTISER" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/PAGE_ID/assigned_users"

View Page Permissions

To see pages with user permissions, make this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_SCOPED_USER_ID/assigned_pages"

To see specific permissions on a Page, make this GET call:

curl -G -d "access_token=ACCESS_TOKEN" "https://graph.facebook.com/VERSION/PAGE_ID/assigned_users?business=<business_id>"

Remove Page Access

Before you can remove a page from Business Manager, you must also remove the admins of that page from your business.

To remove someone's access from an Page you own, you need

  • page_id—ID of the Page
  • user_id—ID of the user to remove

The DELETE call is:

curl \
-X DELETE \
-F "user=BUSINESS_SCOPED_USER_ID" \
-F "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/PAGE_ID/assigned_users"

Apps

A Business Manager can claim apps that belong to a business. This enables you to easily manage apps associated with a business and advertising those apps.

The Business Manager-owned apps don't support role management. If you have to change app roles, you should do that from the app developer dashboard.

View Business-Owned Apps

To see all the applications your business owns:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/owned_apps"

This returns a list of apps associated with a Business Manager.

To see all client applications your business has access to or client applications, you have requested access to, but are pending approval:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_apps"
curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_client_apps"

The response contains permitted_roles. This is an array of the roles you can assign for that particular ad account.

Remove Apps from Business Manager

To remove an app from the Business Manager, make this DELETE call:

curl \
-X DELETE \
-F "app_id=<APP_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/apps"

Instagram Accounts

A Business Manager can claim Instagram Accounts that belong to the business. This enables a business to easily manage Instagram accounts and ad accounts used for these Instagram accounts.

You cannot manage roles for Instagram accounts owned by a business. You can only run ads for Instagram accounts with access to the ad accounts linked to the Instagram accounts.

Claim Instagram Account

To claim an Instagram account for your business, you must use the Business Manager UI. See Instagram Ads Setup.

Manage Instagram Accounts

You can use the API to manage relationship between a business and an Instagram account. See Instagram Ads Setup; you can:

  • Assign a business as an agency of a business' Instagram account
  • Delete an agency from an Instagram account
  • See all Instagram accounts accessible by a given business, either owned or as agency
  • See all agency businesses of a given Instagram account

There are also APIs to manage the relationship between ad accounts and Instagram accounts; see Instagram Ads Setup.

Product Catalog

Manage Product Catalogs for Dynamic Ads with Business Manager. Once you create a Product Catalog for a business, you can set up Product Feeds and Product Sets.

See Product Catalog, Reference.

Viewing Business-Owned Product Catalogs

To see all product catalogs that your business owns, use this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_ID/owned_product_catalogs"

To see all product catalogs your business is an agency of, use this GET call:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_ID/client_product_catalogs"

This returns a list of product catalogs that belong to clients of a Business Manager.

Product Catalog Permissions

To update items in a Product Catalog, a user (including a system user or a system admin user) needs permissions. The possible roles on a Product Catalog are ADMIN and ADVERTISER.

To assign the ADMIN role for a catalog to a user:

curl \
-X POST
-F "user=<user_id>" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/userpermissions"

To assign the ADVERTISER role for a catalog to a user under a business:

curl \
-X POST
-F "user=<USER_ID>" \
-F "role=ADVERTISER" \
-F "business=<business_id>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/userpermissions"

To get the ID of a user:

curl \
-X GET \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/me"

To remove permissions for a catalog from a user:

curl \
-X DELETE \
-F "user=<USER_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PRODUCT_CATALOG_ID>/userpermissions"

To see product catalogs that a business user, system user, or a pending user with permissions, make a GET request:

curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/BUSINESS_SCOPED_USER_ID/assigned_product_catalogs"
curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/SYSTEM_USER_ID/assigned_product_catalogs"
curl -G \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/VERSION/PENDING_USER_ID/assigned_product_catalogs"

Permitted Roles

When a user is added to a business, one of the following two roles can be assigned.

API Constant Name Description

ADMIN

Business Admin

Can manage all aspects of the business settings, including modifying or deleting the account and adding or removing people.

EMPLOYEE

Business Employee

Can see all of the information in the business settings but can't make any changes, except to add Pages or ad accounts which this user is an admin of to the business.

The following roles can be assigned to any user of the business, either Admin or Employee, on ad accounts accessible by this business:

API Constant Name Description

ADMIN

Ad Account Admin

Can manage all aspects of campaigns, reporting, billing and account permissions, and can set ad account spending limits. Ad account admins can also associate business payment methods.

GENERAL_USER

Ad Account Advertiser

Can see and edit ads and set up ads using the payment method associated with the ad account.

REPORTS_ONLY

Ad Account Analyst

Can see ad performance.

The following roles can be assigned to any user of the business, either Admin or Employee, on Pages accessible by this business:

API Constant Name Description

MANAGER

Page Admin

Can manage Page roles, send messages and post as the Page, create ads, and view insights.

CONTENT_CREATOR

Page Editor

Can edit the Page, send messages and post as the Page, create ads, and view insights.

MODERATOR

Page Moderator

Can respond to and delete comments on the Page, send messages as the Page, create ads, and view insights. Page moderators can't post as the Page.

ADVERTISER

Page Advertiser

Can create ads for the Page and view insights. Page advertisers can't post as the Page.

INSIGHTS_ANALYST

Page Analyst

Can view insights. Page analysts can't post as the Page.

There is no role management API for apps in Business Manager.

The following roles can be assigned to any user of the business, either Admin or Employee, on Product Catalogs accessible by this business:

API Constant Name Description

ADMIN

Catalog Admin

Can manage all aspects of the product catalog with full read and write access including create/update/delete of items, managing feeds, attaching catalog to pixels and apps, creating product sets, running dynamic ads with the catalog, changing catalog settings, etc.

ADVERTISER

Catalog Advertiser

Can create product sets and run dynamic ads with the catalog. Cannot edit its products, feeds or catalog settings.

There is no role management for Instagram accounts in Business Manager. Users with access to ad accounts that are linked to Instagram accounts can run ads for those Instagram accounts.

Business-to-Business Functions

Request Access to Assets

Business Manager may request access to an ad account or a page owned by another business manager. They must specify the roles that they want need to be able to assign in the request.

To request AGENCY access, you must provide permitted_roles in your request. You can only send request to assets to business manager that you intend to approve and that they must already know your business.

For example, a business that needs access to adaccount_id and needs to be able to assign its employees as GENERAL_USER and REPORTS_ONLY would make this POST call:

curl \
-F "adaccount_id=act_<AD_ACCOUNT_ID>" \
-F "permitted_roles=['GENERAL_USER','REPORTS_ONLY']" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_ad_accounts?access_token=<ACCESS_TOKEN>"

Similarly for a Page, if you want to assign the ADVERTISER and INSIGHTS_ANALYST to a Page they do not own:

curl \
-F "page_id=<PAGE_ID>" \
-F "permitted_roles=['ADVERTISER','INSIGHTS_ANALYST']" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/client_pages?access_token=<ACCESS_TOKEN>" 

These calls send out a notification to the respective admins of the ad account or Page, which asks to accept the access request. The respective admins will see the notification in Ads Manager or Pages Manager. They can also accept the request from the UI. If you want to see the outstanding requests via the API, look for PENDING for access_status field with a GET request.

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"

This is how the response would look like:

"data": [
   {
     "name": "Random Page", 
     "page_permissions": [
       {
         "id": "1900952844321", 
         "permitted_roles": [
           "ADVERTISER", 
           "CONTENT_CREATOR", 
           "MODERATOR", 
           "MANAGER"
         ], 
         "access_status": "CLIENT_RESPONSE_PENDING", 
         "access_requested_time": "2014-01-07T23:26:09+0000", 
         "access_updated_time": "2014-01-07T23:26:09+0000"
       }
     ], 
     "id": "190137931178903"
   }, 

Grant Access to Assets for Another Business Manager

This is also known as adding an Agency to your object.

To accept an access request of an object you own from another business manager, or to give access of one of the objects you own to another business manger, you must specify the business and the list of roles they should have access to.

If the access token used to make the API call belongs to a user or system user who has access to the requested asset via a business, the access to the asset can only be granted if this business is the OWNER of the asset. You cannot grant access to assets of which you are just an AGENCY.

For example, to give a business access to an ad account with GENERAL_USER and REPORTS_ONLY roles, use this POST request:

curl \
-F "business=<BUSINESS_ID>" \
-F "permitted_roles=['GENERAL_USER','REPORTS_ONLY']" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

To give a business access to your page with ADVERTISER and MODERATOR roles:

curl \
-F "business=<BUSINESS_ID>" \
-F "permitted_roles=['ADVERTISER','MODERATOR']" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

Page admins can also accept a agency access requests in the Manage Admin Roles tabs in a page settings on facebook.com.

Remove Access to Assets

This is also known as removing an agency from your business. To remove a business managers's access from your ad account:

curl \
-X DELETE \
-F "business=<BUSINESS_ID>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

Similarly, to remove a Business's access from your Page:

curl \
-X DELETE \
-F "business=<BUSINESS_ID>" \
"https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

View Agency Access

To see all the businesses that have access to your ad account with a GET call:

curl "https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/agencies?access_token=<ACCESS_TOKEN>"

To see all the businesses that have access to your page:

curl "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/agencies?access_token=<ACCESS_TOKEN>"

To see all the businesses that have access to your business assets:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/agencies?access_token=<ACCESS_TOKEN>"

View Client Access

To see all the businesses that have given you access to one or more of their ad accounts or pages, use this GET call:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/clients?access_token=<ACCESS_TOKEN>"