Queries users.

Usage notes

This topic provides an example on how to query users in the d-00fc2p61**** directory. The returned result shows that the directory contains two users. The user AliceLee is synchronized from an external identity provider (IdP). The user user1 is manually created within CloudSSO.

Limits

You can call this operation up to 100 times per second per account. This operation is globally limited to 100 times per second across all accounts. If the number of the calls per second exceeds a limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limits when you call this operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes ListUsers

The operation that you want to perform. Set the value to ListUsers.

DirectoryId String Yes d-00fc2p61****

The ID of the directory.

Status String No Enabled

The status of the user. The status can be used to filter users. Valid values:

  • Enabled: The logon of the user is enabled.
  • Disabled: The logon of the user is disabled.
ProvisionType String No Manual

The type of the user. The type can be used to filter users. Valid values:

  • Manual: The user is manually created.
  • Synchronized: The user is synchronized from an external IdP.
Filter String No UserName sw test

The filter condition.

Specify the value in the <Attribute> <Operator> <Value> format. The value is not case-sensitive. You can set <Attribute> only to UserName and Operator only to eq or sw. The value eq indicates Equals, and the value sw indicates Starts With.

For example, if you set Filter to UserName sw test, the operation queries the users whose names start with test. If you set Filter to UserName eq testuser, the operation queries the user whose name is testuser.

MaxResults Integer No 10

The number of entries to return on each page.

Valid values: 1 to 100.

Default value: 10.

NextToken String No K1c3o9K7pFxoTtxH1Nm7MMLb7zrDGvftYBQBPDVv7AD3a8yhRb3Mk8L9ivmN6bFSjfkZNTAg3h4****

The token to return for the next page. If this is your first time to call this operation, you do not need to specify NextToken .

When you call this operation for the first time, if the total number of entries to return exceeds the value of MaxResults, the entries are truncated. Only the entries that match the value of MaxResults are returned, and the excess entries are not returned. In this case, the value of the response parameter IsTruncated is true, and NextToken is returned. In the next call, you can use the value of NextToken and maintain the settings of the other request parameters to query the excess entries. You can repeat the call until the value of IsTruncated becomes false. This way, all entries are returned.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
NextToken String K1c3o9K7pFxoTtxH1Nm7MMLb7zrDGvftYBQBPDVv7AD3a8yhRb3Mk8L9ivmN6bFSjfkZNTAg3h4****

The token that is returned for the next page.

Note This parameter is returned only when the value of IsTruncated is true.
RequestId String 734D9AAC-9A8E-5DF6-A633-ADE70FF2A9B1

The ID of the request.

MaxResults Integer 10

The number of entries returned per page.

TotalCounts Integer 2

The total number of entries returned.

IsTruncated Boolean false

Indicates whether the queried entries are truncated. Valid values:

  • true: The queried entries are truncated.
  • false: The queried entries are not truncated.
Users Array of User

The users.

Status String Enabled

The status of the user. Valid values:

  • Enabled: The logon of the user is enabled.
  • Disabled: The logon of the user is disabled.
UserName String AliceLee@example.onmicrosoft.com

The name of the user.

Email String AliceLee@example.onmicrosoft.com

The email address of the user.

Description String This is a user.

The description of the user.

UserId String u-00bikzkuzbb58luh****

The ID of the user.

FirstName String Alice

The first name of the user.

CreateTime String 2021-06-30T09:20:08Z

The time when the user was created.

ProvisionType String Synchronized

The type of the user. Valid values:

  • Manual: The user is manually created.
  • Synchronized: The user is synchronized from an external IdP.
DisplayName String AliceLee

The display name of the user.

UpdateTime String 2021-06-30T09:20:08Z

The time when the information about the user was modified.

LastName String Lee

The last name of the user.

Examples

Sample requests

https://[Endpoint]/?Action=ListUsers
&DirectoryId=d-00fc2p61****
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<ListUsersResponse>
	<RequestId>734D9AAC-9A8E-5DF6-A633-ADE70FF2A9B1</RequestId>
	<MaxResults>10</MaxResults>
	<TotalCounts>2</TotalCounts>
	<IsTruncated>false</IsTruncated>
	<Users>
		<User>
			<Status>Enabled</Status>
			<UserName>AliceLee@example.onmicrosoft.com</UserName>
			<Email>AliceLee@example.onmicrosoft.com</Email>
			<Description>This is a user.</Description>
			<UserId>u-00bikzkuzbb58luh****</UserId>
			<FirstName>Alice</FirstName>
			<CreateTime>2021-06-30T09:20:08Z</CreateTime>
			<ProvisionType>Synchronized</ProvisionType>
			<DisplayName>AliceLee</DisplayName>
			<UpdateTime>2021-06-30T09:20:08Z</UpdateTime>
			<LastName>Lee</LastName>
		</User>
		<User>
			<Status>Enabled</Status>
			<UserName>user1</UserName>
			<Email></Email>
			<Description></Description>
			<UserId>u-00pkfll14gwm1mb9****</UserId>
			<FirstName></FirstName>
			<CreateTime>2021-07-12T03:11:38Z</CreateTime>
			<ProvisionType>Manual</ProvisionType>
			<DisplayName></DisplayName>
			<UpdateTime>2021-07-12T03:11:38Z</UpdateTime>
			<LastName></LastName>
		</User>
	</Users>
</ListUsersResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "734D9AAC-9A8E-5DF6-A633-ADE70FF2A9B1",
  "MaxResults" : 10,
  "TotalCounts" : 2,
  "IsTruncated" : false,
  "Users" : [ {
    "Status" : "Enabled",
    "UserName" : "AliceLee@example.onmicrosoft.com",
    "Email" : "AliceLee@example.onmicrosoft.com",
    "Description" : "This is a user.",
    "UserId" : "u-00bikzkuzbb58luh****",
    "FirstName" : "Alice",
    "CreateTime" : "2021-06-30T09:20:08Z",
    "ProvisionType" : "Synchronized",
    "DisplayName" : "AliceLee",
    "UpdateTime" : "2021-06-30T09:20:08Z",
    "LastName" : "Lee"
  }, {
    "Status" : "Enabled",
    "UserName" : "user1",
    "Email" : "",
    "Description" : "",
    "UserId" : "u-00pkfll14gwm1mb9****",
    "FirstName" : "",
    "CreateTime" : "2021-07-12T03:11:38Z",
    "ProvisionType" : "Manual",
    "DisplayName" : "",
    "UpdateTime" : "2021-07-12T03:11:38Z",
    "LastName" : ""
  } ]
}

Error codes

For a list of error codes, visit the API Error Center.