Account Management API (Graph)

Overview

As people join and leave your organization, you need to grant and revoke access to Workplace. This set of guides introduces the concepts of account provisioning and deactivation through the use of the Graph API, which can be used to read, create, modify and delete users.

If you're planning on integrating with a cloud provider for the purpose of provisioning and deactivating users, please see our Automatic Account Management guide.

Reading user accounts

See Member page.

Supported writeable fields

This table shows the fields that can be set and updated using the Graph API. See Member page for information on all fields and edges, including read-only fields.

FieldDescriptionTypeRequired

email

Unique identifier for the user, used by the user to directly authenticate with the service provider. Must be unique.

String

Optional. Accounts without email addresses must have an external_id set.

name

The components of the Users real name.

String

Required

title

Job title of the user, e.g., Vice President.

String

Optional

organization

Identifies the name of an organization.

String

Optional

division

Identifies the name of a division.

String

Optional

department

Identifies the name of a department.

String

Optional

manager

Set manager of user. Use /managers edge or managers field to read manager.

ID

Optional

external_id

An identifier for the User as defined by the customer. Each User MAY include a non-empty externalId value. The value of the externalId attribute is always issued be the customer and will never be specified by Workplace.

ID

Required if the user account does not have an email address set. Otherwise optional

cost_center

Identifies the name of a cost center.

String

Optional

invited (write-only)

Control whether a user is invited. This field is ignored for accounts without an email address, which will always be invited on creation.

Boolean

Optional

work_locale

User's locale. This is the locale that Workplace will use for this user until there is another way to determine the user's locale (such as a browser or device language setting)

String. Valid values are concatenation of the ISO 639-1 two-letter language code plus an underscore plus the ISO 3166-1 two letter country code.For example, en_US specifies the English language and country US.

Optional

auth_method

User's authentication method to Workplace

String. Either sso or password

Optional

Adding user accounts

Users can be added to Workplace by calling the https://graph.facebook.com/company/accounts endpoint using the POST verb and including the required profile fields. Field data can be provided as URL parameters or as JSON within the data payload.

The Provision user accounts permission is required to add user accounts.

On successful creation. the newly-created user ID will be returned.

Create user account using URL parameters

POST /company/accounts
  ?name=John McClane
  &email=john@mclane.com
  &title=Salesman
  &department=US Sales
  &organization=Global Sales
  &manager=1126377362881
  &division=Cars
  &cost_center=CC1
  &invited=true
  &work_locale=en_US
  &auth_method=password
HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

Create a new user account using JSON payload

POST /company/accounts HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

{
  "name"         : "John McLane",
  "email"        : "john@mclane.com",
  "title"        : "Salesman",
  "department"   : "US Sales",
  "organization" : "Global Sales",
  "manager"      : 100013693981877,
  "division"     : "Cars",
  "cost_center"  : "CC1",
  "external_id"  : "1232112",
  "invited"      : true,
  "work_locale"  : "en_US",
  "auth_method"  : "password"
}

Modifying user accounts

Users can be added to Workplace by calling the https://graph.facebook.com/{user-id} endpoint using the POST verb and providing updated profile field data. Field data can be provided as URL parameters (preferred) or as JSON within the data payload (some operations not fully supported). Omitted fields will not be changed.

The Manage work profiles permission is required to modify user profile data.

Modify user account using URL parameters

POST /{user-id}
  ?name=John McClane
  &email=john@mclane.com
  &title=Salesman
  &department=US Sales
  &organization=Global Sales
  &manager=1126377362881
  &division=Cars
  &cost_center=CC1
  &invited=true
  &work_locale=en_US
  &auth_method=password

HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

Modify user account using JSON payload

POST /{user-id} HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

{
  "name"         : "John McLane",
  "email"        : "john@mclane.com",
  "title"        : "Salesman",
  "department"   : "US Sales",
  "organization" : "Global Sales",
  "manager"      : 100013693981877,
  "division"     : "Cars",
  "cost_center"  : "CC1",
  "external_id"  : "1232112",
  "invited"      : true
  "work_locale"  : "en_US"
  "auth_method"  : "password"
}

Unsetting previously set profile fields

To uset a previously set field, set the profile field to an empty setting. Note that the name field can never be unset nor empty and the email field cannot be cleared.

Unsetting title field using URL parameter

POST /{user-id}&title=&
HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

Unsetting title field using JSON payload

POST /{user-id} HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}

{
  "title"        : ""
}

Setting user profile photo

Profile photos can be updated by making a POST call to the https://graph.facebook.com/{user-id}/profile_pictures endpoint. Image data can be provided in jpg or png format and can be supplied as a publicly accessible URL or as a file upload. A caption can optionally be set for the photo.

Publicly accessible URL

POST graph.facebook.com
      /{member-id}/profile_pictures?
      image_url={...}&
      caption={...}

Photo data included in request

POST graph.facebook.com
      /{member-id}/profile_pictures?
      caption={...}
Content-Type: multipart/form-data;
Content-Disposition: form-data; name="image_data"; filename="/profile_picture.png

Deleting user accounts

Unclaimed user accounts can be deleted by calling the https://graph.facebook.com/{user-id} endpoint using the DELETE verb.

The Provision user accounts permission is required to delete user accounts.

Delete user account

DELETE /{user-id} HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}