¶ Get/search user list

Update time: 2025-07-23 07:34:21

This document is automatically generated based on https://github.com/authing/authing-docs-factory and https://api-explorer.genauth.ai V3 API, and is consistent with API parameters and return results. If this document description is incorrect, please refer to V3 API.

This interface is used to obtain user lists, supports fuzzy search, and filters users by user basic fields, user custom fields, user department, user history login application and other dimensions.

¶ Fuzzy search example

Fuzzy search will perform fuzzy search on users from five fields: phone, email, name, username, nickname by default. You can also set options.fuzzySearchOn to determine the scope of the fuzzy matching fields:

{
  "keywords": "xx",
  "options": {
    "fuzzySearchOn": ["address"]
  }
}

¶ Advanced search example

You can use advancedFilter to perform advanced search. Advanced search supports filtering users by user basic information, custom data, department, user source, login application, external identity source information, etc. **These filtering conditions can be combined arbitrarily. **

¶ Filter users with disabled status

User status (status) is a string type, and the optional values are Activated and Suspended:

{
  "advancedFilter": [
    {
      "field": "status",
      "operator": "EQUAL",
      "value": "Suspended"
    }
  ]
}

¶ Filter users whose mailboxes contain `@example.com`

User mailboxes (email) are string types and can be fuzzy searched:

{
  "advancedFilter": [
    {
      "field": "email",
      "operator": "CONTAINS",
      "value": "@example.com"
    }
  ]
}

¶ Search based on any extended fields of the user

{
  "advancedFilter": [
    {
      "field": "some-custom-key",
      "operator": "EQUAL",
      "value": "some-value"
    }
  ]
}

¶ Filter by number of user logins

Filter users with more than 10 logins:

{
  "advancedFilter": [
    {
      "field": "loginsCount",
      "operator": "GREATER",
      "value": 10
    }
  ]
}

Filter users with 10 to 100 login times:

{
  "advancedFilter": [
    {
      "field": "loginsCount",
      "operator": "BETWEEN",
      "value": [10, 100]
    }
  ]
}

Filter users who have logged in within the last 7 days:

{
  "advancedFilter": [
    {
      "field": "lastLoginTime",
      "operator": "GREATER",
      "value": new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
    }
  ]
}

Filter users who have logged in within a certain period of time:

{
  "advancedFilter": [
    {
      "field": "lastLogin",
      "operator": "BETWEEN",
      "value": [
        Date.now() - 14 * 24 * 60 * 60 * 1000,
        Date.now() - 7 * 24 * 60 * 60 * 1000
      ]
    }
  ]
}

¶ Filter based on the applications that the user has logged in

Filter users who have logged in to applications appId1 or appId2:

{
  "advancedFilter": [
    {
      "field": "loggedInApps",
      "operator": "IN",
      "value": ["appId1", "appId2"]
    }
  ]
}

¶ Filter by user's department

{
  "advancedFilter": [
    {
      "field": "department",
      "operator": "IN",
      "value": [
        {
          "organizationCode": "steamory",
          "departmentId": "root",
          "departmentIdType": "department_id",
          "includeChildrenDepartments": true
        }
      ]
    }
  ]
}

¶ Method Name

ManagementClient.listUsers

¶ Request Parameters

Name	Type	Is it required	Default Value	Description	Example Value
keywords	string	No	-	Fuzzy search keywords	`Zhang San`
advancedFilter	ListUsersAdvancedFilterItemDto[]	No	-	Advanced search	`[{"field":"status","operator":"EQUAL","value":"Activated"}]`
searchQuery	object	No	-	Use ES query statements to execute search commands	`{"query":{"bool":{"must":[{"term":{"phone":"18818888888"}}],"must_not":[]}},"sort":["_score",{"created_at":"ASC"}]}`
options	ListUsersOptionsDto	No	-	Optional	`{"pagination":{"page":1,"limit":10},"fuzzySearchOn":["phone","email","name","username","nickname","identityNumber"],"withCustomData":true,"withIdentities":true,"withDepartmentIds":true}`

¶ Sample Code

package test.management;

import cn.authing.sdk.java.client.ManagementClient;
import cn.authing.sdk.java.dto.ListUsersRequestDto;
import cn.authing.sdk.java.dto.UserPaginatedRespDto;
import cn.authing.sdk.java.model.ManagementClientOptions;
import cn.authing.sdk.java.util.JsonUtils;

public class ListUsersTest {
    // Need to be replaced with your GenAuth Access Key ID
    private static final String ACCESS_KEY_ID = "AUTHING_ACCESS_KEY_ID";
    // Need to be replaced with your GenAuth Access Key Secret
    private static final String ACCESS_KEY_SECRET = "AUTHING_ACCESS_KEY_SECRET";

    public static void main(String[] args) throws Throwable {
        ManagementClientOptions clientOptions = new ManagementClientOptions();
        clientOptions.setAccessKeyId(ACCESS_KEY_ID);
        clientOptions.setAccessKeySecret(ACCESS_KEY_SECRET);
        // If you are a private deployment customer, you need to set the GenAuth service domain name
        // clientOptions.setHost("https://api.your-authing-service.com");

        ManagementClient client = new ManagementClient(clientOptions);

        UserPaginatedRespDto response = client.listUsers(new ListUsersRequestDto());
        System.out.println(JsonUtils.serialize(response));
    }
}

¶ Request Response

Type： UserPaginatedRespDto

Name	Type	Description
statusCode	number	Business status code. You can use this status code to determine whether the operation is successful. 200 means success.
message	string	Description
apiCode	number	Segment error code, through which the specific error type can be obtained (not returned for successful requests). For a detailed list of error codes, see：API Code List (opens new window)
requestId	string	Request ID. Returned when the request fails.
data	UserPagingDto	Response data

Example Results：

{
  "statusCode": 200,
  "message": "Operation successful",
  "requestId": "934108e5-9fbf-4d24-8da1-c330328abd6c",
  "data": {
    "list": {
      "userId": "6229ffaxxxxxxxxcade3e3d9",
      "createdAt": "2022-07-03T03:20:30.000Z",
      "updatedAt": "2022-07-03T03:20:30.000Z",
      "status": "Activated",
      "workStatus": "Active",
      "externalId": "10010",
      "email": "test@example.com",
      "phone": "188xxxx8888",
      "phoneCountryCode": "+86",
      "username": "bob",
      "name": "Zhang San",
      "nickname": "Zhang San",
      "photo": "https://files.authing.co/authing-console/default-user-avatar.png",
      "loginsCount": 3,
      "lastLogin": "2022-07-03T03:20:30.000Z",
      "lastIp": "127.0.0.1",
      "gender": "M",
      "emailVerified": true,
      "phoneVerified": true,
      "passwordLastSetAt": "2022-07-03T03:20:30.000Z",
      "birthdate": "2022-06-03",
      "country": "CN",
      "province": "BJ",
      "city": "BJ",
      "address": "Beijing Chaoyang",
      "streetAddress": "xx Street, Chaoyang District, Beijing",
      "postalCode": "438100",
      "company": "steamory",
      "browser": "Mozilla/5.0 (Linux; Android 10; V2001A; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/87.0.4280.141 Mobile Safari/537.36 VivoBrowser/10.2.10.0",
      "device": "iOS",
      "givenName": "San",
      "familyName": "Zhang",
      "middleName": "James",
      "profile": "alice",
      "preferredUsername": "alice",
      "website": "https://my-website.com",
      "zoneinfo": "GMT-08:00",
      "locale": "af",
      "formatted": "132, My Street, Kingston, New York 12401.",
      "region": "Xinjiang Uyghur Autonomous Region",
      "userSourceType": "register",
      "passwordSecurityLevel": 1,
      "departmentIds": "[\"624d930c3xxxx5c08dd4986e\",\"624d93102xxxx012f33cd2fe\"]",
      "identities": {
        "identityId": "62299d8b866d2dab79a89dc4",
        "extIdpId": "6076bacxxxxxxxxd80d993b5",
        "provider": "wechat",
        "type": "openid",
        "userIdInIdp": "oj7Nq05R-RRaqak0_YlMLnnIwsvg",
        "accessToken": "57_fK0xgSL_NwVlS-gmUwlMQ2N6AONNIOAYxxxx",
        "refreshToken": "57_IZFu91Ak1Wg6DRytZFFIOd3upNF5lH7vPxxxxx",
        "originConnIds": "[\"605492ac41xxxxe0362f0707\"]"
      },
      "identityNumber": "420421xxxxxxxx1234",
      "customData": {
        "school": "Beijing University",
        "age": 22
      },
      "statusChangedAt": "2022-07-03T03:20:30.000Z"
    }
  }
}

