Business Manager

Help businesses and agencies manage Facebook Pages, ad accounts and apps in one place. Business Manager API's can help manage multiple ad account assets and permissions. You can also automate creating ad accounts. See Ads Help Center, Business Manager Basics.

In Business Manager you connect ads-related assets and other business assets for:

  • Project and permission management
  • Run campaigns on behalf of another company.
  • Create ad accounts and assign credit to buy ads.

For example, create a new Business Manager with a POST:

curl \
-F "name=Pomni Media" \
-F "vertical=ADVERTISING" \
-F "primary_page=<PAGE_ID>" \
-F "timezone_id=1" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

Prerequisites

A business needs at least one page, an admin, a business name and a valid email address.

The business name is used only for your business and any of other businesses you choose to share objects with. After you create this business, you can add pages, ad-accounts, apps, offsite conversion tracking objects, and other ads-related assets that belong to a business.

To use Business Manager API, your app needs appropriate Marketing API Access Level. Your app also needs business_management extended permission, available as of 2.7. You cannot use ads_management or manage_pages to call Business Management API 2.7. If you have an existing app on 2.6 or earlier, with approval to use ads_management or manage_pages permissions, Facebook will migrate your app to this new permission and you do not need to redo permissions review. If you move your app to 2.7 your app should ask for the additional permission ‘business_management’ any time your app generates a new access token for new or old users. Apps using this permission for the first time need to go through review, see Permissions.

Work with Business Managers

Create a new business manager to represent your business. Only create a new business manager if you are setting up a new business manager for yourself or your clients. If you need another ad account or access to another page, you should use your existing manager and asset permissions. Deleting a business manager is not allowed.

To create a Business you need:

  • An access token
  • A Page ID
  • A vertical
  • An app-scoped user ID

The Page ID you provide should be the Primary Page of your Business. This page publically represents your business on Facebook. Whoever creates the Business is a manager of this page. If you don't have a Page to represent your business on Facebook create one.

The vertical is one of these String constants:

ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

To view properties for a business, use its ID:

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

You can also see a list of the business managers you can access:

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

Response fields include:

Name Description Type

name

Name of business

string

timezone_id

ID of the business's timezone

int

primary_page

The object of the primary page associated with this business manager.

{ "category": "App page", "name": "Sample Primary Page", "id": "123456789" }

JSON object

id

ID of the business manager

long

update_time

Last time this business manager was updated

string

updated_by

Last user, by name and id, who have updated this manager

JSON object

creation_time

Time this business created

string

created_by

User name and id who created this manager

JSON object

Updating Business Managers

Update fields in the business manager using make a POST request to https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID}. For example, change the business name:

curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

Change the business vertical by making the following POST request:

curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

You have these options:

Name Description

name

Required; The Name of the Business

primary_page

The ID of the primary page associated with this business manager

You can update the primary page by making the following POST request. The primary page has to be owned by business manager.

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

You can also update all of the above in one POST request:

curl \
-F "name=My Actual Business Name" \
-F "vertical=RETAIL" \
-F "primary_page=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

People on Business Manager

There are two types of roles on a business manager:

Name API Constant Description

Admin

ADMIN

  • Can control all aspects of the business including modifying or deleting the account and adding or removing people from the employee list.
  • Has READ and WRITE access to all assets that the Business Manager is connected with.

Employee

EMPLOYEE

  • Can see all of information in business settings and be assigned roles by business admins. Cannot make any changes, except to add Pages or ad accounts which this user is an admin of to the business.
  • Has READ access to all assets that the Buisness Manager is connected with.

Initially the creator of the Business is the only user on the Business and is an Admin.

Invite People

To add your coworkers to your business you must invite them. To invite someone, provide a valid email address that they have access to. Sending requests to add employees to a business manager is limited. When you reach this limit you will get error code 17, you should resume 24 hours later.

To invite someone as an Admin, send a POST request:

curl \
-F "email=some@email.com" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

To invite someone as an Employee, send a POST request:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

Facebook sends an email invitation to the work email address you specified. The invitee must check the email and follow the signup process. Once they are done, you can see them in your list of Users.

People on Business Manager

To get the list of all people within the business manager, make the following GET request:

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

This include INVITED and ACTIVE users on your Business. ACTIVE users have a user field and a business_persona field. Here is the example:

{
  "data": [
    {
      "business_persona": {
        "name": "Jason White", 
        "id": "12345678"
      }, 
      "role": "ADMIN", 
      "status": "ACTIVE", 
      "email": "jw@email.com", 
      "user": {
        "name": "Jason White", 
        "id": "10015004084976543"
      }
    }, 
    {
      "role": "EMPLOYEE", 
      "status": "INVITED", 
      "email": "jesscias3@fb.com", 
    }, 
  ]
}
Name Description Type

user

Facebook user information, including id and name. This field is null for non-ACTIVE people. Do not use the name in this field in your user interfaces. Use business_persona instead.

JSON object

business_persona

