This document provides example requests for the most commonly used SCIM API requests in Work Accounts. For information on the SCIM data structure, see API Reference. For information on step by step tutorials, see Guides. Guides differs from the information presented in this document; the examples provided here reflect singular requests whereas guides will provide step by step instructions that may execute multiple sequential requests or administrative tasks.
This request creates a new user account. Newly created user accounts will immediately begin receiving invitation and other notification emails from Work Accounts.
Note that not all objects in the request body are required. The request body lists all available fields associated with the Users endpoint. Only the userName
field is required to create a new user account. For more information on the data structure, see the API Reference page.
POST /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:schemas:core:2.0/User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User" ], "userName":"{STRING}", "name":{ "formatted":"{STRING}", "familyName":"{STRING}", "givenName":"{STRING}", "middleName":"{STRING}", "honorificPrefix":"{STRING}", "honorificSuffix":"{STRING}" }, "active":{BOOLEAN}, "displayName":"{STRING}", "title":"{STRING}", "nickName":"{STRING}", "profileURL":"{URL}", "preferredLanguage":"{STRING}", "locale":"{STRING}", "timezone":"{STRING}", "userType":"{STRING}", "photos":[ "value":"{URL}", "type":"{STRING}", "primary":{BOOLEAN} ], "emails":[ { "value":"{STRING}", "display":"{STRING}", "primary":{BOOLEAN}, "type":"{STRING}", } ], "phoneNumbers":["{STRING}"], "ims":["{STRING}"], "roles":["{STRING}"], "entitlements":["{STRING}"], "addresses":[ { "primary":{BOOLEAN}, "type":"{STRING}", "streetAddress":"{STRING}", "locality":"{STRING}", "region":"{STRING}", "postalCode":"{STRING}", "country":"{STRING}", "formatted":"{STRING}" } ], "x509Certificates":["{STRING}"], "id":"{STRING}", "externalId":"{STRING}", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "employeeNumber":"{STRING}", "costCenter":"{STRING}", "organizaation":"{STRING}", "division":"{STRING}", "department":"{STRING}", "manager":{ "value":"{STRING}", "$ref":"{READ ONLY}", "displayName":"{READ ONLY}" } }, "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": { "authMethod": "{STRING}" }, "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User":{ "accessCode":"{READ ONLY}", "accessCodeExpirationDate":"{READ ONLY}", "canDelete":{READ ONLY}, "claimed":{BOOLEAN}, "claimDate":"{DATE/TIME}", "claimLink":"{URL}", "invited":{BOOLEAN}, "invitedDate":"{STRING}" }, "urn:ietf:params:scim:schemas:extension:facebook:starttermdates:2.0:User":{ "startDate":"{YYYY-MM-DDThh:mm:ssZ}", "termDate":"{YYYY-MM-DDThh:mm:ssZ}" } }
201: Created
The system will return a JSON representation of the user account including a Work Accounts generated id
. This ID is required to perform any subsequent account update operations. It's recommended that Work Accounts IDs are stored in a database for reference in future patch operations.
Example |
---|
Request PathPOST /Users HTTP/1.1 Host: scim.workplace.com |
Request Body{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User" ], "userName":"anne@example.com", "name":{ "givenName":"Anne", }, "active":true, "displayName":"Anne", "emails":[ { "value":"anne@example.com", "primary":true, } ], "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "employeeNumber":"007", } }, "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": { "authMethod": "sso" } } |
Response{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User" ], "userName":"anne@example.com", "name":{ "givenName":"Anne", }, "active":true, "displayName":"Anne", "emails":[ { "value":"anne@example.com", "primary":true, } ], "id":"1987", "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": { "employeeNumber":"007", } }, "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": { "authMethod": "sso" } } |
409: Conflict
This error indicates that there is a pre-existing user account with the same username. This can typically be resolved by performing a PATCH operation on the existing user account and updating the relevant fields.
This request returns the JSON representation of a specified user's account. The request can be tailored to request all users or to request singular users by username, external ID or Work Accounts ID. The response will yield an empty set if the specified user does not exist.
By idBy usernameBy external IDAll UsersMultiple specific users cannot be called using a singular request. Multiple singular requests must be executed to retrieve multiple specific users.
This request identifies a user by the Work Accounts generated id
.
GET /Users/`WORK ACCOUNTS ID` HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}
200: Success
Returns a JSON representation of the user's account.
Example |
---|
Request PathGET /Users/2567 Host: scim.workplace.com |
Response{ "userName":"joe@example.com", "active":true, "id":"2567" } |
This request identifies a user by the value of the customer-defined userName
. The username is added to the request as a filter parameter.
GET /Users?filter=userName%20eq%20%22`{USERNAME}`%22 HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}
200: Success
Returns a JSON representation of the user's account.
Example |
---|
Request PathGET /Users?filter=userName%20eq%20%22ednash%22 Host: scim.workplace.com |
Response{ "userName":"ednash", "id":"2341" } |
This request identifies a user by the value of the customer-defined externalId
. The externalId is added to the request as a filter parameter.
GET /Users?filter=externalId%20eq%20%22`{EXTERNAL ID}`%222 HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}
200: Success
Returns a JSON representation of the user's account.
Example |
---|
Request PathGET /Users?filter=externalId%20eq%20%22JB007%222 Host: scim.workplace.com |
Response{ "userName":"james@example.com", "externalId":"JB007" "id":"2567" } |
This request returns a JSON representation of all user accounts. The default request will return results in pages of 1,000 users. You can configure the request to specify the number of users per page and the page offset by adding count
and startIndex
parameters to the request.
GET /Users/ HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}Request Body: Configured
GET /Users?count=10&startIndex=20 HTTP/1.1 Host: scim.workplace.com Authorization: Bearer {your access token} User-Agent: {your user agent}
200: Success
Returns a JSON representation of all user accounts.
Example: Default |
---|
Request PathGET /Users Host: scim.workplace.com |
Response(1000)[{...}, {...}, {...}, ...] 0: {...} 1: {...} 2: {...} 3: {...} 4: {...} 5: {...} "userName":"james@example.com", "id":"6" ... 999:{...} "userName":"jane@example.com", "active":true "id":"1000" |
Example: configured |
---|
Request PathGET /Users?count=10&startIndex=2 Host: scim.workplace.com |
Response(10)[{...}, {...}, {...}, ...] 10: {...} 11: {...} 12: {...} 13: {...} 14: {...} 15: {...} "userName":"james@example.com", "id":"16" ... 19:{...} "userName":"jane@example.com", "active":true "id":"20" |
The following section covers requests for commonly updated account fields. All non-read-only fields can be updated similarly.
This request updates an account from a not invited
state to an invited
state.
Invited users cannot be uninvited. The request will silently fail and return a response with unchanged values.
PATCH /Users/`{WORK ACCOUNTS ID}`/ 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": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:invited", "value":true }] }
200: Success
Returns a JSON representation of the user's account with "invited":true
.
Example |
---|
Request PathPATCH /Users/7065 Host: scim.workplace.com |
Request Body{ "schemas":[ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations":[{ "op": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:invited", "value":true }] } |
Response{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User" ], "userName":"d.grayson", "id":"7065", "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": { "invited":true } } |
This request updates an account from a claimed
state to an unclaimed
state.
Unclaimed accounts cannot be converted to claimed. The request will silently fail and return a response with unchanged values.
PATCH /Users/`{WORK ACCOUNTS ID}`/ 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": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:claimed", "value":true }] }
200: Success
Returns a JSON representation of the User's account with "claimed": false
.
Example |
---|
Request PathPATCH /Users/616 Host: scim.workplace.com |
Request Body{ "schemas":[ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations":[{ "op": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User:claimed", "value":false }] } |
Response{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User", "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User" ], "userName":"t.drake", "id":"616", "urn:ietf:params:scim:schemas:extension:facebook:accountstatusdetails:2.0:User": { "claimed":false } } |
This request sets a user's authentication method to either sso
or password
. Users will only be able to access the system using the method defined here.
PATCH /Users/`{WORK ACCOUNTS ID}`/ 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": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User:authMethod", "value": "{sso/password}" }] }
200: Success
Returns a JSON representation of the user's account with authMethod
set to the specified value.
Example |
---|
Request PathPATCH /Users/10002 Host: scim.workplace.com |
Request Body{ "schemas":[ "urn:ietf:params:scim:api:messages:2.0:PatchOp" ], "Operations":[{ "op": "replace", "path": "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User:authMethod", "value": "password" }] } |
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" "id": "10002", "active": true, "urn:ietf:params:scim:schemas:extension:facebook:authmethod:2.0:User": { "authMethod": "password" } } |