Account Management API

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 SCIM API. This set of API calls will allow you to build a custom connector to provision and deactivate your people who are stored on your user directory.

Using the Account Management API

The Account Management API for Workplace is a SCIM-compliant REST API. This specification was designed to easily manage user identities in cloud-based apps and services.

The base URL for the Account Management API: https://www.facebook.com/scim/v1/

API Access Token

Only a Workplace user with the System Administrator privilege can change this configuration.

The Workplace Account Management API will only process requests that include a valid access token, which you must send with your API invocations as an authorization header.

To receive an access token, you need to create an app on the Integrations page of the Admin Panel. More information can be found in the Apps and Permissions documentation.

Example

GET /scim/v1/Users/ HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

Note: A User-Agent string is mandatory in all SCIM API requests.

API Reference

The Account Management API data structure is comprised of the core SCIM schema and several schema extensions:

Core Schema

The following properties belong to the core SCIM schema urn:scim:schemas:core:1.0

FieldDescriptionTypeRequired

userName

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

String

Required

name

The components of the Users real name.

Name

Required

displayName

The name of the User, suitable for display to end-users. Each User returned MAY include a non-empty displayName value. The name SHOULD be the full name of the User being described if known (e.g. Babs Jensen or Ms. Barbara J Jensen, III), but MAY be a username or handle, if that is all that is available (e.g. bjensen).

String

Optional

title

Title of the user, e.g., Vice President.

String

Optional

nickName

The casual way to address the user in real life, e.g., Bob or Bobby instead of Robert. This attribute SHOULD NOT be used to represent a username.

String

Optional

profileUrl

A fully qualified URL to a page representing the user online profile.

URL

Optional

preferredLanguage

Indicates the preferred written or spoken language for this user. Generally used for selecting a localised User Interface. 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.

String

Optional

locale

Used to indicate a default location for the user for the purposes of localizing items such as currency, date time format, numerical representations, etc. 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.

String

Optional

timezone

The timezone of the user in the Olson timezone database format, e.g., America/Los_Angeles.

String

Optional

active

A Boolean value indicating whether a user is active. Set to true if the user is able to access Workplace and should receive email and mobile push notifications. Set to false to cause the user to be logged out and to prevent the user from receiving further emails or mobile push notifications.

boolean

Required

userType

Used to identify the organization to user relationship. Typical values used might be Contractor, Employee, Intern, Temp, External, and Unknown, but any value may be used.

String

Optional

photos

Array of one or more photo values that each contain a fully-qualified URL that points to an image file that is a photo of the user.

URL

Optional

emails

Array of one or more Email objects for the user.

Email

Optional

phoneNumbers

Array of one or more phoneNumber values for the User. Include country code for valid canonicalization.

String

Optional

ims

Array of one or more im (Instant Message) address values for the user.

String

Optional

roles

Array of one or more role values that this user holds.

String

Optional

entitlements

Array of one or more entitlement values that this user has.

String

Optional

addresses

Array containing one or more Address objects.

Address

Optional

x509Certificates

An array of one ore more x509certificate values that each contain an X509 Certificate issued to the user.

String

Optional

schemas

The schema identifier for the SCIM request.

String

Optional

id

Unique identifier for the SCIM User as defined by Workplace. Each User will always contain a non-empty id value. This identifier will be unique across all Workplace users and it will be a stable, non-reassignable that does not change with the same User is returned in subsequent requests.

String

Optional

externalId

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.

String

Optional

Enterprise Extension

The following properties belong to the SCIM extension enterprise:1.0

FieldDescriptionTypeRequired

employeeNumber

Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization.

String

Optional

costCenter

Identifies the name of a cost center. enterprise:1.0

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

A complex type that optionally allows Service Providers to represent organizational hierarchy by referencing the id attribute of another User.

Manager

Optional

Note that you need to remove the entire "manager": { "managerId": "manager id"} parameter in case you want to remove a manager from a user.

Account Status Details Extension

The following properties belong to the SCIM extension facebook:accountstatusdetails:1.0

FieldDescriptionTypeRequired

invited

Field that shows whether a user is invited or not

Boolean

Optional

claimed

Field that shows whether a user has claimed the account or not

Boolean

Optional

invitedDate

Field that shows when a user was invited formatted as a Unix timestamp

String

Optional

claimedDate

