Workplace from Meta is going away. You will be able to continue using Workplace until 31 August 2025. Visit our Help Center to find out more.
Deprecation Update:
SCIM 2.0 is the latest industry standard API for account management. With SCIM 2.0, your organisation will be able to better manage users at scale, via PATCH support.
See SCIM API 2.0 Documentation for more details and migration guides.
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.
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.
The SCIM API is available to custom integrations with the Manage Accounts
permission. To provide account management via a third party app, please see Account Management (Graph 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 is: https://www.workplace.com/scim/v1/
Only a Workplace user with the System Administrator privilege can change this configuration.
GET /scim/v1/Users/ HTTP/1.1
Host: www.workplace.com
Authorization: Bearer {your access token}
Note: A User-Agent
string is mandatory in all SCIM API requests.
The Account Management API data structure is comprised of the core SCIM schema and several schema extensions:
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
urn:scim:schemas:extension:facebook:frontline:1.0
The following properties belong to the core SCIM schema urn:scim:schemas:core:1.0
Field | Description | Type | Required |
---|---|---|---|
| Unique identifier for the user, used by the user to directly authenticate with the service provider. Must be unique. | String | Required |
| The components of the Users real name. | Required | |
| 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 of the user, e.g., Vice President. | String | Optional |
| 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 |
| A fully qualified URL to a page representing the user online profile. | URL | Optional |
| 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 |
| 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 |
| The timezone of the user in the Olson timezone database format, e.g., America/Los_Angeles. | String | Optional |
| 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 |
| 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 |
| Array of one or more | URL | Optional |
| Array of one or more Email objects for the user. | Optional | |
| Array of one or more | String | Optional |
| Array of one or more | String | Optional |
| Array of one or more | String | Optional |
| Array of one or more | String | Optional |
| Array containing one or more Address objects. | Optional | |
| An array of one ore more | String | Optional |
| The schema identifier for the SCIM request. | String | Optional |
| 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 |
| 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 |
The following properties belong to the SCIM extension enterprise:1.0
Field | Description | Type | Required |
---|---|---|---|
| Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization. | String | Optional |
| Identifies the name of a cost center.
| String | Optional |
| Identifies the name of an organization. | String | Optional |
| Identifies the name of a division. | String | Optional |
| Identifies the name of a department. | String | Optional |
| A complex type that optionally allows Service Providers to represent organizational hierarchy by referencing the | Optional |
Note: You need to set "manager": { "managerId": ""}
in case you want to remove a manager from a user.
The following properties belong to the SCIM extension facebook:accountstatusdetails:1.0
Field | Description | Type | Required |
---|---|---|---|
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 | Integer | Optional |
claimedDate | Field that shows when a user claimed the account formatted as a Unix timestamp | Integer | 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.
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
}
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
}
The following properties belong to the SCIM extension facebook:frontline:1.0
The Frontline User Extension will allow you to include or exclude the user in the Frontline set of users. Set the value of the key "is_frontline" to either true
or false
.
Note that including this schema will result in an error if the instance is not enabled for the Frontline feature set.
GET Request
When retrieving the information of a user, the value of the "is_frontline" will be visible in case that your instance has the Frontline feature enabled.
"urn:scim:schemas:extension:facebook:frontline:1.0": {
"is_frontline": true
}
POST Request
In the case where the Frontline feature set has been enabled in your instance, you can trigger a POST Request to create your user and put them in the Frontline people set.
PUT Request
In the case where the Frontline feature set has been enabled in your instance, you can trigger a PUT Request to include or exclude your user from the Frontline people set.
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".
Can't be set to SSO for emailLess users.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.
"urn:scim:schemas:extension:facebook:auth_method:1.0": {
auth_method": "sso"
}
"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".
The following properties belong to the SCIM extension facebook:starttermdates:1.0
Field | Description | Type | Required |
---|---|---|---|
| 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: | Integer | Optional |
| 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: | Integer | Optional |
The following fields make up the Name data structure used by the name
field.
Field | Description | Type | Required |
---|---|---|---|
| The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Ms. Barbara J Jensen, III.). | String | Required |
| 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 |
| 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 |
| The middle name(s) of the User. | String | Optional |
| 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 |
| 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 |
The following describes the data structure used by the email
field.
Field | Description | Type | Required |
---|---|---|---|
| Boolean value indicating whether this is the primary address. | Boolean | Optional |
| Type of this address, e.g., work or personal. | String | Optional |
| Email address. | String | Required |
The following describes the data structure used by the address
field.
Field | Description | Type | Required |
---|---|---|---|
| Boolean value indicating whether this is the primary address. | Boolean | Optional |
| Type of this address, e.g., work or personal. | String | Optional |
| 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 |
| The city or locality component. | String | Optional |
| The state or region component. | String | Optional |
| The zipcode or postal code component. | String | Optional |
| 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 |
| The full mailing address, formatted for display or use with a mailinglabel. This attribute MAY contain newlines. | String | Optional |
The following describes the data structure used by the manager
field.
Field | Description | Type | Required |
---|---|---|---|
| The id of the SCIM user representing the manager of this user. | String | Required |
| Display name of the manager. | String | Optional |
The base URL for the Account Management API is:
https://www.workplace.com/scim/v1
Below are the edges which can be used for various operations.
Edge | Description |
---|---|
/Users | To Create/Update/Delete users using above schemas. |
/Groups | To Create/Update/Delete People Sets using above schemas |
/Schemas | Supports /Schemas/Groups /Schemas/Users to get Group or User schema respectively. |
/ServiceProviderConfigs | Gives a summary of Workplace Schema |
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.
POST RequestIn order to create an email less user, you'll need to create a user that has at least the following parameters:
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:
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.
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
{ "Errors": [ { "description": "You Can't Change Your Username: Usernames are permanent and can't be changed.", "code": 1855129 } ] }
{ "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
When you try to change the values for these parameters, the original value will be returned.
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.
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:
"active: true"
to "active: false"
flag./Groups
endpoint supports Creating, Updating and Deleting peoplesets.
GET www.workplace.com/scim/v1
/Groups
GET www.workplace.com/scim/v1
/Groups/{peopleset-id}
Create a People set with members. The body must contain all member user IDs for a given people set.
POST www.workplace.com/scim/v1
/Groups/
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Test People Set",
"members": [
{
"type": "user",
"value": {{user_id}}
},
{
"type": "user",
"value": {{user_id}}
}
]
}
Updates People set Name and/or members. The body must contain all member user IDs for a given people set.
PUT www.workplace.com/scim/v1
/Groups/{peopleset-id}
{
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "New Set Name",
"members": [
{
"type": "user",
"value": {{user_id}}
},
{
"type": "user",
"value": {{user_id}}
}
]
}
DELETE www.workplace.com/scim/v1
/Groups/{peopleset-id}
When a new person joins your organization or is newly-granted access to Workplace, you must create an account for them. To do so:
https://www.workplace.com/scim/v1/Users/
201 - Created
response 409 - Conflict
response 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.
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 } ]
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 can retrieve the information about your users:
https://www.workplace.com/scim/v1/Users
/Users
will return results in pages of 1000.count
and startIndex
.GET /scim/v1/Users?count=10&startIndex=20 HTTP/1.1 Host: www.workplace.com Authorization: Bearer {your access token}
Upon success:
200 - OK
responseYou can retrieve a single user by the user's Workplace ID:
GET /scim/v1/Users/{Workplace-assigned user id} HTTP/1.1 Host: www.workplace.com Authorization: Bearer {your access token}
If a user doesn't exist:
404 - OK
responseYou can only get a user if you are authorized to see the user, i.e., if that user exists within your Workplace instance
You can retrieve a single user by username / email address by including a userName filter. Please note that email address should be URL encoded as shown below.
GET /scim/v1/Users?filter=userName%20eq%20%22juliusc%40example.com%22 HTTP/1.1 Host: www.workplace.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
You can retrieve a single user by their external id by including an externalId filter:
GET /scim/v1/Users?filter=externalId%20eq%20%22{external-id}%22 HTTP/1.1 Host: www.workplace.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
Workplace recommends always setting manager IDs for your users, since it creates a better user experience for the people using the product.
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:
https://www.workplace.com/scim/v1/Users/{Workplace-assigned user id}
200 - OK
response 404 - Not Found
response Workplace only supports PUT requests with a complete request body. Incremental PATCH requests are not supported.
When a person leaves your organization or should not longer have access to Workplace, you must deactivate their account:
active
to false
.https://www.workplace.com/scim/v1/Users/{Workplace-assigned user id}
200 - OK
response. The user will immediately be deactivated and any current mobile or web sessions for that user will be immediately terminated.If a person's account has been created in error and that account has never been claimed by the user you can delete it.
https://www.workplace.com/scim/v1/Users/{Workplace-assigned user id}
200 - OK
response412 - Precondition Failed
responseIf 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:
"active: true"
to "active: false"
flag.POST /scim/v1/Users/ HTTP/1.1 Host: www.workplace.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" } }
{ "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" } }
POST /scim/v1/Users/ HTTP/1.1 Host: www.workplace.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 } } }
On the first pass:
After users have been created, do a second pass to update each user's manager: