Search users

POST 
/nevisidm/api/scim/v1/:clientExtId/Users/.search

Searches users using a POST request with a SCIM search request body. Functionally equivalent to the GET list endpoint but allows complex filter expressions and parameters to be passed in the request body instead of query parameters.

Specific credential types can be selected using credentials[TYPE] syntax in the attributes/excludedAttributes parameters, e.g. credentials[PASSWORD] or credentials[OTP]. Only the specified credential types will be included in or excluded from the response.

Request

Path Parameters

clientExtId stringrequired
Client's external identifier.
Example: 100

application/json

Body

required

Query request attributes.

attributes string[]

A multi-valued list of strings indicating the names of resource attributes to return in the response, overriding the set of attributes that would be returned by default.

excludedAttributes string[]

A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return.

filter string

The filter string used to request a subset of resources.

sortBy string

A string indicating the attribute whose value be used to order the returned responses.

sortOrder string

Sort order of selected attribute (in 'sortBy' parameter). Empty value means the default ascending sorting order. Allowable values: ascending, descending.

startIndex int32

An integer indicating the 1-based index of the first query result.

count int32

An integer indicating the desired maximum number of query results per page.

bulkImportFormat boolean

The output is ScimBulkRequest with create operations instead of ScimListResponse as standard defines. This optional parameter by default false.

Responses

200

Search results retrieved successfully

application/json

Schema

Schema

schemas string[]required

An array of Strings containing URIs that are used to indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure.

totalResults int64required

Number of total results.

itemsPerPage int32required

Number of results in a single response. By default 10. Controlled by 'count' request parameter.

startIndex int64required

Start index of current result. By default 1. Controlled by 'startIndex' request parameter.

Resources ScimBase[]required
Array of SCIM resources. For example array of users.
Array [
schemas string[]required
An array of Strings containing URIs that are used to indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure.
]

Example (from schema)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "totalResults": 100,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "100",
      "userName": "[email protected]"
    },
    {}
  ]
}

User list

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "123456",
      "externalId": "user-123",
      "userName": "jdoe",
      "name": {
        "formatted": "John Doe",
        "familyName": "Doe",
        "givenName": "John"
      },
      "displayName": "John Doe",
      "active": true,
      "emails": [{"value": "[email protected]"}],
      "meta": {
        "resourceType": "User",
        "created": "2024-01-15T10:30:00",
        "lastModified": "2024-01-15T10:30:00",
        "location": "https://idm.example.com/nevisidm/api/scim/v1/100/Users/100-1001"
      }
    }
  ]
}

Schemas endpoint

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 2,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
      "id": "urn:ietf:params:scim:schemas:core:2.0:User",
      "name": "User",
      "description": "SCIM provides a resource type for User resources.",
      "attributes": [
        {
          "name": "userName",
          "type": "string",
          "multiValued": false,
          "description": "Unique identifier for the User.",
          "required": false,
          "caseExact": true,
          "mutability": "readWrite",
          "returned": "default",
          "uniqueness": "none"
        },
        {
          "name": "name",
          "type": "complex",
          "subAttributes": [
            {
              "name": "familyName",
              "type": "string",
              "multiValued": false,
              "required": false,
              "caseExact": true,
              "mutability": "readWrite",
              "returned": "default",
              "uniqueness": "none"
            }
          ]
        }
      ]
    }
  ]
}

ResourceTypes endpoint

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 1,
  "itemsPerPage": 10,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id": "User",
      "name": "User",
      "description": "SCIM provides a resource type for User resources.",
      "meta": {
        "resourceType": "ResourceType",
        "location": "https://idm.example.com/nevisidm/api/scim/v1/ResourceTypes/User"
      },
      "endpoint": "/{clientExtId}/Users",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [
        {
          "required": true,
          "schema": "urn:nevis:idm:scim:schemas:v1:extension:User"
        }
      ]
    }
  ]
}

Bulk export format with users list

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
  "failOnErrors": 10,
  "Operations": [
    {
      "method": "POST",
      "path": "Users",
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User",
          "urn:nevis:idm:scim:schemas:v1:extension:User"
        ],
        "userName": "jdoe"
      }
    },
    {
      "method": "POST",
      "path": "Users",
      "data": {
        "schemas": [
          "urn:ietf:params:scim:schemas:core:2.0:User",
          "urn:nevis:idm:scim:schemas:v1:extension:User"
        ],
        "userName": "jdoe2"
      }
    }
  ]
}

400

Invalid SCIM request

application/json

Schema

Schema

schemas string[]required

An array of Strings containing URIs that are used to indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure.

status HttpStatusCoderequired
The HTTP status code.
error boolean
is1xxInformational boolean
is2xxSuccessful boolean
is3xxRedirection boolean
is4xxClientError boolean
is5xxServerError boolean
scimType string

Possible values: [invalidFilter, tooMany, uniqueness, mutability, invalidSyntax, invalidPath, noTarget, invalidValue, invalidVers, sensitive]

A SCIM detail error keyword.

detail string

A detailed human-readable message.

Example (from schema)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "status": 400,
  "scimType": "invalidValue",
  "detail": "The requested user '999' does not exist in IDM database."
}

Count exceeds maximum

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "BAD_REQUEST",
  "scimType": "invalidValue",
  "detail": "Count is higher than allowed (100)"
}

Invalid pagination parameters

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "BAD_REQUEST",
  "scimType": "invalidValue",
  "detail": "Start index must be positive"
}

Invalid filter attribute

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "BAD_REQUEST",
  "scimType": "invalidValue",
  "detail": "Filter attribute 'invalidAttr' is not valid or unsupported or encrypted."
}

Filter parse error

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "BAD_REQUEST",
  "scimType": "invalidValue",
  "detail": "Filter expression cannot be parsed. Message: Missing expected character '@' at '9' in 'userName @'"
}

422

Request body parse error

application/json

Schema

Schema

schemas string[]required

An array of Strings containing URIs that are used to indicate the namespaces of the SCIM schemas that define the attributes present in the current JSON structure.

status HttpStatusCoderequired
The HTTP status code.
error boolean
is1xxInformational boolean
is2xxSuccessful boolean
is3xxRedirection boolean
is4xxClientError boolean
is5xxServerError boolean
scimType string

Possible values: [invalidFilter, tooMany, uniqueness, mutability, invalidSyntax, invalidPath, noTarget, invalidValue, invalidVers, sensitive]

A SCIM detail error keyword.

detail string

A detailed human-readable message.

Example (from schema)

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "status": 400,
  "scimType": "invalidValue",
  "detail": "The requested user '999' does not exist in IDM database."
}

JSON parse error

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "status": "UNPROCESSABLE_ENTITY",
  "scimType": "invalidSyntax",
  "detail": "JSON parse error: Unexpected character ('x' (code 120))"
}

Loading...