Queries the list of users

GET/v2/users

Queries users in the current organization based on filter expressions and paginates using a cursor.

Filter Criteria

The supported filter fields are email, name, nickname, employeeNo, status, domain, employeeType, delegateType, departmentId, jobTitle, workLocation, homeLocation, info, managerId, and isSharedWithOthers. For example:

• (departmentId=xxx): Queries users directly under the department xxx, excluding sub-departments.
• (departmentId=xxx*): Queries users in the department xxx and its sub-departments.
• (employeeNo=32901): Queries the user whose employee ID equals 32901.
• (|(name=Jack)(email=*jack*)): The name is "Jack", or the email address contains jack.
• (&(employeeType=SERVICE)(email=*abc*)): Service accounts whose email addresses contain abc.
• (&(departmentId=xxx)(!(status=FREEZE))): Users in the department xxx whose status is not frozen.
• (domain=example.com): Users belonging to the subdomain example.com.
• (delegateType=QUARANTINE): Users who have established a quarantine authorization relationship.

Sorting

Supports sorting by email, name, nickname, employeeNo, or createdTime.

Request

Query parameters

filter string

Filter expression.

cursor string

The query cursor. Leave blank to start from the beginning.

size number

Page size, maximum is 100.

orderby string

Sort field. If not specified, sorting is by creation time in descending order.

order enum
Possible values: [ASC, DES]
• ASC:
• DES:
managed boolean

Returns only managed users. This field is only effective for administrator roles.

$select string

Response

users object[]
id string
User ID,
email stringrequired
Specifies the email address to display; must be one of the alias list.
emailAliases string[]
List of email address aliases.
name stringrequired
User name (person name).
nickname string
User nickname (or alias).
employeeNo string
Employee ID.
jobTitle string
Position.
workLocation string
Workplace.
officeLocation string
Workstation.
departmentIds string[]required
List of departments the user belongs to, not the department chain. A user may belong to multiple departments simultaneously.
status enum
Account status (Normal or Frozen only). Only the domain administrator or an authorized application can modify it.
• NORMAL: Normal
• FREEZE: Frozen
Possible values: [NORMAL, FREEZE]
avatar object
Avatar.
url string
Avatar URL.
bgColor string
Background color value when the avatar URL is empty. Example: #0089ff.
freezedTime string<date-time>
Freeze time, readable by administrators or authorized applications (Optional field: returned when the query parameter $select=freezedTime is added to the URL; use commas to separate multiple fields).
managerInfo object
Manager details (Optional field: returned after adding the query parameter $select=managerInfo in the URL. Use commas to separate multiple fields.)
id string
Manager ID.
email string
Supervisor email address.
name string
Name.
nickname string
Nickname.
managerEmail string
Manager email, writable (Optional field: returned when the $select=managerEmail query parameter is added to the URL. Use commas to separate multiple fields).
orderInDepartments object[]
Sort order of the account in different departments. The full set of department sort values must be provided. This field affects the account's sort order in other departments; in general, prefer using the API that sets the sort order for a single department. For example, if an account belongs to departments a, b, and c, and originally only had a sort value for department c, updating this field with sort values for departments a and b will result in the account having only sort values for departments a and b, and the original sort value for department c will be lost. Only accessible to administrators or authorized applications. This field is modifiable (Optional field: returned when the query parameter $select=orderInDepartments is added to the URL; use commas to separate multiple fields).
departmentId string
order string
nextCursor string
hasMore boolean

Errors

401	Access is unauthorized. Please check whether the correct authorization token is passed.
403	No API access permission. Please complete the relevant authorization on the application management page of the domain administrator.