Как стать счастливее и уверенно идти к своим целям? Все ответы — в книге «Сам себе государство. Как совершить революцию в жизни». Подпишитесь на рассылку, чтобы не пропустить предзаказ Get Started - Marketing API - Documentation - Facebook for Developers

Get Started

To use Business Manager, a business needs at least one page, an admin, a business name, and a valid email address. Facebook requires 2-factor authentication using the BUSINESS_ID/two_factor_type field on the business object to verify people from that business who want to access the API.

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.

Requirements

  • Your app needs appropriate Marketing API Access Level to use the Business Manager API.
  • Your app also needs the business_management permission.

Create a New Business Manager

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.

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"

Requirements

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 publicly 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

name

type: string

Name of business

timezone_id

type: int

ID of the business's timezone

primary_page

type: JSON object

Object of the primary page associated with this Business Manager.

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

id

type: long

ID of the Business Manager

update_time

type: string

Last time this Business Manager was updated

updated_by

type: JSON object

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

creation_time

type: string

Time this business created

created_by

type: JSON object

Username and id who created this manager

Update 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>/"

Manage People and Roles

There are two types of roles in 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.

For more information about roles, see Set up catalog roles in Business Manager.

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>/business_users"

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>/business_users"

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

As of v2.11 we have separate endpoints to get users based on their status. Make a GET request to retrieve each group of users. To get all business users:

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

To get system users, with system-level access:

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

To get pending users who are invited to access a business, but who have not yet accepted:

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

The endpoints return either active, pending or system users for your Business. For example:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "name": "Alpha MK",
      "email": "some@email.com",
      "role": "EMPLOYEE",
    }
  ]
}

The results for pending users looks like this:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "email": "some@email.com",
      "role": "EMPLOYEE",
      "status": "PENDING",
      "owner": {
        "id": "USER_ID",
        "name": "Generic Emporium"
      }
    }
  ]
}

Definitions for returned fields are as follows:

Name Description

id

type: long

ID of this user scoped to this Business.

name

type: string

Name of this user under this Business

business

type: JSON object

Business Manager that this user belongs to

first_name

type: string

First name of this user under this business

last_name

type: string

Last name of user under this business

title

type: string

Title of user under this business

role

type: string

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

email

type: string

Email address of user

Change Roles

To change an active 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 "role=ADMIN" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

To change someone from an Admin to the Employee role make a POST request:

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

You can change the role for a pending user with this POST request:

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

Remove Users

Remove permissions granted to someone based on membership under 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 do not change. For example, someone may have added themselves or they have access through another business manager

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

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

To cancel a pending user with a DELETE request:

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

This remove the users from your Business and removes access to your Business's assets.

Get Connection Objects

Reference Docs

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:

  • Pages and Places
  • Events
  • Apps
  • Domains

See a sample queries and learn more at Connection Objects.

Invoices

Business Manager API enables you to view and manage credit sources associated with a business. The API retries all invoices that are visible to a Business Manager. This means all invoices that this Business Manager is liable for are visible via the API, not just the invoices belonging to an individual business ID.

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:

curl "https://www.graph.facebook.com/<API_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:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?start_date=2017-01-01&end_date=2017-04-01"

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 invoice details at a campaign level with this request:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?fields=billed_amount_details,billing_period,entity,id,invoice_id,payment_term,type,campaigns&start_date=2019-06-01&end_date=2019-07-01"

The response is similar to this:

{
  "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"
}

You can also retrieve the additional invoicing fields:

  • invoice_date - Date when Facebook generated the invoice
  • due_date - Date the invoice is due
  • payment_status - Shows whether the invoice is Paid, Unpaid, or Partially Paid
  • amount_due - How much money is currently due, and outstanding, on the invoice
  • download_uri - Download a PDF of the invoice at this URI

Funding Source API

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

curl "https://www.graph.facebook.com/<API_VERSION>/<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.