Field that shows when a user claimed the account formatted as a Unix timestamp

String

Optional

claimLink

The unique claim link that allows a user to claim the account

URL

Optional

canDelete

Field that shows if a user can be deleted

Boolean

Optional

Depending on whether a user is created, invited or claimed the account, the field values within the account status details will appear or change.

GET:

unclaimed and deactivated account

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"invited": false,

"inviteDate": 1495201229

"canDelete": true

}

unclaimed and invited account

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"claimLink": "<claimLink url>",

"invited": true,

"inviteDate": 1495201229

"canDelete": true

}

claimed (with claimlink) account

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": true,

"claimDate": 1495449275,

"invited": true,

"inviteDate": 1495201229

"canDelete": false

}

unclaimed and not invited account

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"invited": false,

"inviteDate": 0

"canDelete": true

}

PUT:

update account from unclaimed to claimed

Request:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": true,

"claimLink": "<claimLink url>",

"invited": true,

"inviteDate": 1495201229

"canDelete": true

}

Response:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"claimLink": "<claimLink url>",

"invited": true,

"inviteDate": 1495201229

"canDelete": true

}

This operation is not permitted. Notice in the response that the claimed value didn't change (the request will silently fail).

update account from claimed to unclaimed

Request:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"claimDate": 1495458062

"invited": true,

"inviteDate": 1495201229

"canDelete": false

}

Response:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"claimLink": "<claimLink url>",

"invited": true,

"inviteDate": 1495201229

"canDelete": false

}

update account from not invited to invited

You can use a PUT request to change the invited value from invited "false" to invited "true".

You can only use a PUT request to invite users, using the invite "true" value during a POST request will create the user but the user won't be invited unless this is configured in the general settings of your instance.

Request:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"invited": true,

"invitedDate": 0,

"canDelete": true

}

Response:

"urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {

"claimed": false,

"claimLink": "<claimLink url>",

"invited": true,

"inviteDate": 1495201229

"canDelete": true

}

Authentication Method Extension

The following properties belong to the SCIM extension facebook:auth_method:1.0

The Authentication Method Extension will allow you to set the authentication method in case that you've enabled the possibility to log in with either "sso" or "password".

Note that the value of the "auth_method" will be set to the default value that was configured in the Admin Panel when you create new users without setting the value of the "auth_method".

GET Request

When retrieving the information of a user, the value of the "auth_method" will be visible in case that you're instance has hybrid authentication enabled.

Single Sign On:

"urn:scim:schemas:extension:facebook:auth_method:1.0": {

auth_method": "sso"

}

Username / Password:

"urn:scim:schemas:extension:facebook:auth_method:1.0": {

auth_method": "password"

}

POST Request

In case the hybrid authentication is enabled for your instance, you can trigger a POST Request to create your users and set the "auth_method" to "sso" or "password". In this case, the created user will only be able to log in with the configured "auth_method".

PUT Request

In case hybrid authentication is enabled for your instance, you can trigger a PUT Request to update the "auth_method" of your users and change the "auth_method" to "sso" or "password".

Start / Termination Date Extension

The following properties belong to the SCIM extension facebook:starttermdates:1.0

FieldDescriptionTypeRequired

startDate

Field that contains the date the employee was hired formatted as a Unix timestamp (the number of seconds since January 1 1970 00:00:00 UTC). Schema: urn:scim:schemas:extension: facebook:starttermdates:1.0

String

Optional

termDate

Field that contains the date the employee was terminated, if any, formatted as a Unix timestamp (the number of seconds since January 1 1970 00:00:00 UTC). Schema: urn:scim:schemas:extension:

String

Optional

Name Data Structure

The following fields make up the Name data structure used by the name field.

FieldDescriptionTypeRequired

formatted

The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Ms. Barbara J Jensen, III.).

String

Required

familyName

The family name of the User, or Last Name in most Western languages (e.g. Jensen given the full name Ms. Barbara J Jensen, III.).

String

Optional

givenName

The given name of the User, or First Name in most Western languages (e.g. Barbara given the full name Ms. Barbara J Jensen, III.).

String

Optional

middleName

The middle name(s) of the User.

String

Optional

honorificPrefix

The honorific prefix(es) of the User, or Title in most Western languages (e.g. Ms. given the full name Ms. Barbara J Jensen, III.).

String

Optional

honorificSuffix

