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.

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.

Frontline field

Further fields are available within the frontline field.

Supported writeable edges

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

Adding user accounts

Users can be added to Workplace by calling the https://graph.facebook.com/community/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 /community/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 /community/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 edited in 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"
}

Set or modify a user's phone number

POST /{user-id}/phones HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {your access token}
{
"number": "+44-7236-123459",
"type": "work",
"primary": "true"
}

Set or modify a user's frontline status

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

{"frontline": 
  {"is_frontline": true}
}

Set or modify a user's has_access status

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

{"frontline": {
 "is_frontline": true, 
 "has_access": false
  }
}

Set or a user account as deactivated

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

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
      /{user-id}/profile_pictures?
      image_url={...}&
      caption={...}

Photo data included in request

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

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
      /{user-id}/profile_pictures?
      image_url={...}&
      caption={...}

Photo data included in request

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

Remove Profile Information

Profile data can be removed from deactivated users by making a POST call to the https://graph.facebook.com/{user-id}/remove_profile_information endpoint. This has the effect of removing personal information, including name and profile image, from a user account. A full list of fields from which data will be removed is provided. Posts and comments made by this person will remain available on Workplace.

Removing personal information is permanent and can't be undone. A profile where Remove Profile Information has been used cannot be restored, even if the same individual returns back to the organisation.

Affected fields

The following is the full list of field where data will be removed by the /remove_profile_information endpoint:

• External ID
• Username
• Formatted name
• Family name
• Given name
• Middle name
• Honorific prefix
• Honorific suffix
• Display name
• Nicknames
• Profile URL
• Preferred language
• Locale
• Profile languages
• Timezone
• Employee number
• Entitlements
• Hire date
• Termination date
• Roles
• Emails
• IMs
• Phone numbers
• Addresses
• Manager email
• Manager external ID
• Manager
• Skills
• Bio
• Frontline settings
• Total report count
• Custom pronoun text
• Division
• Department
• Job title
• Org
• Cost Center
• IDP import settings
• Creation invite
• Unlaunched login attempt
• X509 certificates
• All cover pictures
• All profile pictures
• Follows
• Birthday
• Name pronunciation

Remove Profile Information

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

Deleting user accounts

User accounts which have never been claimed 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}