SCIM API for User Search

Use the SCIM API to find a user.

Authentication

Authorization: Bearer <Client Secret>

Use the copied Client Secret key as the Authorization key value.

Search Users with GET

You can filter for matching results by performing a GET and providing query parameter.

Request Requirements

Method Request URL Response Content Type Response Body Response Codes
GET

<Base URI>/Users

<Base URI>/Users/id

application/scim+json

User details 200, 400, 401

Example Request Data

GET < Base URI > /Users?filter= username+eq+"userName"
Authorization: Bearer 29da0602f6db1ed033aa91d644ce4d70bdf3ab58
Content-Type: application/scim + json

Response

The API returns the user details.

Example Response Body

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "Resources": [{
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "0189446a-4671-16ed-99d6-fe4917dc67f6",
            "externalId": "scim-user5-external",
            "meta": {
                "resourceType": "User",
                "created": "2023-01-06T06:02:58Z",
                "lastModified": "2023-01-06T06:02:58Z"
            },
            "userName": "clouduser5",
            "nickName": "Joe",
            "userType": "Temp",
            "preferredLanguage": "English",
            "locale": "us-en",
            "active": true,
            "emails": [{
                    "value": "Blair.Schmeler@yahoo.com",
                    "type": "work"
                }, {
                    "value": "scim-user2-home@rsavia.com",
                    "type": "home"
                }, {
                    "value": "scim-user2-other@rsavia.com",
                    "type": "other"
                }
            ],
            "phoneNumbers": [{
                    "value": "888888890",
                    "type": "mobile"
                }, {
                    "value": "888888889",
                    "type": "work"
                }, {
                    "value": "888888891",
                    "type": "home"
                }, {
                    "value": "888888938",
                    "type": "fax"
                }, {
                    "value": "888888189",
                    "type": "pager"
                }, {
                    "value": "888888992",
                    "type": "other"
                }
            ],
            "addresses": [{
                    "formatted": "BKR street Indiana,US",
                    "streetAddress": "MDP LYT",
                    "locality": "Brooklyn",
                    "region": "Bengaluru",
                    "postalCode": "780094",
                    "country": "US",
                    "type": "work",
                    "primary": true
                }, {
                    "formatted": "MDP LYT,Bangalore,India",
                    "streetAddress": "MDP LYT",
                    "locality": "Marathalli",
                    "region": "Bengaluru",
                    "postalCode": "560037",
                    "country": "India",
                    "type": "other",
                    "primary": false
                }
            ]
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 20
}

Search Users with GET Parameters

The following table describes the user search attributes used for the request parameters:

Request Parameter Description
filter User record filtration based on attributes
startIndex Starting index of paginated record
count Expected number of records to be returned
sortBy

List of records order by attribute name

The following list of attributes are allowed for this parameter:

userName

name.givenName

name.familyName

emails.work.value
sortOrder Way of ordering ascending or descending
attributes Attributes to be returned in response payload

User Search Filter Parameters

The search endpoints allow you to filter the rows in the result. To do so, use the filter parameter. You can use the NOT, AND, and OR operators between filters and use parentheses between conditions. The following table describes the user search attributes used for the request parameters:

Request Parameter Description
userName

Custom logon name of the user
name.givenName First name of the user
name.familyName Last name of the user
emails.work.value Work email address of the user
externalId External user ID of the user
active The user status
meta.lastModified The date for changes made to the user

Response Property Descriptions

See SCIM Attributes.

Response Codes

The following table shows response codes for this API.

Code Description
200 OK
400

Error message examples:

  • Invalid sortBy parameter.

  • Result count exceeds max limit 50.

  • Invalid attribute(s) provided.

  • Invalid Search Filter.

  • Invalid sortOrder parameter. It should be either ascending or descending.

  • Invalid Search filter.
401

Unauthorized
404

Not Found

Error message example:

  • User not found with id :{{User ID}}

  • User with id: {{User ID}} not found in identity source {{Identity Source ID}}

Search Users with POST

You can filter for matching resources by performing a POST against the special .search endpoint and providing a filter query parameter.

Request Requirements

Method Request URL Response Content Type Response Body Response Codes
POST

<Base URI>/.search


 application/scim+json User details 200, 400, 401

Example Request Data

POST <Base URI>/scim/v2/{{scimAppID}}/.search
Authorization: Bearer 29da0602f6db1ed033aa91d644ce4d70bdf3ab58
Content-Type: application/scim+json	
{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:SearchRequest"],
    "startIndex": 1,
    "count": 10,
    "filter": "userName eq \"Joanne.Halvorson75\"",
    "sortBy": "userName",
    "attributes": ["displayName", "userName", "name.givenName", "name.familyName"]
}

Response

The API returns the user details.

Example Response Body

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "totalResults": 1,
    "Resources": [{
            "schemas": [
                "urn:ietf:params:scim:schemas:core:2.0:User"
            ],
            "id": "0147b00f-9fd2-c1a1-8b4c-910d6cc24cdc",
            "userName": "Joanne.Halvorson75",
            "name": {
                "familyName": "Sporer",
                "givenName": "Millie"
            },
            "displayName": "scim-user3"
        }
    ],
    "startIndex": 1,
    "itemsPerPage": 10
}

Pagination

All search endpoints allow you to paginate your search. When searching, use the startIndex and count parameters to control the size of the page, the result will contain a totalResults attribute to allow you to compute the number of pages. This API is used to retrieve a paginated set of users with an optional filter.

Example Request Data

GET /Users?startIndex=1&count=10
Host: example.com
Accept: application/scim+json
Authorization: Bearer h480djs93hd8
The response to the query above returns metadata regarding paging
similar to the following example (actual resources removed for
brevity):
{
    "totalResults": 20,
    "itemsPerPage": 10,
    "startIndex": 1,
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "Resources": [{
            ...
        }
    ]
}