Examples

Complete request and response pairs, headers included.

Create

To create a resource, send an HTTP POST request to the resource's respective endpoint. In the example below we see the creation of a User.

As can be seen in this and later examples, the URL contains a version number so that different versions of the SCIM API can co-exist. Available versions can be dynamically discovered via the ServiceProviderConfig endpoint.

Request

POST /v2/Users HTTP/1.1
Accept: application/json
Authorization: Bearer h480djs93hd8
Host: example.com
Content-Length: ...
Content-Type: application/json

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "externalId":"dschrute",
  "userName":"dschrute",
  "name":{
    "familyName":"Schrute",
    "givenName":"Dwight"
  }
}

A response contains the created resource and HTTP code 201 to indicate that the resource has been created successfully. Note that the returned user contains more data than was posted: id and meta have been added by the service provider to make a complete User resource. A Location header indicates where the resource can be fetched in subsequent requests.

Response

HTTP/1.1 201 Created
Content-Type: application/scim+json
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"dschrute",
  "meta":{
    "resourceType":"User",
    "created":"2011-08-01T21:32:44.882Z",
    "lastModified":"2011-08-01T21:32:44.882Z",
    "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
    "version":"W\/\"e180ee84f0671b1\""
  },
  "name":{
    "familyName":"Schrute",
    "givenName":"Dwight"
  },
  "userName":"dschrute"
}

Get

Fetching resources is done by sending HTTP GET requests to the desired resource endpoint, as in this example.

Request

GET /v2/Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8

The response to a GET contains the resource. The ETag header can, in subsequent requests, be used to prevent concurrent modifications of resources.

Response

HTTP/1.1 200 OK
Content-Type: application/scim+json
Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3"

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id":"2819c223-7f76-453a-919d-413861904646",
  "externalId":"dschrute",
  "meta":{
    "resourceType": "User",
    "created":"2011-08-01T18:29:49.793Z",
    "lastModified":"2011-08-01T18:29:49.793Z",
    "location":"https://example.com/v2/Users/2819c223...",
    "version":"W\/\"f250dd84f0671c3\""
  },
  "name":{
    "formatted": "Mr. Dwight K Schrute, III",
    "familyName": "Schrute",
    "givenName": "Dwight",
    "middleName": "Kurt",
    "honorificPrefix": "Mr.",
    "honorificSuffix": "III"
  },
  "userName":"dschrute",
  "phoneNumbers":[
    {
      "value":"555-555-8377",
      "type":"work"
    }
  ],
  "emails":[
    {
      "value":"dschrute@example.com",
      "type":"work",
      "primary": true
    }
  ]
}

Filter

In addition to getting single resources it is possible to fetch sets of resources by querying the resource endpoint without the id of a specific resource. Typically a fetch request will include a filter to be applied to the resources. SCIM has support for the filter operations equals, contains, starts with, and more.

In addition to filtering the response it is also possible to ask the service provider to sort the resources in the response, return specific attributes of the resources, and return only a subset of the resources.

Request

https://example.com/{resource}?filter={attribute} {op} {value}&sortBy={attributeName}&sortOrder={ascending|descending}&attributes={attributes}

https://example.com/Users?filter=title pr and userType eq "Employee"&sortBy=title&sortOrder=ascending&attributes=title,username

The response to a filtered GET request is a list of matching resources:

Response

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults":2,
  "Resources":[
    {
      "id":"c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
      "title":"Assistant VP",
      "userName":"dschrute"
    },
    {
      "id":"a4a25dd3-17a0-4dac-a2ac-ce211e125f57",
      "title":"VP",
      "userName":"jsmith"
    }
  ]
}

Specifications The normative documents Implementations Libraries and services