¶ Data Structure

¶ ListUsersAdvancedFilterItemDto

Name	Type	Is it required	Description	Example Value
field	string	Yes	User fields specified for advanced search: - `id`: User ID - `phone`: Phone number - `email`: Email address - `username`: User name - `externalId`: User ID in the external system - `name`: Name - `status`: User status, optional values are `Activated` and `Suspended` - `gender`: User gender, optional values are `M` (male), `F` (female) and `U` (unknown) - `birthdate`: Date of Birth - `givenName`: First Name - `familyName`: Last Name - `preferredUsername`: Preferred Username - `profile`: Profile - `country`: Country - `province`: Province - `zoneinfo`: Time Zone - `website`: Personal website - `address`: address - `streetAddress`: street address - `company`: company - `postalCode`: postal code - `formatted`: formatted address - `signedUp`: registration time - `locale`: language information - `lastLogin`: last login time, as timestamp type - `loginsCount`: number of logins, as numeric type - `lastLoginApp`: last logged in application ID - `userSource`: user source, see the example for specific usage - `department`: user department, see the example for specific usage - `loggedInApps`: applications that have been logged in, see the example for specific usage - `identity`: user external identity source information, see the example for specific usage - ... Other custom fields	`nickname`
operator	string	Yes	Operator, optional values are: - `EQUAL`: all equal, applicable to all equal matching of numbers and strings - `NOT_EQUAL`: not equal, applicable to matching of numbers and strings - `CONTAINS`: string contains - `NOT_CONTAINS`: string does not contain - `IS_NULL`: empty - `NOT_NULL`: not empty - `IN`: an element in an array - `GREATER`: greater than or equal to, applicable to comparison of numbers and date type data - `LESSER`: less than or equal to, applicable to comparison of numbers and date type data - `BETWEEN`: between something, applicable to comparison of numbers and date type data	EQUAL
value	object	No	Search value, different `field` may correspond to different `value` types, see the example for detail.	`test`

¶ ListUsersOptionsDto

Name	Type	Is it required	Description	Example Value
pagination	No	Pagination configuration Nested Type: PaginationDto.	`{"page":1,"limit":10}`
sort	array	No	Sorting settings, you can set multiple items to be sorted according to multiple fields Nested Type: SortingDto.	`[{"field":"createdAt","direction":"desc"},{"field":"loginsCount","direction":"desc"}]`
fuzzySearchOn	array	No	User fields for fuzzy search matching, optional values are: - `phone`: User phone number, cannot contain phone number area code, included by default - `email`: User email address, included by default - `name`: User Name, included by default - `username`: User name, included by default - `nickname`: User nickname, included by default - `id`: User ID - `company`: Company - `givenName`: First name - `familyName`: Last name - `middleName`: Middle name - `preferredUsername`: Preferred Username - `profile`: Personal profile - `website`: Personal website - `address`: address - `formatted`: formatted address - `streetAddress`: street address - `postalCode`: postal code
withCustomData	boolean	No	Yes No Get custom data	`true`
withPost	boolean	No	Yes No Get department information	`true`
withIdentities	boolean	No	Yes No Get identities	`true`
withDepartmentIds	boolean	No	Yes No Get department ID list	`true`
flatCustomData	boolean	No	Yes No Flatten extension fields

