Graph API Version

Business

Reading

Represents a business on Facebook. Includes any specified properties and assets belonging to the business.

Example

Graph API Explorer
GET /v4.0/{business-id} 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(
    '/{business-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(
    "/{business-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{business-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{business-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
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

FieldDescription
id
numeric string

The business ID.

block_offline_analytics
bool

Specifies whether offline analytics for business is blocked.

created_by
BusinessUser|SystemUser

Creator of this business.

created_time
datetime

Creation time of this business.

extended_updated_time
datetime

Extended credits update time.

is_hidden
bool

Whether the business is hidden.

is_instagram_enabled_in_fb_analytics
bool

Whether Instagram is enabled as event source in Facebook Analytics.

link
string

URI for business profile page.

name
string

The business's name.

payment_account_id
numeric string

ID for the payment account for this business.

primary_page

The primary Facebook Page for this business.

profile_picture_uri
string

The profile picture URI of the business.

timezone_id
unsigned int32

This business's timezone.

two_factor_type
enum

Two factor type authentication used for this business

updated_by
BusinessUser|SystemUser

Last time this business was updated.

updated_time
datetime

Last time this business was updated.

verification_status
enum

Verification status for this business.

vertical
string

This business belongs to this vertical industry.

vertical_id
unsigned int32

ID for vertical industry.

Edges

EdgeDescription

The studies this business has access to, such as any advertising lift studies or split testing studies.

Audience Network query for this publisher entity.

Obtain the results of an asynchronous Audience Network query for this publisher entity.

The business has access to these pixels.

Agencies associated with this business.

Placements used by this Audience Network business.

Business asset groups owned by this business. The business can grant permissions to assets in this group.

Business users associated with this business. Includes employees and admins at the business.

This business has access to these client ad accounts.

This business has access to these client apps.

This business has access to these client pages.

This business has access to these client pixels.

This business has access to these client product catalogs.

Clients of this business.

The business has access to these custom conversions.

The business owns these event source groups. Includes various signals sources such as pixels.

The audience sharing requests initiated by this business.

initiated_sharing_agreements

This business has access to these Instagram accounts.

The measurement reports that the business owns.

The business has access to these offline conversion datasets.

This business owns these ad accounts.

This business owns these apps.

This business aggregates and manages these client businesses.

This business owns these Instagram accounts.

This business owns these pages.

This business owns these pixels.

This business owns these product catalogs.

This business requested access to these client ad accounts and is pending approval.

This business requested access to these client apps and is pending approval.

This business requested access to these client pages and is pending approval.

This business requested access to these client offline conversion data sets and is pending approval.

This business requested ownership of these ad accounts and is pending approval.

This business requested ownership of these pages and is pending approval.

This business received sharing requests for these pixels and is pending for approval.

Admin for this business invited this user to the business. Pending user approval.

The shared audiences permissions from other business to this business.

The audience sharing requests received by this business.

Requests received by this business from another business that want to mark this business as on behalf of the business of a business owned object.

received_sharing_agreements

Reseller verification requests for a China reseller business.

Requests sent by this business to other business that want to mark that business as on behalf of business of the business owned object.

This business owns audiences with these shared-audience permissions.

The business's system users.

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter
278Reading advertisements requires an access token with the extended permission ads_read
80004There 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.
294Managing advertisements requires an access token with the extended permission for ads_management
1150An unknown error occurred.

Creating

You can make a POST request to agencies edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
business
numeric string or integer

SELF_EXPLANATORY

Required
other_relationship
string

SELF_EXPLANATORY

permitted_roles
list<enum {ADMIN, UPLOADER, ADVERTISER}>

Permitted roles the agency can assign to users

relationship_type
array<enum {AD_MANAGER, AUDIENCE_MANAGER, AGENCY, AGGREGATOR, OTHER}>

Relationship type for sharing

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
share_status: enum,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to access_token edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
app_id
app ID

app_id

Required
scope
List<Permission>

scope

Required

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
access_token: string,
}

Validation Rules

ErrorDescription
100Invalid parameter
3960Error creating the token, make sure that system user has tos-ed the app.
3962Provided permission is not valid. Check you spelling and syntax.
You can make a POST request to owned_businesses edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
name
string

name