The persona associated with this business. To display user names, you must use the name from the business_persona when available and not use name from user. This makes a clear separation of business contexts from personal contexts. Customers may use a different name in their business context.

JSON object

role

The role this person has for this business. EMPLOYEE or ADMIN.

string

status

Whether someone accepted the invitation for a role in this business. INVITED, ACTIVE, or SUSPENDED.

string

email

Email address to invite someone to a role in this business.

string

created_by

ADMIN who created this user.

string

updated_by

ADMIN who last updated this user.

string

created_time

When this user created.

DateTime string

updated_time

When user was updated

DateTime string

page_permissions

Array of Page permissions. One element for each Page this user can access or is invited to have access. In each element, there is an id for Page, a role for the Page, and a STATUS which is ACTIVE or INVITED.

JSON object

adaccount_permissions

An array of ad account permissions. One element for each ad account this user can access or is invited to have access. Each elemnt includes: an id for ad account, a role for the ad account, and a STATUS of ACTIVE or INVITED.

JSON object

Changing Roles

To change a user's role on your Business provide the User ID for the user. For example you can upgrade an Employee to the Admin role, with this POST request:

curl \
-F "user=<USER_ID>" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

or downgrade an Admin to the Employee role using this POST request:

curl \
-F "user=<USER_ID>" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

You can change the role offered to someone via email address with this POST request:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

Removing users

Remove permissions granted to someone based on membership in your business managers. Limit access to ad accounts and pages. If the user has access to ad accounts or pages outside of your Business Manager those permissions are not affected. For example, someone may have added themselves or they have access through another business manager

To remove a user from your business make a DELETE call:

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

To cancel an email invitation with a DELETE request:

curl \
-X DELETE \
-F "email=some@email.com" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/userpermissions"

This remove the user from your Business as well as remove them from all your Business's assets.

Getting Connection Objects

Connection Objects are the Facebook objects (for example, pages, apps, and so on) that an administrator manages. An administrator can be a user or business, or in the case of apps, a developer or advertiser. The types of connection objects are:

See a sample queries and learn more at Connection Objects, Reference.

Business Persona

Each Business Manager creates a separate working context which is distinct from someone's personal identities, and distinct from someone's other business manager contexts. Each person has name, email and title specific to that particular Business Manager. Although we authenticate access with someone's individual Facebook identity within each business context, Facebook does not use or display Facebook usernames, friend lists, and so on.

Fields

Name Description Type

id

Business persona ID, default field

long

name

Business persona pame, default field

string

business

Business manager id

long

first_name

Business first Name

string

last_name

Business last Name

string

title

Business title

string

email

Business email

string

update_time

The last time this persona was updated

string

updated_by

The last user (name and id) who have updated this persona

JSON object

created_time

The time this persona was created

string

created_by

The user (name and id) who has created this persona

JSON object

When someone accepts an invitation to your Business Manager, they create a persona. They can choose how their identity displays with in a particular Business Manager. The persona consists of a name , first_name , last_name , email and an id.

To get all personas associated with a specific Business Manager, make a GET:

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

To get a persona connected with your user account by your user access token, on a specific business manager, make this GET call:

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

You may modify first_name, last_name , email with this POST request:

curl \
-F "first_name=Teddy" \
-F "last_name=Bear" \
-F "email=user@email.com" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_PERSONA_ID>"

If you update email you will not see this property immediately updated for the persona even if the result is success. Facebook first sends an email with a verification link to the new email address. After the owner of this account verifies the new email, Facebook updates the persona's email address.

Projects

Organize your business assets such as ad accounts, Pages, apps, into logical groups. Projects help you navigate your business hierarchy more easily. You can use them across agency and client owned assets. You can only have one label per asset.

To create a business project you must specify the name in a POST request.

curl \
-F "name=Test label" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/businessprojects"

You can view all the labels under the business account with a GET request:

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

Fields

Name Description Type

id

Business Project ID, default field

long

name

Business project Name, default field

string

business

Business id

long

update_time

The last time this Business project was updated

string

updated_by

The last user (name and id) who have updated this Business project

JSON object

created_time

The time this Business Label was created

string

created_by

The user (name and id) who has created this Business project

JSON object

adaccounts

The adaccounts under this project for this given business

JSON object

pages

The Pages under this project for this given business

JSON object

apps

The apps under this project for this given business

JSON object

Viewing a projects on the business

You can view the details of a project by making this GET call:

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

Removing a project on the business

You can delete a project by making this DELETE call:

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

Page for Project

You can add a Page to a project by making following POST call:

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

You can view all the Pages under a project by making following GET call:

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

You can remove a Page from a project by making following DELETE call:

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

Ad Account for Project

You can add an ad account to a project by making following POST call:

curl \
-F "adaccount_id=act_<ADACCOUNT_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/adaccounts"

You can view all the ad accounts under a project by making following GET call:

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

You can remove an ad account from a project by making following DELETE call:

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

App for Project