¶ PaginationDto

Name	Type	Is it required	Description	Example Value
page	number	No	Current page number, starting from 1	`1`
limit	number	No	The maximum number of pages per page cannot exceed 50, and the default value is 10	`10`

¶ SortingDto

Name	Type	Is it required	Description	Example Value
field	string	Yes	The field to be sorted. Optional values are: - `createdAt`: creation time - `updatedAt`: modification time - `email`: email address - `phone`: phone number - `username`: username - `externalId`: external ID - `status`: public account status - `statusChangedAt`: status change time - `passwordLastSetAt`: password change time - `loginsCount`: number of logins - `gender`: gender - `lastLogin`: last login time - `userSourceType`: public account registration source - `lastMfaTime`: last MFA authentication time - `passwordSecurityLevel`: password security level - `phoneCountryCode`: mobile area code - `lastIp`: The IP used for the last login	createdAt
order	string	Yes	Sorting order: - `desc`: Sort by descending order from largest to smallest. - `asc`: Sort by ascending order from smallest to largest.	desc

¶ UserPagingDto

Name	Type	Is it required	Description	Example Value
totalCount	number	Yes	Total number of records
list	array	Yes	Data List Nested Type：UserDto。

¶ UserDto

Name	Type	Is it required	Description	Example Value
userId	string	Yes	The unique identifier of the user, which can be user ID, user name, email, phone number, externalId, or ID in an external identity source. For details, see the description of the userIdType field. The default is user id.	`6229ffaxxxxxxxxcade3e3d9`
createdAt	string	yes	creation time	`2022-07-03T03:20:30.000Z`
updatedAt	string	yes	update time	`2022-07-03T03:20:30.000Z`
status	string	yes	current status of the account: - Activated: normal status - Suspended: deactivated - Deactivated: disabled - Resigned: resigned - Archived: archived	Suspended
workStatus	string	yes	current work status of the account	Closed
externalId	string	no	third-party external ID	`10010`
email	string	no	email address, case insensitive	`test@example.com`
phone	string	No	Phone number without area code. If it is a foreign phone number, specify the area code in the phoneCountryCode parameter.	`188xxxx8888`
phoneCountryCode	string	No	Mobile phone area code. This field is optional for mainland China mobile phone numbers. The GenAuth SMS service does not yet support international mobile phone numbers. You need to configure the corresponding international SMS service in the GenAuth console. For a complete list of mobile phone area codes, please refer to https://en.wikipedia.org/wiki/List_of_country_calling_codes.	`+86`
username	string	No	Username, unique in the user pool	`bob`
name	string	No	User's real name, not unique	`Zhang San`
nickname	string	No	Nickname	`Zhang San`
photo	string	No	Avatar link	`https://files.authing.co/authing-console/default-user-avatar.png`
loginsCount	number	No	Total number of historical logins	`3`
lastLogin	string	No	Last login time	`2022-07-03T03:20:30.000Z`
lastIp	string	No	Last login IP	`127.0.0.1`
gender	string	Yes	Gender: - `M`: Male, `male` - `F`: Female, `female` - `U`: unknown, `unknown`	M
emailVerified	boolean	yes	Email verified	`true`
phoneVerified	boolean	yes	Phone number verified	`true`
passwordLastSetAt	string	no	User's last password change time	`2022-07-03T03:20:30.000Z`
birthdate	string	No	Date of birth	`2022-06-03`
country	string	No	Country	`CN`
province	string	No	Province	`BJ`
city	string	No	City	`BJ`
address	string	No	Address	`Beijing Chaoyang`
streetAddress	string	No	Street address	`Beijing Chaoyang District xxx Street`
postalCode	string	No	Postal code	`438100`
company	string	No	Company	`steamory`
browser	string	No	Last browser used for login UA	`Mozilla/5.0 (Linux; Android 10; V2001A; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/87.0.4280.141 Mobile Safari/537.36 VivoBrowser/10.2.10.0`
device	string	No	The device used when logging in last time	`iOS`
givenName	string	no	first name	`xxx`
familyName	string	no	last name	`xxx`
middleName	string	no	middle name	`James`
profile	string	no	Preferred Username	`alice`
preferredUsername	string	no	Preferred Username	`alice`
website	string	no	User personal website	`https://my-website.com`
zoneinfo	string	no	User time zone information	`GMT-08:00`
locale	string	no	Locale	`af`
formatted	string	no	Full standard address	`132, My Street, Kingston, New York 12401.`
region	string	no	User location	`Xinjiang Uyghur Autonomous Region`
userSourceType	string	yes	Source type: - `excel`: via excel Import - `register`: User self-registration - `adminCreated`: Manual creation by the administrator (including creating users using the management API) - `syncTask`: Sync task in the sync center	excel
userSourceId	string	No	Application ID or sync task ID
lastLoginApp	string	No	ID of the application that the user last logged in to
mainDepartmentId	string	No	ID of the user's main department
lastMfaTime	string	No	Time when the user last performed MFA authentication
passwordSecurityLevel	number	No	User password security strength level	`1`
resetPasswordOnNextLogin	boolean	No	Require password reset on next login
registerSource	array	No	Registration method
departmentIds	array	No	List of department IDs to which the user belongs	`["624d930c3xxxx5c08dd4986e","624d93102xxxx012f33cd2fe"]`
identities	array	No	External identity source nested Type: IdentityDto.
identityNumber	string	No	User ID number	`420421xxxxxxxx1234`
customData	object	No	User's extended field data	`{"school":"Beijing University","age":22}`
postIdList	array	No	User-associated department ID
statusChangedAt	string	No	User status last modified time	`2022-07-03T03:20:30.000Z`
tenantId	string	No	User tenant ID