Required
page_permitted_tasks
array<enum {MANAGE, CREATE_CONTENT, MODERATE, ADVERTISE, ANALYZE, MODERATE_COMMUNITY, MANAGE_JOBS, PAGES_MESSAGING, PAGES_MESSAGING_SUBSCRIPTIONS, READ_PAGE_MAILBOXES, VIEW_MONETIZATION_INSIGHTS, MANAGE_LEADS, PLATFORM_MANAGE_PAGES, PLATFORM_READ_INSIGHTS, PLATFORM_PAGES_MANAGE_INSTANT_ARTICLES}>

page_permitted_tasks

sales_rep_email
string

sales_rep_email

shared_page_id
page ID

shared_page_id

survey_business_type
enum {AGENCY, ADVERTISER, APP_DEVELOPER, PUBLISHER}

survey_business_type

survey_num_assets
int64

survey_num_assets

survey_num_people
int64

survey_num_people

timezone_id
int64

timezone_id

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

vertical

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

ErrorDescription
3947You are trying to create a Business Manager with the same name as one you are already a part of. Please pick a different name.
3913It doesn't look like you have permission to create a new Business Manager.
100Invalid parameter
200Permissions error
3974The name you chose for this Business Manager is not valid. Try a different name.
You can make a POST request to sent_inprogress_onbehalf_requests edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
business_owned_object
string

The object the business is allegedly managing on behalf of receiving_business

Required
receiving_business
numeric string or integer

The business targeted by the request

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

ErrorDescription
100Invalid parameter
You can make a POST request to china_business_onboarding_attributions edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
id: numeric string,
link_with_id: string,
}

Validation Rules

ErrorDescription
200Permissions error
You can make a POST request to business_users edge from the following paths:
When posting to this edge, a Business will be created.

Parameters

ParameterDescription
email
string

Email of user to be added to this business.

Required
role
enum {FINANCE_EDITOR, FINANCE_ANALYST, ADS_RIGHTS_REVIEWER, ADMIN, EMPLOYEE}

Role of user to add to this business.

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

ErrorDescription
100Invalid parameter

Updating

You can update a Business by making a POST request to /{business_id}.

Parameters

ParameterDescription
name
string

Business's name

primary_page
numeric string or integer

Primary page of this business

timezone_id
int64

Timezone id of this business

two_factor_type
enum{none, admin_required, all_required}

Two-factor type of the business

vertical
enum {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, NON_PROFIT, RESTAURANT, HEALTH, LUXURY, OTHER}

Vertical type of the business

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

ErrorDescription
3974The name you chose for this Business Manager is not valid. Try a different name.
3918The Facebook Page you've tried to add is already owned by another Business Manager. You can still request access to this Page, but your request will need to be approved by the Business Manager that owns it.
3947You are trying to create a Business Manager with the same name as one you are already a part of. Please pick a different name.
3973The name you chose for this Business Manager is not valid. Please choose another.
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
3910You need permission to edit the details of your Business Manager. Please talk to one of your Business Manager admins about changing your role or editing the Business Manager details.
3911You need permission to set up a new Business Manager.
100Invalid parameter
200Permissions error

Deleting

You can dissociate a Business from a Business by making a DELETE request to /{business_id}/agencies.

Parameters

ParameterDescription
business
numeric string or integer

The agency's business.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/clients.

Parameters

ParameterDescription
business
numeric string or integer

The client's business.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/pages.

Parameters

ParameterDescription
page_id
Page ID

Page ID.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
42001This Page can't be removed because it's already linked to an Instagram business profile. To remove this Page from Business Manager, go to Instagram and convert to a personal account or change the Page linked to your business profile.
3948Please assign someone as a manager to this Page before removing it from your Business Manager.
3996The page does not belong to this Business Manager.
100Invalid parameter
200Permissions error
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/instagram_accounts.

Parameters

ParameterDescription
instagram_account
numeric string or integer

Instagram account ID.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/ad_accounts.

Parameters

ParameterDescription
adaccount_id
string

Ad account ID.

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
You can dissociate a Business from a Business by making a DELETE request to /{business_id}/owned_businesses.

Parameters

ParameterDescription
client_id
business ID

client_id

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
3912There was a technical issue and the changes you made to your Business Manager weren't saved. Please try again.
100Invalid parameter
200Permissions error
You can dissociate a Business from an AdAccount by making a DELETE request to /act_{ad_account_id}/agencies.

Parameters

ParameterDescription
business
business ID

SELF_EXPLANATORY

Required

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error