This document provides the data structure for the core schema, its extensions and for patch operations. For select example requests, see Examples and Guides.
Fields marked with an asterisk indicate required fields. Unless specifically designated as READ ONLY, all other fields are optional.
https://scim.workplace.com
https://scim.workplace.com/Users
The Users
endpoint is used to provision and manage user accounts. This is currently the only accessible endpoint for Work Accounts. All schema and extension properties outlined herein can be used with this endpoint.
All API requests must include Authorization
and User-Agent
headers. Authorization credentials require a valid access token. To learn more about generating access tokens, see Permissions.
GET /Users/ HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}
urn:ietf:params:scim:schemas:core:2.0:User
The core user schema provides the base properties to interface with the SCIM API. The root schema may be further expanded with the schema extensions found in the subsequent sections of this document.
Field | Description |
---|---|
| A customer-defined unique identifier for the user. |
| The properties of the user's name. Click See More to view the data structure of this object. |
| Identifies an account as active or inactive. Active users are able to access Work Accounts and receive notifications. |
| The user's publicly displayed name. This will be the name displayed to end users. |
| The title of the user. Examples: |
| The preferred name of the user. |
| Any fully qualified URL to the user's online profile. |
| The preferred language of the user. The value must be a language tag in accordance with ISO 639-1 and ISO 3166-1. For further details, see W3 language tags. Examples: |
| Identifies the user's default location for the purposes of localization. The value must be a language tag in accordance with ISO 639-1 and ISO 3166-1. For further details, see W3 language tags. |
| The timezone of the user. The value must be in accordance with the Olson timezone database format. Examples: |
| Identifies the user's relationship with their organization. Values should be in accordance with the organization's employee structure. Examples: |
| The properties for the user's reference image(s). Click See More to view the data structure of this object. |
| The properties of the user's email address(es). Click See More to view the data structure of this object. |
| The phone number(s) of the user. Include country code for valid canonicalization. |
| The instant messaging address(es) of the user. |
| The role(s) of the user. |
| The user's entitlements in accordance with the organization's entitlements structure. |
| The properties of the user's address(es). Click See More to view the data structure of this object. |
| One or more x509certificate values that each contain an X509 certificate issued to the user. |
| The URN(s) for the schema. |
| READ ONLY. The Work Accounts generated unique identifier for the user. |
| A customer-defined identifier for the User. |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
This extension allows organizational properties to be attributed to an account.
Field | Description |
---|---|
| A customer-defined employee identifier for the user. |
| Identifies the name of the user's cost center. |
| Identifies the name of the user's organization. |
| Identifies the name of the user's division. |
| Identifies the name of the user's department. |
| The properties of the user's manager. Click See More to view the data structure of this object. When removing a user's manager, the full object must be removed. It cannot contain an empty value. |
urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User
The Start/Termination Date Extension is used to store the start and termination dates of a user.
Field | Description |
---|---|
| The organization's hire date for the employee. Date format xsd:dateTime (YYYY-MM-DDThh:mm:ssZ) |
| The organization's termination date for the employee. Date format xsd:dateTime (YYYY-MM-DDThh:mm:ssZ) |
urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User
The Account Status Details Extension is used to identify specific states for a user account.
Field | Description |
---|---|
| READ ONLY. A Work Accounts generated access code for initial account login. |
| READ ONLY. The expiration date for the access code. |
| READ ONLY. Identifies whether the account can be deleted. |
| Identifies if the user has claimed the account or not. |
| Identifies the date (displayed as a Unix timestamp) when the user claimed the account. |
| The URL that allows a user to claim the account. |
| Identifies if a user is invited to Work Accounts or not. |
| Identifies the date (displayed as a Unix timestamp) when the invitation was sent. |
Note that when executing GET user requests, responses will vary depending on the state of the account.
Example Responses |
---|
Unclaimed and deactivated account |
Invited and unclaimed account |
Claimed (by claim link) account |
Not invited and unclaimed account |
urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User
This extension defines which authentication method users must use to log into their account.
Field | Description |
---|---|
| The authentication method for the user. The value can only be set to |
PATCH operations allow updates to specific fields. This reduces the overall payload size and mitigates accidental overwriting of existing values. PATCH requests can perform multiple field updates in a single request. Each field being updated is defined as an additional value in the Operations
object.
urn:ietf:params:scim:api:messages:2.0:PatchOp
Field | Description |
---|---|
| The properties of the patch operation. Click See More to view the data structure of this object. |
PATCH /Users HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}Request Body
{ "schemas":[ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations":[{ "op": "{ADD/REMOVE/REPLACE}", "path": "{URN:FIELD}", "value": ["{STRING/OBJECT/BOOLEAN}"] }, ... + additional operations... ] }
Example: Updating a User's Title |
---|
Request PathPATCH /Users/201 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent} |
Request Body{ "schemas":[ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations":[{ "op": "replace", "path": "urn:ietf:params:scim:schemas:core:2.0:User:title", "value": "Director" }] } |
Response{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User" ], "userName":"anne@example.com", "active":true, "title":"Director", "id":"201", "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": { "authMethod": "sso" } } |