The honorific suffix(es) of the User, or Suffix in most Western languages (e.g. III. given the full name Ms. Barbara J Jensen, III.).

String

Optional

Email Data Structure

The following describes the data structure used by the email field.

FieldDescriptionTypeRequired

primary

Boolean value indicating whether this is the primary address.

Boolean

Optional

type

Type of this address, e.g., work or personal.

String

Optional

value

Email address.

String

Required

Address Data Structure

The following describes the data structure used by the address field.

FieldDescriptionTypeRequired

primary

Boolean value indicating whether this is the primary address.

Boolean

Optional

type

Type of this address, e.g., work or personal.

String

Optional

streetAddress

The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information. This attribute MAY contain newlines.

String

Optional

locality

The city or locality component.

String

Optional

region

The state or region component.

String

Optional

postalCode

The zipcode or postal code component.

String

Optional

country

The country name component. When specified the value MUST be in ISO 3166-1 alpha 2 short code format; e.g., the United States and Sweden are US and SE respectively.

String

Optional

formatted

The full mailing address, formatted for display or use with a mailinglabel. This attribute MAY contain newlines.

String

Optional

Manager Data Structure

The following describes the data structure used by the manager field.

FieldDescriptionTypeRequired

managerId

The id of the SCIM user representing the manager of this user.

String

Required

displayName

Display name of the manager.

String

Optional

Create accounts without email addresses (beta only)

We now allow for users to be created without the need for an actual email address. In order to do this, you will need to create a user that has an external id and a formatted name. You can still choose to add other attributes in case you want to add a user with rich profile data.

How can I create and update a user without an email address?

POST Request

In order to create an email less user, you'll need to create a user that has at least the following parameters:

  • externalId
  • formatted name

The request could look like the following:

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:facebook:auth_method:1.0"
  ],
  "externalId": "1745847",
  "name": {
    "formatted": "Julius Caesar"
  },
  "active": true,
  "urn:scim:schemas:extension:facebook:auth_method:1.0": {
    "auth_method": "password"
  }
}

The response in this case would look like this:

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:enterprise:1.0",
    "urn:scim:schemas:extension:facebook:starttermdates:1.0",
    "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0",
    "urn:scim:schemas:extension:facebook:auth_method:1.0"
  ],
  "id": 100024833978801,
  "externalId": "1745847",
  "name": {
    "formatted": "Julius Caesar"
  },
  "active": true,
  "urn:scim:schemas:extension:facebook:starttermdates:1.0": {
    "startDate": 0,
    "termDate": 0
  },
  "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
    "accessCode": "dwsngnlinocitezt",
    "accessCodeExpirationDate": 1528384514,
    "claimed": false,
    "invited": true,
    "inviteDate": 1520608512
  },
  "urn:scim:schemas:extension:facebook:auth_method:1.0": {
    "auth_method": "password"
  }
}

It's important to know that the response won't create a username yet. The username will only be set once the user activates the account by using the access code on the desktop or mobile applications.

Once the user activated the account, you will get the following response:

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:enterprise:1.0",
    "urn:scim:schemas:extension:facebook:starttermdates:1.0",
    "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0",
    "urn:scim:schemas:extension:facebook:auth_method:1.0"
  ],
  "id": 100024833978801,
  "externalId": "1745847",
  "userName": "Julius.C",
  "name": {
    "formatted": "Julius Caesar"
  },
  "active": true,
  "urn:scim:schemas:extension:facebook:starttermdates:1.0": {
    "startDate": 0,
    "termDate": 0
  },
  "urn:scim:schemas:extension:facebook:accountstatusdetails:1.0": {
    "accessCode": "bcbegjpagzeqkwox",
    "accessCodeExpirationDate": 1528385241,
    "claimed": true,
    "claimDate": 1520609227,
    "invited": true,
    "inviteDate": 1520608512
  },
  "urn:scim:schemas:extension:facebook:auth_method:1.0": {
    "auth_method": "password"
  }
}

When the account is activated, you'll notice two things:

  • The username is visible
  • The access code has changed

Because of the fact that the username is now set, we can use an access code to reset the password of this user based on a username and access code.

auth_method needs to be "password"

It's not allowed to create an email less user with the auth_method set to "sso". We recommend that you add the "auth_method": "password" to all of the POST and PUT requests to avoid any errors in case the default authentication is set to "sso"

{
  "Errors": [
    {
      "description": "People without email have to use a password to log in: Select 'Password' for this users login method",
      "code": 1855128
    }
  ]
}
PUT Request

When you want to update a user, you can update any value apart from the following parameters:

Error message will be triggered when updating

  • username
{
  "Errors": [
    {
      "description": "You Can't Change Your Username: Usernames are permanent and can't be changed.",
      "code": 1855129
    }
  ]
}
  • auth_method to "sso"
{
  "Errors": [
    {
      "description": "You Can't Change Your Username: Usernames are permanent and can't be changed.",
      "code": 1855129
    }
  ]
}
The request will silently fail when updating
  • accessCode
  • accessCodeExpirationDate

When you try to change the values for these parameters, the original value will be returned.

How can I retrieve my email-less users?

GET Request

You can use the GET request in the same way that you would use the GET request for users with an email address. The only difference is that you will only be able to see a username in case the user claimed the account.

How can I delete or deactivate my email less users?

DELETE Request

You can use the DELETE request to delete users in case that those users didn't claim their account yet.

Deleting users that are already claimed

When you want to delete a user that claimed their account, you will need to do the following:

  • Deactivate the account by using the "active: true" to "active: false" flag.
  • Create a support ticket with the request to delete the account.
  • Once the support team responds that you can delete the account, you will be able to run the DELETE Request.

Usage Examples

Creating an Account for a Person

When a new person joins your organization or is newly-granted access to Workplace, you must create an account for them. To do so:

  • Send a POST request to the endpoint https://www.facebook.com/scim/v1/Users/
  • Upon success:
    • You will receive a 201 - Created response
    • The response body will contain a JSON representation of the person's account, including the Workplace-assigned ID, which must be used to do any subsequent update operations
    • You should store each person's Workplace ID in a database for later use in update operations
  • If a user already exists within your Workplace instance with the same username:
    • You will receive a 409 - Conflict response
    • The typical recovery path for a conflict is to:
      • Make a GET request using the username filter to retrieve the existing user
      • Merge your local user record with the existing Workplace user record
      • Do a PUT operation to update the Workplace user
  • You may receive another response code - refer to the error codes section below for more details

Once a new User Account is created, Workplace will begin sending invitation and other notification emails.

If you'd like to create the account without inviting the person immediately, you must disable the setting Send invites when accounts are created on the Settings tab of the Admin Panel.

Read more.

Create a User with a Profile Picture

Any manual updates made by an employee to their profile picture will change their account to a manual updates only mode. After being switched to manual mode, Workplace will no longer use updates to the photos field for updating an account's profile picture.

You can create a user and set their initial Workplace profile picture if you have an internet-accessible image URL for the person by including the photos attribute with the type set to profile and primary set to true.

"photos": [
    {
         "value": "http://www.example.com/julius_profile_pic.jpeg",
         "type": "profile",
         "primary": true
    }
]

Remove the profile picture that was set through the API

You can clear the profile picture, thus setting it back to the default appearance, by removing the photos attribute, the array value or changing the primary value to false.

You're only able to set or clear the profile picture through the api in case the user hasn't done this through the UI.

Getting All Users

You can retrieve the information about your users:

  • Send a GET request to the endpoint https://www.facebook.com/scim/v1/Users}
  • By default, a GET request on /Users will return results in pages of 100
  • You can specify a different page size and page offset by including the parameters count and startIndex.
GET /scim/v1/Users?count=10&startIndex=20 HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

Upon success:

  • You will receive a 200 - OK response
  • The response body will contain a JSON representation of the requested users

Getting one user by ID

You can retrieve a single user by the user's Workplace ID:

GET /scim/v1/Users/{Workplace-assigned user id} HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

If a user doesn't exist:

  • You will receive a 404 - OK response
  • Error message: “User or Group Not Available: The user or group you tried to access from SCIM is not available.”

You can only get a user if you are authorized to see the user, i.e., if that user exists within your Workplace instance

Getting one User by Username

You can retrieve a single user by username / email address by including a username filter:

GET /scim/v1/Users?filter=userName%20eq%20%22juliusc@example.com%22 HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

If no user exists with that username, you will receive an empty response list.

You can only get a user if you are authorized to see the user; i.e., if that user exists within your Workplace instance

Getting one User by External Id

You can retrieve a single user by their external id by including a username filter:

