API Reference

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.

Base URL

Base URL: https://scim.workplace.com

Endpoints

Users: 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.

API Requests

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.

Example Request Path

GET /Users/ HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}
User-Agent: {your user agent}

Core User Schema

URN: 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.

Fixed Fields

Field	Description
`userName`** _{Type: String}	A customer-defined unique identifier for the user.
`name` _{Type: Object}	The properties of the user's name. Click See More to view the data structure of this object.
`formatted`** _{Type: String}	The user's complete name, formatted for display including all prefixes, suffixes and middle names as required. *Examples:* Mr. Tim Jason Grayson, III Dr. Russ Gellar, Sr Ms. Barbara Stephanie Martha Cain
`familyName` _{Type: String}	The family name (last name/surname) of the user.
`givenName` _{Type: String}	The given name (first name) of the user.
`middleName` _{Type: String}	The middle name(s) of the user.
`honorificPrefix` _{Type: String}	The honorific prefix(es) or title(s) of the user. *Examples:* Mr. Ms. Dr. Sir Lt. Gen.
`honorificSuffix` _{Type: String}	The honorific suffix(es) or title(s) of the user. *Examples:* Jr. Phd III Sr. (MD USN US Navy)
`active` _{Type: Boolean}	Identifies an account as active or inactive. Active users are able to access Work Accounts and receive notifications.
`displayName` _{Type: String}	The user's publicly displayed name. This will be the name displayed to end users.
`title` _{Type: String}	The title of the user. *Examples:* Vice President Director
`nickName` _{Type: String}	The preferred name of the user.
`profileUrl` _{Type: URL}	Any fully qualified URL to the user's online profile.
`preferredLanguage` _{Type: String}	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:* American English: en_us British English: en_gb Canadian French: fr_ca French French: fr_fr
`locale` _{Type: String}	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.
`timezone` _{Type: String}	The timezone of the user. The value must be in accordance with the Olson timezone database format. *Examples:* America/Los_Angeles America/Costa_Rica Asia/Kolkata
`userType` _{Type: String}	Identifies the user's relationship with their organization. Values should be in accordance with the organization's employee structure. *Examples:* Employee Contractor Temporary Intern
`photos` _{Type: Array, Object}	The properties for the user's reference image(s). Click See More to view the data structure of this object.
`value` _{Type: URL}	Any fully qualified URL to the user's reference image.
`type` _{Type: String}	Identifies the type of reference image. *Examples:* Profile Badge HR
`primary` _{Type: Boolean}	Identifies the primary photo of the account. Only one photo can be designated as the primary photo.
`emails` _{Type: Array, Object}	The properties of the user's email address(es). Click See More to view the data structure of this object.
`value`** _{Type: String}	The complete email address of the user.
`display` _{Type: String}	READ ONLY. The standardized representation of the user's email address. This will be the email address displayed to end users.
`primary` _{Type: Boolean}	Identifies the primary email address of the account. Only one email address can be designated as the user's primary email address.
`type` _{Type: String}	Identifies the email type in accordance with the organization's contacts structure. *Examples:* Work Personal School
`phoneNumbers` _{Type: Array, String}	The phone number(s) of the user. Include country code for valid canonicalization.
`ims` _{Type: Array, String}	The instant messaging address(es) of the user.
`roles` _{Type: Array, String}	The role(s) of the user.
`entitlements` _{Type: Array, String}	The user's entitlements in accordance with the organization's entitlements structure.
`addresses` _{Type: Array, Object}	The properties of the user's address(es). Click See More to view the data structure of this object.
`primary` _{Type: Boolean}	Identifies the user's primary address. Only one address can be designated as the user's primary address.
`type` _{Type: String}	Identifies the address type in accordance with the organization's contacts structure. *Examples:* Work Personal School
`streetAddress` _{Type: String}	The user's full street address including house/apt number, street name, P.O. box, etc as required. This field can accept multi-line extended street address information by allowing newlines (`\n`.)
`locality` _{Type: String}	The city or locality of the address.
`region` _{Type: String}	The state or region.
`postalCode` _{Type: String}	The zip code or postal code.
`country` _{Type: String}	The country name in accordance with the ISO 3166-1 alpha-2 short code format. *Examples:* US JP UK NG
`formatted` _{Type: String}	The full mailing address formatted for display or use with a mailing label. This field can accept multi-line extended street address information by allowing newlines (`\n`).
`x509Certificates` _{Type: Array, String}	One or more x509certificate values that each contain an X509 certificate issued to the user.
`schemas` _{Type: Array, String}	The URN(s) for the schema.
`id` _{Type: String}	READ ONLY. The Work Accounts generated unique identifier for the user.
`externalId` _{Type: String}	A customer-defined identifier for the User.

