Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

DescribeUsers

Important

Notice: New customer sign-ups and account upgrades are no longer available for Amazon WorkDocs. Learn about migration steps here: How to migrate data from Amazon WorkDocs.

Describes the specified users. You can describe all users or filter the results (for example, by status or organization).

By default, Amazon WorkDocs returns the first 24 active or pending users. If there are more results, the response includes a marker that you can use to request the next set of results.

Request Syntax


GET /api/v1/users?fields=Fields&include=Include&limit=Limit&marker=Marker&order=Order&organizationId=OrganizationId&query=Query&sort=Sort&userIds=UserIds HTTP/1.1
Authentication: AuthenticationToken

URI Request Parameters

The request uses the following URI parameters.

AuthenticationToken

Amazon WorkDocs authentication token. Not required when using AWS administrator credentials to access the API.

Length Constraints: Minimum length of 1. Maximum length of 8199.

Fields

A comma-separated list of values. Specify "STORAGE_METADATA" to include the user storage quota and utilization information.

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [\w,]+

Include

The state of the users. Specify "ALL" to include inactive users.

Valid Values: ALL | ACTIVE_PENDING

Limit

The maximum number of items to return.

Valid Range: Minimum value of 1. Maximum value of 999.

Marker

The marker for the next set of results. (You received this marker from a previous call.)

Length Constraints: Minimum length of 1. Maximum length of 2048.

Order

The order for the results.

Valid Values: ASCENDING | DESCENDING

OrganizationId

The ID of the organization.

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: [&\w+-.@]+

Query

A query to filter users by user name. Remember the following about the Userids and Query parameters:

If you don't use either parameter, the API returns a paginated list of all users on the site.
If you use both parameters, the API ignores the Query parameter.
The Userid parameter only returns the users that match a corresponding user ID.
Use commas to delimit multiple user IDs. For example:

aws workdocs describe-users --region us-west-2 --user-ids 'S-1-5-21-3987873806-3646240316-3418290641-317967&d-9267750cd0,S-1-5-21-3987873806-3646240316-3418290641-317966&d-9267750cd0'
We treat the ID field as a string. We don't limit the number of IDs. The string can be 2000 characters long. Each ID is 59 characters. With the comma delimiter, the caller can supply up to 33 users in one request.
You don't need a delimiter for user-query. For multi-word queries, enclose the query in quotes. For example:

aws workdocs describe-users --region us-west-2 --organization-id d-9267750cd0 --user-query 'First Last'
You can use a maximum of 512 characters in a query. We don't limit the number of query terms as long as the string is less than 512 characters.
The Query parameter runs a "prefix" search for users by the GivenName, SurName, or UserName fields included in a CreateUser API call. For example, querying on Ma returns Márcia Oliveira, María García, and Mateo Jackson. If you use multiple characters, the API only returns data that matches all characters. For example, querying on Ma J only returns Mateo Jackson.

Length Constraints: Minimum length of 1. Maximum length of 512.

Pattern: [\u0020-\uFFFF]+

Sort

The sorting criteria.

Valid Values: USER_NAME | FULL_NAME | STORAGE_LIMIT | USER_STATUS | STORAGE_USED

UserIds

The IDs of the users.

Length Constraints: Minimum length of 1. Maximum length of 2000.

Pattern: [&\w+-.@, ]+

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "Marker": "string",
   "TotalNumberOfUsers": number,
   "Users": [ 
      { 
         "CreatedTimestamp": number,
         "EmailAddress": "string",
         "GivenName": "string",
         "Id": "string",
         "Locale": "string",
         "ModifiedTimestamp": number,
         "OrganizationId": "string",
         "RecycleBinFolderId": "string",
         "RootFolderId": "string",
         "Status": "string",
         "Storage": { 
            "StorageRule": { 
               "StorageAllocatedInBytes": number,
               "StorageType": "string"
            },
            "StorageUtilizedInBytes": number
         },
         "Surname": "string",
         "TimeZoneId": "string",
         "Type": "string",
         "Username": "string"
      }
   ]
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Marker

The marker to use when requesting the next set of results. If there are no additional results, the string is empty.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

TotalNumberOfUsers

This parameter has been deprecated.

The total number of users included in the results.

Type: Long

Users

The users.

Type: Array of User objects

Errors

For information about the errors that are common to all actions, see Common Errors.

EntityNotExistsException

The resource does not exist.

HTTP Status Code: 404

FailedDependencyException

The AWS Directory Service cannot reach an on-premises instance. Or a dependency under the control of the organization is failing, such as a connected Active Directory.

HTTP Status Code: 424

InvalidArgumentException

The pagination marker or limit fields are not valid.

HTTP Status Code: 400

RequestedEntityTooLargeException

The response is too large to return. The request must include a filter to reduce the size of the response.

HTTP Status Code: 413

ServiceUnavailableException

One or more of the dependencies is unavailable.

HTTP Status Code: 503

UnauthorizedOperationException

The operation is not permitted.

HTTP Status Code: 403

UnauthorizedResourceAccessException

The caller does not have access to perform the action on the resource.

HTTP Status Code: 404