List users

The endpoint finds one or more users that match the provided query parameters.

HTTP request

GET https://$instanceId.id.nevis.cloud/nevis/api/v1/users?{queryParameters}

Parameters

Parameter	In	Type	Required / Optional	Description
instanceId	path	string	required	The ID of your Identity Cloud instance
<user-attribute>	query	generic	optional	Any user attribute. Supported are all attributes listed on HTTP response.
limit	query	integer	optional	The maximum size limit of the token-based pagination results Default 1000
continuationToken	query	string	optional	The token to retrieve the next set of the token-based pagination results

note

• userState query parameter only accepts the following values: active, blocked and notInvited. It is not supported to query users by pendingInvitation or expiredInvitation as userState.

Example request

curl "https://$instanceId.id.nevis.cloud/nevis/api/v1/users?limit=10" \
  --header "Authorization: Bearer $accessKey"

HTTP response

On success

HTTP/1.1 200 is returned on success.

Parameter	Type	Description
items	array of users	The collection of users
_pagination	object	The pagination object. For more information, see Token-based pagination.

Example response

{
    "items": [
        {
            "loginId": "[email protected]",
            "address": {
                "dwellingNumber": "31",
                "city": "Budapest",
                "street": "Corvin sétány",
                "countryCode": "hu",
                "postalCode": "1082",
                "postOfficeBoxText": "133",
                "houseNumber": "1/b",
                "locality": "Corvin-negyed",
                "addressline2": "Main building",
                "addressline1": "Corvin sétány 1/b 1/1",
                "postOfficeBoxNumber": 9
            },
            "gender": "other",
            "modificationComment": "simply created modification",
            "created": "2021-10-15T07:54:12Z",
            "languageCode": "en",
            "version": 1,
            "birthDate": "2000-01-01T00:00:01Z",
            "userState": "active",
            "name": {
                "firstName": "Alexander",
                "lastName": "Nagy",
                "title": "Dr."
            },
            "lastModified": "2021-10-15T07:54:12Z",
            "userId": "4a5e7346-488b-46f9-914f-79ddb1131e0b",
            "contacts": {
                "telephone": "+3611234567",
                "telefax": "+441619998888"
            },
            "remarks": "my first user!",
            "properties": {
                "preferredContactChannel": "email"
            }
        },
        {
            "loginId": "[email protected]",
            "address": {
                "dwellingNumber": "32",
                "city": "Budapest",
                "street": "Corvin sétány",
                "countryCode": "hu",
                "postalCode": "1082",
                "postOfficeBoxText": "134",
                "houseNumber": "1/b",
                "locality": "Corvin-negyed",
                "addressline2": "Main building",
                "addressline1": "Corvin sétány 1/b 1/2",
                "postOfficeBoxNumber": 10
            },
            "gender": "male",
            "modificationComment": "simply created modification",
            "created": "2021-10-15T07:54:13Z",
            "languageCode": "en",
            "version": 1,
            "birthDate": "2001-01-02T00:00:01Z",
            "userState": "active",
            "name": {
                "firstName": "Attila",
                "lastName": "Black",
                "title": "Mr."
            },
            "lastModified": "2021-10-15T07:54:13Z",
            "userId": "4a5e7346-488b-46f9-914f-79ddb1131e0b",
            "contacts": {
                "telephone": "+3611234567",
                "telefax": "+441619998888"
            },
            "remarks": "my second user!",
            "properties": {
                "preferredContactChannel": "phone"
            }
        }
    ],
    "_pagination": {
        "continuationToken": "1639467743000_a721ec6d-dcbf-4bcf-ac15-8ba7bba4135b",
        "limit": 1000
    }
}

note

properties in the response item body, properties map custom attributes of a user. If a custom attribute value is empty, it will be simply omitted. Custom attribute definitions are requested as a white glove service in Identity Cloud by an administrator.

On failure

HTTP/1.1 401 is returned if the authorization fails due to an invalid access key.

HTTP/1.1 422 is returned if invalid query parameters are given.

HTTP/1.1 500 is returned if an unexpected error occurs.