Help Center/ IAM Identity Center/ API Reference/ API/ User Management/ Querying Details About Specified Users in Batches

Updated on 2025-08-21 GMT+08:00

View PDF

Querying Details About Specified Users in Batches

Function

This API is used to query details about specified users in batches. It can be called only from the organization's management account or from a delegated administrator account of a cloud service.

URI

POST /v1/identity-stores/{identity_store_id}/users/batch-query

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
identity_store_id	Yes	String	Globally unique ID of an identity source.

Request Parameters

**Table 2** Parameters in the request header
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	Security token (session token) of your temporary security credentials. If a temporary security credential is used, this header is required.

**Table 3** Parameters in the request body
Parameter	Mandatory	Type	Description
user_ids	Yes	Array of strings	List of unique user IDs.

Response Parameters

Status code: 200

**Table 4** Parameters in the response body
Parameter	Type	Description
users	Array of DescribeUserResp objects	List of user details.

**Table 5** DescribeUserResp
Parameter	Type	Description
addresses	Array of AddressDto objects	List of user addresses.
display_name	String	Display name of a user.
emails	Array of EmailDto objects	Email address list of a user.
external_id	String	Identifier assigned by an external identity source to a resource.
external_ids	Array of ExternalIdDto objects	External ID list of a user.
identity_store_id	String	Globally unique ID of an identity source.
locale	String	Geographical area or location of a user.
name	NameDto object	User's name.
nickname	String	Nickname of a user.
phone_numbers	Array of PhoneNumberDto objects	Phone number list of a user.
preferred_language	String	User's preferred language.
profile_url	String	URL associated with a user.
timezone	String	User time zone.
title	String	User title.
user_id	String	Globally unique ID of an IAM Identity Center user in the identity source.
user_name	String	Username, which uniquely identifies a user.
user_type	String	User type.
created_at	Long	Timestamp when a user is created.
created_by	String	Creator.
updated_at	Long	Timestamp when a user is updated.
updated_by	String	Updater.
email_verified	Boolean	Boolean value, indicating whether the email address of a user is verified.
enabled	Boolean	Boolean value, indicating whether a user is enabled.
enterprise	EnterpriseDto object	User work information.

**Table 6** AddressDto
Parameter	Type	Description
country	String	Country or region.
formatted	String	Formatted address to be displayed.
locality	String	Location.
postal_code	String	Postal code.
primary	Boolean	Boolean value, indicating whether this is a user's primary address.
region	String	Region.
street_address	String	Street.
type	String	Address type.

**Table 7** EmailDto
Parameter	Type	Description
primary	Boolean	Boolean value, indicating whether this is a user's primary email address.
type	String	Email address type.
value	String	Email address.
verification_status	String	Verification status of an email address.

**Table 8** ExternalIdDto
Parameter	Type	Description
id	String	Resource ID issued by an external identity provider.
issuer	String	Issuer of an external ID.

**Table 9** NameDto
Parameter	Type	Description
family_name	String	Family name of a user.
formatted	String	Formatted name to be displayed.
given_name	String	Given name of a user.
honorific_prefix	String	Prefix of a user's name.
honorific_suffix	String	Suffix of a user's name.
middle_name	String	Middle name of a user.

**Table 10** PhoneNumberDto
Parameter	Type	Description
primary	Boolean	Boolean value, indicating whether this is a user's primary phone number.
type	String	Phone number type.
value	String	Phone number.

**Table 11** EnterpriseDto
Parameter	Type	Description
cost_center	String	Cost Center.
department	String	Department.
division	String	Division.
employee_number	String	Employee ID.
manager	ManagerDto object	Manager.
organization	String	Organization.

**Table 12** ManagerDto
Parameter	Type	Description
value	String	Manager information.

Status code: 400

**Table 13** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Unique ID of a request.

Status code: 403

**Table 14** Parameters in the response body
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.
request_id	String	Unique ID of a request.
encoded_authorization_message	String	Encrypted error message.

Example Request

Querying details about specified users in batches

POST https://{hostname}/v1/identity-stores/{identity_store_id}/users/batch-query

{
  "user_ids" : [ "c59a3e4f-2cb2-4649-9874-3880664xxx" ]
}

Example Response

Status code: 200

Successful

{
  "users" : [ {
    "addresses" : [ {
      "country" : "country",
      "formatted" : "formatted",
      "locality" : "locality",
      "postal_code" : "postalCode",
      "primary" : false,
      "region" : "region",
      "street_address" : "streetAddress",
      "type" : "work"
    } ],
    "display_name" : "displayNamexxx",
    "emails" : [ {
      "primary" : true,
      "type" : "work",
      "value" : "xx@xx.com",
      "verification_status" : "NOT_VERIFIED"
    } ],
    "external_id" : "nickName",
    "external_ids" : [ {
      "id" : "nickName"
    } ],
    "identity_store_id" : "d-a23adaabca",
    "name" : {
      "family_name" : "familyNamedhf",
      "formatted" : "givenNameupdategfgdhf familyNamedhf",
      "given_name" : "givenNameupdategfgdhf"
    },
    "phone_numbers" : [ {
      "primary" : true,
      "type" : "work",
      "value" : "100845277237"
    } ],
    "title" : "title",
    "user_id" : "c59a3e4f-2cb2-4649-9874-38xxxx",
    "user_name" : "your name",
    "created_at" : 1753794283870,
    "created_by" : "SCIM/87905e14-e3ab-43dd-8a48-xxxx",
    "updated_at" : 1753794283878,
    "updated_by" : "SCIM/87905e14-e3ab-43dd-8a48-xxx",
    "email_verified" : false,
    "enabled" : true,
    "enterprise" : {
      "department" : "department",
      "employee_number" : "employeeNumber"
    }
  } ]
}