¶ IdentityDto

Name	Type	Is it required	Description	Example Value
identityId	string	Yes	Identity source ID	`62299d8b866d2dab79a89dc4`
extIdpId	string	Yes	Identity source connection ID	`6076bacxxxxxxxxd80d993b5`
provider	string	Yes	External identity source Type: - `wechat`: WeChat - `qq`: QQ - `wechatwork`: WeChat for Business - `dingtalk`: DingTalk - `weibo`: Weibo - `github`: GitHub - `alipay`: Alipay - `baidu`: Baidu - `lark`: Feishu - `welink`: Welink - `yidun`: NetEase Yidun - `qingcloud`: Qingyun - `google`: Google - `gitlab`: GitLab - `gitee`: Gitee - `twitter`: Twitter - `facebook`: Facebook - `slack`: Slack - `linkedin`: Linkedin - `instagram`: Instagram - `oidc`: OIDC-type enterprise identity source - `oauth2`: OAuth2-type enterprise identity source - `saml`: SAML-type enterprise identity source - `ldap`: LDAP-type enterprise identity source - `ad`: AD-type enterprise identity source - `cas`: CAS-type enterprise identity source - `azure-ad`: Azure AD-type enterprise identity source	oidc
type	string	Yes	Identity type, such as unionid, openid, primary	`openid`
userIdInIdp	string	Yes	ID in the external identity source	`oj7Nq05R-RRaqak0_YlMLnnIwsvg`
userInfoInIdp	object	Yes	User's identity information in idp
accessToken	string	No	Access Token in the external identity source (this parameter is only returned when the user actively obtains it, and the management side interface will not return it).	`57_fK0xgSL_NwVlS-gmUwlMQ2N6AONNIOAYxxxx`
refreshToken	string	No	Refresh Token in the external identity source (this parameter is only returned when the user actively obtains it, and the management side interface will not return it).	`57_IZFu91Ak1Wg6DRytZFFIOd3upNF5lH7vPxxxxx`
originConnIds	array	Yes	List of identity origin connection IDs that the identity comes from	`["605492ac41xxxxe0362f0707"]`

Previous article: Events Next article: Get user information