You can add an app to a project by making following POST call:

curl \
-F "app_id=<PAGE_ID>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PROJECT_ID>/apps"

You can view all the apps under a project by making following GET call:

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

You can remove an app from a project by making following DELETE call:

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

Invoicing

Business Manager API enables you to view and manage credit sources associated with a business.

Business Manager Owned Normal Credit Line

For the Marketing API partners who have invoicing enabled, you can take advantage of Business Manager Owned Normal Credit Line.

Facebook Marketing Partners (FBMP) need to contact their sales rep to get your business manager setup for credit. Please make sure ask for Business Manager Owned Normal Credit Line. Once this is setup, you can start using the ad account creation API to start creating ad accounts. Charges will be against your business manager credit line.

For the ad accounts created via the following API, we will dynamically distribute credit across accounts and update credit limits and spend to avoid hitting the credit limits. You will also be able to see summarized credit available and the amount of credit on each ad account.

Today, we only support normal liability, sequential liability is not supported. The process for setting this up will remain unchanged.

Month-End Invoicing

Once your credit line is set up for a business and business uses this run ads, we generated month-end invoices for the business account. To see the business invoices, you need a finance role. For normal administrators and employee of a business, you can assign permissions under People in Business Manager. For system users, you need to assign permissions with an API call:

www.graph.facebook.com/VERSION/<BUSINESS_ID>/finance_permissions?user=<USER_ID>&finance_permission=<FINANCE_ROLE>

Where FINANCE_ROLE can be FINANCE_ANALYST or FINANCE_EDITOR.

To retrieve invoices under this business account, send a GET request:

GET https://graph.facebook.com/<BUSINESS_ID>
?fields=business_invoices
.start_date(2017/1/1)
.end_date(2017/4/1)

Sample results look like this:

{
  "business_invoices": {
    "data": [
      {
        "id": "1659175694099710",
        "billing_period": "2017-03-01"
      },
      {
        "id": "1303851778395619",
        "billing_period": "2017-01-01"
      },
      {
        "id": "1415846861611329",
        "billing_period": "2017-02-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "249554531892085"
}

You can get a detailed breakdown of the invoice at a campaign level with this request:

GET https://graph.facebook.com/<BUSINESS_ID>
?fields=business_invoices
.start_date(2017/1/1)
.end_date(2017/4/1) {
    billed_amount_details,
    billing_period,entity,
    id,
    invoice_id,
    liability_type,
    invoice_type,
    payment_term,
    type,
    campaigns}
  &amp;&amp;access_token=<TOKEN>

The response:

{
  "business_invoices": {
    "data": [
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "387.70",
          "tax_amount": "0.00",
          "total_amount": "387.70"
        },
        "billing_period": "2017-03-01",
        "entity": "FBUS",
        "id": "1659175694099710",
        "invoice_id": "22736800",
        "liability_type": "Normal",
        "invoice_type": "Invoice",
        "payment_term": "CUSTOMER",
        "type": "Invoice",
        "campaigns": {
          "data": [
            {
              "campaign_id": "6056967798500",
              "campaign_name": "Nhận ưu đãi",
              "tags": [
                "hello2"
              ],
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "207.62",
                "tax_amount": "0.00",
                "total_amount": "207.62"
              }
            },
            {
              "campaign_id": "6056958052500",
              "campaign_name": "Nhận ưu đãi",
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "180.08",
                "tax_amount": "0.00",
                "total_amount": "180.08"
              }
              "impressions": 100,
              "clicks": 50,
              "conversions": 30
            }
          ]
        }
      },
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "382.99",
          "tax_amount": "0.00",
          "total_amount": "382.99"
        },
        ......
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "1515766328651000"
}

Funding Source API

To retrieve the credit card associated with a business manager, send this GET request.

https://graph.facebook.com/business_id/creditcards

To retrieve the extended credit funding source associated with a business manager, send this GET request.

https://graph.facebook.com/business_id/extendedcredits

To setup a funding source for a business, go to settings section of your business on Business Manager.

Dynamic Credit Allocation

Dynamic Credit Allocation, also known as DCAF, is our credit allocation system for periodically adjusting available credit on per ad account basis. Our automated script runs approximately every 30 minutes and takes your available credit and evenly distributes it across all your active accounts enabled for DCAF. Available credit includes total approved credit minus total outstanding balance. This helps manage spend at your ad account level and allocate funding for each ad account.

A business can also “inactivate” an invoiced ad account and removing the ad account from the list that needs credit assigned. Businesses no longer need to have Facebook manage this status.

Resources

General, Marketing API related:

Business Manager:

  • Asset Management - Manage assets, such as ad accounts, Pages, Instagram accounts, product catalogs, and so on.
  • System User APIs - Automated services make API calls to assets owned or managed by a Business Manager. This document covers system user APIs, only available to apps with Standard access level.
  • Client Messaging - Guidelines for messaging clients about Business Manager and gray account deprecation
  • FAQ
  • Business Manager Best Practices