GET /scim/v1/Users?filter=externalId%20eq%20%22{external-id}%22 HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

If no user exists with that externalId, you will receive an empty response list.

You can only get a user if you are authorized to see the user; i.e., if that user exists within your Workplace instance

Setting Manager IDs

Workplace recommends always setting manager IDs for your users, since it creates a better user experience for the people using the product.

  1. You can set a user's manager during either a POST or a PUT operation, but doing so requires having the Workplace-assigned user ID for the manager.
  2. When doing create operations, you may not yet have the manager's user ID when you create the user.
  3. To simplify this, use two-pass logic (explained below) to create users and then set manager IDs.

Two-pass Logic

On the first pass:

  1. Iterate over each user
  2. Build the request payload, but do not set the manager relationship
  3. Simply create each user by sending a POST request
  4. Store each created-users' IDs in a data store

After users have been created, do a second pass to update each user's manager:

  1. Iterate over each user
  2. Lookup the user's manager's Workplace user ID in your data store
  3. Create the request payload for this user, adding the manager's ID to the request body
  4. Finally send a PUT request to Workplace to update the user and set the manager relationship

Updating a User

When any user attribute changes in your user directory, you must update the user's account in Workplace. This can either be done on event, when the underlying data changes, or in a batch, say every 3 hours. In either case, the logic is the same:

  1. Prepare the request body with the updated data.
  2. Send a PUT request to the endpoint https://www.facebook.com/scim/v1/Users/{Workplace-assigned user id}
  3. Upon success, you will receive a 200 - OK response
  4. If the user id you specified does not exist, you will receive a 404 - Not Found response

Workplace only supports PUT requests with a complete request body. Incremental PATCH requests are not supported.

Deactivating a User's Account

When a person leaves your organization or should not longer have access to Workplace, you must deactivate their account:

  1. Generate the request body setting the attribute active to false.
  2. Send a PUT request to the endpoint https://www.facebook.com/scim/v1/Users/{Workplace-assigned user id}
  3. Upon success, you will receive a 200 - OK response. The user will immediately be deactivated and any current mobile or web sessions for that user will be immediately terminated.

Deleting a User Account

If a person's account has been created in error and that account has never been claimed by the user you can delete it.

  1. Send a DELETE request to the endpoint https://www.facebook.com/scim/v1/Users/{Workplace-assigned user id}
  2. Upon success, you will receive a 200 - OK response
  3. If the account has ever been claimed, you will receive a 412 - Precondition Failed response

If a user has ever logged into their account, regardless whether the account is currently active, you cannot delete the account via the API.

Deleting users that are already claimed

When you want to delete a user that claimed their account, you will need to do the following:

  • Deactivate the account by using the "active: true" to "active: false" flag.
  • Create a support ticket with the request to delete the account.
  • Once the support team responds that you can delete the account, you will be able to run the DELETE Request.

Further Examples

Create a Person Who is a Manager

POST /scim/v1/Users/ HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "userName": "juliusc@example.com",
  "name": {
    "formatted": "Julius Caesar"
  },
  "active": true,
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "juliusc@example.com"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "formatted": "Emporer's Palace",
      "primary": true
    }
  ],
  "urn:scim:schemas:extension:enterprise:1.0": {
    "department": "Headquarters"
  }
}

Read the Manager's ID From the Response Body

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "id": 11111111111,
  "userName": "juliusc@example.com",
  "name": {
    "formatted": "Julius Caesar"
  },
  "active": true,
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "juliusc@example.com"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "formatted": "Foro Italico",
      "primary": true
    }
  ],
  "urn:scim:schemas:extension:enterprise:1.0": {
    "department": "Headquarters"
  }
}

Create a Person With an Assigned Manager

POST /scim/v1/Users/ HTTP/1.1
Host: www.facebook.com
Authorization: Bearer {your access token}

{
  "schemas": [
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:extension:enterprise:1.0"
  ],
  "userName": "marka@example.com",
  "name": {
    "formatted": "Mark Antony"
  },
  "active": true,
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "marka@example.com"
    }
  ],
  "addresses": [
    {
      "type": "work",
      "formatted": "Foro Italico",
      "primary": true
    }
  ],
  "urn:scim:schemas:extension:enterprise:1.0": {
    "department": "Senate",
    "manager": {
      "managerId": 11111111111
    }
  }
}