Meta Work Accounts
Prev: API ReferenceNext: Guides

SCIM Examples

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.

User Requests

Create User

This request creates a new user account. Newly created user accounts will immediately begin receiving invitation and other notification emails from Work Accounts.

Request

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.

Request Path
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}"
    }
}

Response

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 Path
POST /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.

Get User

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 Users

Multiple specific users cannot be called using a singular request. Multiple singular requests must be executed to retrieve multiple specific users.

By ID

This request identifies a user by the Work Accounts generated id.

Request

Request Path
GET /Users/`WORK ACCOUNTS ID` HTTP/1.1
Host: scim.workplace.com
Authorization: Bearer {your access token}
User-Agent: {your user agent}

Response

200: Success

Returns a JSON representation of the user's account.

Example
Request Path
GET /Users/2567
Host: scim.workplace.com
Response
{
    "userName":"joe@example.com",
    "active":true,
    "id":"2567"
}

By Username

This request identifies a user by the value of the customer-defined userName. The username is added to the request as a filter parameter.

Request

Request Path
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}

Response

200: Success

Returns a JSON representation of the user's account.

Example
Request Path
GET /Users?filter=userName%20eq%20%22ednash%22
Host: scim.workplace.com
Response
{
    "userName":"ednash",
    "id":"2341"
}

By External ID

This request identifies a user by the value of the customer-defined externalId. The externalId is added to the request as a filter parameter.

Request

Request Body
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}

Response

200: Success

Returns a JSON representation of the user's account.

Example
Request Path
GET /Users?filter=externalId%20eq%20%22JB007%222
Host: scim.workplace.com
Response
{
  "userName":"james@example.com",
  "externalId":"JB007"
  "id":"2567"
}

All Users

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.

Request

Request Body: Default
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}

Response

200: Success

Returns a JSON representation of all user accounts.

Example: Default
Request Path
GET /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 Path
GET /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"
Account Updates

The following section covers requests for commonly updated account fields. All non-read-only fields can be updated similarly.

Update Invited State

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.

Request

Request Path
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
  }]
}

Response

200: Success

Returns a JSON representation of the user's account with "invited":true.

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

Update Claimed State

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.

Request

Request Path
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
  }]
}

Response

200: Success

Returns a JSON representation of the User's account with "claimed": false.

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

Update Authentication Method

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.

Request

Request Path
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}"
  }]
}

Response

200: Success

Returns a JSON representation of the user's account with authMethod set to the specified value.

Example
Request Path
PATCH /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"
    } 
}
Prev: API ReferenceNext: Guides