Business Management APIs

Asset Groups And Users

Manage your business' asset groups and learn how to connect your business users to asset groups.

Asset Groups

Get List of Groups

To get a list of asset groups associated with a business, send a GET request to the BusinessBusinessAssetGroups endpoint.

Example Request

Formatted for readability
curl -i -X GET 
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ID/business_asset_groups
    ?access_token=ACCESS-TOKEN"

Example Response

{
  "data": [
    {
      "id": "BUSINESS-ID",
      "name": "Northern Region"
    },
    {
      "id": "BUSINESS-ID",
      "name": "Western Region"
    }
  ],
....
}

Get a Specific Group

To read a specific business asset group, send a GET request to the BusinessAssetGroup endpoint.

Example Request

Formatted for readability
curl -i -X GET 
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID
    ?access_token=ACCESS-TOKEN"

Example Response

{
  "id": "BUSINESS-ASSET-GROUP-ID", "name": "BUSINESS-ASSET-GROUP-NAME"
}

Rename Group

To rename a specific asset group, send a POST request to the BusinessAssetGroup endpoint and set name to the new value.

Example Request

Formatted for readability
curl -i -X POST 
 "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID
   ?name=BUSINESS-ASSET-GROUP-NAME
   &access_token=ACCESS-TOKEN"

Example Response

"success":  "true"

Delete Group

To delete a specific asset group, send a DELETE request to the BusinessAssetGroup endpoint.

Example Request

Formatted for readability
curl -i -X DELETE 
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID
    ?access_token=ACCESS-TOKEN"

Example Response

"success":  "true"

Users

Public User fields for a User who has a role on the business that has claimed the app.

Requirements

  • Business Asset User Profile Access Feature allows Business apps to read a small set of public Fields on a User, as long as the User has engaged with assets owned by a Business that has claimed the app.

Refer to the Business Asset User Profile Access reference for a list of readable User Fields.

Get User Access To Groups

To view a list of all business asset groups that a business-scoped user can access send a GET request to the BusinessScopedUser/AssignedBusinessAssetGroups endpoint.

Example Request

Formatted for readability
curl -i -X GET 
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-SCOPED-USER-ID/assigned_business_asset_groups
    ?limit=1
    &access_token=ACCESS-TOKEN"

Example Response

The response includes roles which define the access levels a user has per asset type:

{
  "data": [
    {
      "id": "BUSINESS-ID" 
      "name": "USER NAME",      
      "page_roles": [ "ANALYZE", "ADVERTISE" ],
      "offline_conversion_data_set_roles": ["UPLOAD"],
      "adaccount_roles": ["ANALYZE", "ADVERTISE"],      
      "pixel_roles": ["ANALYZE", "EDIT"]    
    }  
    ],
        ....
}

Get User Permissions

To read a list of assigned users for an asset group, send a GET request to the BusinessAssetGroupAssignedUsers endpoint.

Example Request

Formatted for readability
curl -i -X GET
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID/assigned_users
    ?limit=2
    &business=BUSINESS-ID
    &access_token=ACCESS-TOKEN"

Example Response

{
  "data": [
    {
      "id": "BUSINESS-ID",
      "name": "Dabney Donigan",
      "page_roles": [ "ANALYZE" ],  
      "offline_conversion_data_set_roles": [ "ADVERTISE", "UPLOAD", "MANAGE" ],
      "adaccount_roles": [ "ANALYZE" ],
      "pixel_roles": [ "ANALYZE", "EDIT" ]
      }
      ],
   ....
}

Assign a User to an Asset Group

To assign users to a business asset group, send a POST request to the BusinessAssetGroupAssignedUsers endpoint.

Example Request

Formatted for readability
curl -i -X POST 
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID/assigned_users
    ?business=BUSINESS-ID
    &user=USER-ID 
    &page_roles=LIST-OF-PAGE-ROLES
    &adaccount_roles=LIST-OF-AD-ACCOUNT-ROLES
    &pixel_roles=LIST-OF-PIXEL-ROLES
    &offline_conversion_data_set_roles=LIST-OF-OFFLINE-CONVERSION-ROLES
    &access_token=ACCESS-TOKEN"

Example Response

"success":  "true"

Remove a User from an Asset Group

To remove a user from a group, send a POST request to the BusinessAssetGroup endpoint.

Example Request

Formatted for readability
curl -i -X DELETE \
  "https://graph.facebook.com/LATEST-API-VERSION/BUSINESS-ASSET-GROUP-ID/assigned_users
    ?business=BUSINESS-ID
    &user=USER-ID
    &access_token=ACCESS-TOKEN"

Example Response

"success":  "true"