Search users - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

This web service makes it possible to search for one or more users based on criteria such as display name, email address, role, group, and realm.

Method Endpoint
POST /api/users/search

It is possible to use pagination with this web service.

Request example

The following lines show an example of a JSON request body:

{
  "userTextSearch": "john",
  "realm": "internal",
  "group": "string",
  "role": "KHUB_ADMIN",
  "sort": { 
        "criterion": "LAST_ACTIVITY_DATE",
        "order":"DESC"
    },
  "paging": {
        "page": 1,
        "perPage": 30               
    }
}
Field Type Required? Description
userTextSearch String No Expects information such as a user's display name, their email address, user*, *, etc.
realm String No Expects one of the realms configured for the tenant.
group String No Expects one of the user groups configured for the tenant.
role String No Expects one of the Fluid Topics user roles.
sort Object No Sorts results. Expects the criterion and order parameters.
    criterion String No Expects one of the following values: NAME, REALM, CREATION_DATE, or LAST_ACTIVITY_DATE. If undefined, the default value is NAME.
    order String No Expects one of the following values: ASC or DESC. If undefined, the default value is ASC.
paging Object No Information about paging. Expects the page and perPage parameters.
    page Number No Defines the page number. If undefined, the default value is 1.
    perPage Number No Defines the number of results to display per page. If undefined, the default value is 20.

Defining more than one role, group, or realm at a time in the request body returns an HTTP 400 error.

Return code Description
200 OK The request is valid and data is returned.
400 BAD REQUEST The request is invalid or the requested realm or user role does not exist.
401 UNAUTHORIZED The authorization header was not provided or is invalid.
403 FORBIDDEN The user or API key does not have the ADMIN or USERS_ADMIN role.

For a comprehensive list of all possible return codes, see Return codes.

Response body

The following lines show an example of a JSON response body:

{
  "results": [
    {
      "userId": "a43eb18a-3f48-4732-9389-61b540ce9d0d",
      "displayName": "A User",
      "emailAddress": "user@example.com",
      "creationDate": "2022-10-26T08:55:19.746+00:00",
      "lastActivityDate": "2022-10-26T08:55:19.756+00:00",
      "realm": "oidc",
      "groups": [
        "group-a", 
        "group-b"
      ],
      "roles": [
        "BETA_USER", 
        "USERS_ADMIN"
      ],
      "locked": false
    },
    ...
  ],
    "paging": {
        "currentPage": 1,
        "perPage": 30,
        "totalCount": 200
    }
}
Field Type Description
results Array A list of results.
    userId String The user's identifier.
    displayName String The user's name as it appears in the portal.
    emailAddress String The user's email address.
    creationDate String The date and time when the user was created.
    lastActivityDate String The date and time of the user's last activity.
    realm String The realm used to authenticate.
    groups Array The groups to which the user belongs.
    roles Array The roles assigned to the user.
    locked Boolean If the user's account is locked, the value of this parameter is true.
paging Object Information about paging.
    currentPage Number The number of the page of results currently displayed.
    perPage Number The number of results per page.
    totalCount Number The number of matching users when taking all pages into account.

Technically, it is possible to use the Search for users web service to achieve the same goal as the List all users web service by defining an empty payload. However, the Search for users web service is unique in that it makes it possible to filter directly on a specific user or subset of users without having a user ID on hand.