Graph API Reference

Overview

The Graph API for Workplace is a programmatic way to get data in and out of Workplace. It's a low-level HTTP-based API that you can use to query data about objects in a Workplace graph.

The Graph API is named after the idea of a graph data model, where objects are represented by nodes and joined along edges. At an API level, this is how apps access the information on Workplace. The Graph API for Workplace allows for a subset of functionality of the Graph API for Facebook. This functionality is limited to interactions with a Workplace community and may differ in some cases for better performance or usability.

Workplace Graph API Objects

The following nodes are accessible through the Workplace Graph API using a custom integration or third party app access token.

Community

A Workplace community. The root group for your Workplace Graph API calls.

Groups

A Workplace group.

Posts

A post made in a group or on a member's profile.

Members

An account for a specific Workplace user. This node is also used to view and edit messages received and sent by this user.

Skills

A skill added to a member's profile.

Event

A Workplace Community or Group Event.

Category

A category in Knowledge Library to store important company content.

People Set

A collection of people defined using criteria or lists.

Reported Content

Content on Workplace that has been reported for review by an admin.

Shift

Shift schedule data for hourly workers on Workplace.

Survey

Surveys that have been created on Workplace.

Data Export

Data export jobs for bulk data export from Workplace.

To see examples of combining Graph API calls to solve specific issues, take a look at the list of Sample Apps.

Using the Graph API

Graph API Objects

The Graph API is a representation of the information on Workplace, composed of:

• Nodes - objects such as a User, a Photo, a Post, a Comment
• Edges - the connections between those "things", such as a Post's file, or a Photo's Comments
• Fields - metadata about objects, such as a person's name, or the privacy of a Group

Every item in the Workplace graph is represented by a unique id. Groups, Members, Posts and even Comments have their own ids, and these can be used to retrieve information about them from the Graph API.

Managing Your Community

Each Workplace community is kept separate from other communities, so you can only use the Graph API to access content inside your own community, and in multi-company groups where members of your community have been added.

For the purposes of Graph API access, your Community is treated as a Group. You can think of your community as a root group, under which all of your groups are added as children. To retrieve information about your community on the Graph API, you'll need your Community ID, which is retrieved programmatically from the Graph API, by making a HTTP GET request to graph.facebook.com/community with a valid app access token.

Graph API Versioning

The Graph API for Workplace is built on top of the Graph API for Facebook's platform. This means it inherits the same API versioning behavior used on Facebook.

Graph API versions are released approximately every three months, and changes across all Workplace and Facebook APIs are published in the Graph API Changelog.

When making an API call to the Graph API, you can specify a version in the API path, as follows:

      https://graph.facebook.com/v2.11/community/groups
    

However, there are some restrictions on available versions:

• When a new version is released, it becomes the current API version, and is guaranteed to work for two years after its release.
• When an app is created, it defaults to the current API version at the time of creation, and this becomes the minimum API version available to that app.
• Apps are free to specify any API version when making API calls, but will not be able to make calls to deprecated API version, or to versions below the app's minimum API version.
• Unversioned API calls will default to the minimum API version for that app.

When a new custom integration is created, its minimum available API version will be the current API version at the time of creation. This minimum version affects both Graph API calls and Webhook subscriptions.

Checking Graph API Version

If you're unsure of which version you're using, there are some ways to check. To check which version of the Graph API can be used with your app, you can add the debug parameter to your API call.

      https://graph.facebook.com/community?debug=all
    

This will return extra debug information confirming the version being used.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

If you try to use a version that is below the minimum API version for your app, the debug message will tell you.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }
    

Checking Webhook Versions

Webhook subscriptions use the minimum API version if the subscription was made via the Custom Integration popup dialog, or the specified API version is the subscription was made via the subscriptions Graph API endpoint, /app/subscriptions.

You can use the subscriptions endpoint to confirm the applied webhook version for each webhook field and topic. This endpoint requires an app access token.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...
    

Using Access Tokens

Get an App Access Token

To make any Graph API calls for your community, you'll need to create an app and retrieve an access token. This involves creating a new custom integration, then granting it the necessary permissions for the functionality you want to build.

To learn more about creating apps and the permission model, see the Permissions guide.

Get a Member Access Token

While an app access token allows an app to access and interact with community-wide objects, a member access token allows a service to make calls on behalf of a specific account.

You can fetch a member access token by making a GET request to the /member_id endpoint for a given member, using an admin access token and requesting the additional field impersonate_token.

This functionality requires the Impersonate permission for the app making the call.