Cloud Administration User Search APICloud Administration User Search API
Use the Cloud Administration User Search API to find a user by searching for a string in the user's email address.
AuthenticationAuthentication
Clients calling this API to search for a user must authenticate themselves by including a JSON Web Token in a request. For instructions on using this token, see Authentication for the Cloud Administration REST APIs.
Administrative RolesAdministrative Roles
This API can use an API key that is associated with either the Super Administrator or Help Desk Administrator role. For more information, see Manage the Cloud Administration REST API Keys.
Software Developer KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Request RequirementsRequest Requirements
Use the following information to search for a particular user.
Method | Request URL | Response Content Type | Response Body | Response Codes |
---|---|---|---|---|
POST |
/AdminInterface/restapi/v1/users/search |
application/json | List of user details with matching email address | 200, 400, 403, 500 |
Resource IdentifierResource Identifier
The following resource identifier is optional.
Resource Identifier | Required | Description | Type |
---|---|---|---|
<pageSize> | No | Specifies the maximum number of matching results to return. Valid values are 1 to 25, inclusive. The default value is 25. | Integer |
Example Request DataExample Request Data
The following example displays a user search request.
POST /AdminInterface/restapi/v1/users/search?pageSize=20
Accept: application/json
Authorization: Bearer <JWT token>
Example Request BodyExample Request Body
The following example displays a user search request.
{
"emailLike": "j.doe"
}
Request Body ParametersRequest Body Parameters
The following table describes the emailLike request parameter.
Request Parameter | Required | Description | Type |
---|---|---|---|
emailLike | Yes | The user's email address must contain the literal string passed in this parameter. Do not use wildcards. | String |
ResponseResponse
The API returns an array of matching user data in JSON format, sorted in ascending alphabetical order according to the user email addresses.
The API can find exact and partial matches. The exact match is returned first in the list of results. The remaining results are sorted in ascending order according to the user email addresses.
If no matches are found, an empty body is returned.
Example Response BodyExample Response Body
The following example displays a response body.
{
"id": "f85b6e95-f41f-45b4-bc84-559fead6460c",
"emailAddress": "j.doe1@mycompany.com",
"firstName": "Jane",
"lastName": "Doe",
"creationDate": "2018-08-31T19:10:30.045Z",
"identitySource": "My Company AD",
"userStatus": "Enabled",
"markDeleted": false,
"highRiskUser": false,
"markDeletedAt": null,
"markDeletedBy": null,
"smsNumber": "+11235556799",
"voiceNumber": "+17815551235",
"isTokenLocked": false,
"isSmsLocked": false,
"isVoiceLocked": false,
"lastSyncTime": "2018-08-31T19:20:30.045Z",
"monthLastAuthenticated": null",
},
{
"id": "f85b6e95-f41f-45b4-bc84-559fead6460c",
"emailAddress": "j.doe2@mycompany.com",
"firstName": "John",
"lastName": "Doe",
"creationDate": "2018-08-31T19:10:30.045Z",
"identitySource": "My Company AD",
"userStatus": "Enabled",
"markDeleted": false,
"highRiskUser": false,
"markDeletedAt": null,
"markDeletedBy": null,
"smsNumber": "+17815552234",
"voiceNumber": "+17815552235",
"isTokenLocked": false,
"isSmsLocked": false,
"isVoiceLocked": false,
"lastSyncTime": "2018-08-31T19:20:30.045Z"
"emergencyAccessStatus":"Enabled",
"emergencyTokencodeId":"007c4e8d-7450-4293-be46-16454a78a217",
"emergencyTokencodeExpiration":"2019-08-21T15:02:45.000Z",
"emergencyTokencodeLastUse": null
"offlineEmergencyTokencodeExpiration":"2019-08-21T15:02:45.000Z",
"offlineEmergencyAccessStatus":"Enabled",
"monthLastAuthenticated": Nov 2020",
}
},
Response Property DescriptionsResponse Property Descriptions
The following table describes properties used in the response.
Property | Description | Data Type |
---|---|---|
id | Identifies the user. | String |
emailAddress | User's email address. | String |
firstName | User's first name. | String |
lastName | User's last name. | String |
creationDate | Date when the user account was added to the Cloud Authentication Service. See https://www.w3.org/TR/NOTE-datetime for information on formatting timestamps in ISO 8601 format. |
String |
identitySource | Name of identity source. | String |
userStatus |
Enabled. Users can access protected resources. Disabled. Users cannot access protected resources or register devices. |
String |
markDeleted | Indicates whether the user is marked deleted. | Boolean |
markDeletedAt |
Date when a user is marked deleted. |
String |
markDeletedBy | Administrator who initiated mark for delete. | String |
smsNumber | Displays user SMS Tokencode phone numbers after you click Show synchronized phone numbers. Phone numbers appear only if corresponding attributes were configured and synchronized. | String |
voiceNumber | Displays user Voice Tokencode phone numbers after you click Show synchronized phone numbers. Phone numbers appear only if corresponding attributes were configured and synchronized. | String |
isTokenLocked | Tokencode status is true (locked) or false (unlocked). | Boolean |
isSmsLocked | SMS Tokencode status is true (locked) or false (unlocked). | Boolean |
isVoiceLocked |
Voice Tokencode status is true (locked) or false (unlocked). |
Boolean |
lastSyncTime |
Most recent time when user details were synchronized with an identity source. |
String |
highRiskUser |
True indicates the user is marked as high risk by an external third-party application. False indicates the user is not marked as high risk by an external third-party application. |
Boolean |
emergencyAccessStatus |
Enabled - An Emergency Tokencode has been generated for this user. Disabled - An Emergency Tokencode has not been generated for this user. Locked - Emergency Tokencode is locked for this user. |
String |
emergencyTokencodeId | Identifies the Emergency Tokencode, if one has been generated for this user. | String |
emergencyTokencodeExpiration | Emergency Tokencode expiration date. | String |
emergencyTokencodeLastUse | Emergency Tokencode last used date. | String |
offlineEmergencyTokencodeExpiration | Offline Emergency Tokencode expiration date. | String |
offlineEmergencyAccessStatus |
Enabled - An offline Emergency Tokencode has been generated for this user. Disabled - An offline Emergency Tokencode has not been generated for this user. |
String |
monthLastAuthenticated | Month the user last authenticated. Returns null if not applicable, or a date in MMM/YYYY format. | String |
Response CodesResponse Codes
The following table shows response codes for this API.
Code | Description |
---|---|
200 | Search completed successfully. |
400 | Operation not performed because of client syntax errors. |
403 | Not authorized to perform the request. |
429 | Too many requests. |
500 |
Internal error occurred when processing the request. |