Enterprise Extension

URN: urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

This extension allows organizational properties to be attributed to an account.

Fixed Fields

Field	Description
`employeeNumber` _{Type: String}	A customer-defined employee identifier for the user.
`costCenter` _{Type: String}	Identifies the name of the user's cost center.
`organization` _{Type: String}	Identifies the name of the user's organization.
`division` _{Type: String}	Identifies the name of the user's division.
`department` _{Type: String}	Identifies the name of the user's department.
`manager` _{Type: Object}	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.
`value`** _{Type: String}	The Work Accounts generated `id` number for the manager's account.
`$ref` _{Type: String}	READ ONLY. The URI of the SCIM resource representing the User's manager.
`displayName` _{Type: String}	READ ONLY. The display name of the manager.

Start/Term Date Extension

URN: 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.

Fixed Fields

Field	Description
`startDate` _{Type: String}	The organization's hire date for the employee. Date format xsd:dateTime (YYYY-MM-DDThh:mm:ssZ)
`termDate` _{Type: String}	The organization's termination date for the employee. Date format xsd:dateTime (YYYY-MM-DDThh:mm:ssZ)

Account Status Details Extension

URN: 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.

Fixed Fields

Field	Description
`accessCode` _{Type: String}	READ ONLY. A Work Accounts generated access code for initial account login.
`accessCodeExpirationDate` _{Type: Date/Time}	READ ONLY. The expiration date for the access code.
`canDelete` _{Type: Boolean}	READ ONLY. Identifies whether the account can be deleted.
`claimed` _{Type: Boolean}	Identifies if the user has claimed the account or not.
`claimDate` _{Type: Date/Time}	Identifies the date (displayed as a Unix timestamp) when the user claimed the account.
`claimLink` _{Type: URL}	The URL that allows a user to claim the account.
`invited` _{Type: Boolean}	Identifies if a user is invited to Work Accounts or not.
`invitedDate` _{Type: Date/Time}	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
{ "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User":{ "claimed": false, "invited": false, "inviteDate": "2021-05-19T13:14:29+00:00" } }
Invited and unclaimed account
{ "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": { "claimed": false, "invited": false, "inviteDate": "2021-05-19T13:14:29+00:00" } }
Claimed (by claim link) account
{ "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": { "claimed": true, "claimDate": "2021-05-22T10:34:35+00:00", "invited": true, "inviteDate": "2021-05-19T13:14:29+00:00" } }
Not invited and unclaimed account
{ "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": { "claimed": false, "invited": false } }

Authentication Method Extension

URN: 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.

Fixed Fields

Field	Description
`authMethod` _{Type: String}	The authentication method for the user. The value can only be set to `sso` or `password`.

PATCH Operations

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: urn:ietf:params:scim:api:messages:2.0:PatchOp

Fixed Fields

Field	Description
`Operations` _{Type: Array, Object}	The properties of the patch operation. Click See More to view the data structure of this object.
`op` _{Type: String}	Identifies the operation key: add, replace, remove.
`path` _{Type: String}	Identifies the path for the field that will be updated.
`value` _{Type: String}	The updated value for the field. Not required for remove operations.

Request

Request Path

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 Path PATCH /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" } }

Example: Updating a User's Title

Request Path

PATCH /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"
    }
}

Prev: SCIM API Next: Examples