List all the users (Paginated and w/ Filter)
GET /users
Operation id: UserService_ListUsers
Description
Permission Level: Read
Tags: UserService
Parameters
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
domain | string | No | domain of the users to list, Required: false |
excludeTenantIds | array | No | List of tenant IDs to exclude. Required: false |
fieldMask | string | No | FieldMask to control what fields are to be returned, if empty assumes everything, Required: false Valid path names are names of each field in the UserResponse proto |
genericFilter | string | No | Generic filter for user fields (userId, firstName, lastName, email, location, attributes.scope, attributes.name & attribute.value) If it contains a whitespace, it splits the text and filter by both words, Required: false |
includeDisabled | boolean | No | Flag to include disabled scoped users, Default: false, Required: false if its set to true, all the scoped users will be fetched. This field is set for Deprecation, please switch to the new status_in_scope field. if the scope field above is null this field we be disregarded and no filter will be applied on any scope |
pageSize | integer (int32) | No | Requested size of the next page of data. If not set, the default page size is 10, Required: false. |
pageToken | string | No | MongoDB Field, describes the encoded page token for page traversal, Required: false |
roleFilter | string | No | This filter will only return users who have roles that meet a certain criteria - ALL_ROLES: All Roles - USER_ONLY: User Roles only - ADMIN_ONLY: Admin Roles only |
roleId | string | No | role id. restrict results to users within this role, Required: false |
scope | string | No | scope of the users to list, Required: false |
searchMatchType | string | No | ENUM to switch between the type of string matching you want on a query. Historically, we relied solely on a "contains" or "wild-card" based matching on all fields within specific_filter and and generic_filter. With this ENUM you can now select to do exact matches, Default = REGEX, Required = false |
sortField | string | No | Sort field, valid values: userId, firstName, lastName, email, batchId, lastUpdated, licenses or creationTime Default: userId, Required: false |
sortType | string | No | Sort Type for the results, Default: ASC, Required: false |
specificFilter.email | string | No | |
specificFilter.firstName | string | No | |
specificFilter.lastName | string | No | |
specificFilter.licenseDomain | string | No | The domain of the license |
specificFilter.location | string | No | |
specificFilter.selectedDepartments | array | No | The selected departments of the user |
specificFilter.userId | string | No | |
specificFilter.workspaceName | string | No | The workspace name of the Workspace entity |
specificFilter.workspaceType | string | No | The workspace type of the Workspace entity |
specificFilterQueryType | string | No | ENUM to switch the specific_filter.first_name and specific_filter.last_name params from AND to OR, Default: AND, Required: false. |
startsWithSingleCharacter | boolean | No | Ability to search for a single starts with character, only applicable to specific_filter: first_name, Required: false, Default: false |
statusInScope | string | No | This enum works to retrieve either: ALL, only ENABLED, only DISABLED, users for a given scope if the scope field above is null this field we be disregarded and no filter will be applied on any scope Default: ENABLED, Required: false - ENABLED: gets only enabled users - DISABLED: gets only disabled users - ALL: gets all users |
tenantIds | array | No | List of Tenants of the users, Required: false |
Security
- Authorization (apiKey)
- Bearer token
Responses
200 — A successful response.
Content type: application/json
default — An unexpected error response.
Content type: application/json
Response models
200 — A successful response.
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
users | array | No | |
nextPageToken | string | No |
{
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"tenantId": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"email": {
"type": "string"
},
"location": {
"type": "string"
},
"site": {
"type": "string"
},
"departments": {
"type": "string"
},
"attributes": {
"type": "array",
"items": {
"type": "object"
}
},
"workspaces": {
"type": "array",
"items": {
"type": "object"
}
},
"userStatus": {
"type": "string"
},
"creationTime": {
"type": "string",
"format": "date-time"
},
"lastUpdated": {
"type": "string",
"format": "date-time"
},
"batchId": {
"type": "string"
},
"notificationPreferences": {
"type": "array",
"description": "User notification preferences for different subsystems and scopes. If not present for a given subsystem/scope, it is assumed all notifications modes are enabled.",
"items": {
"type": "object"
}
},
"contactNumber": {
"type": "string"
},
"uniqueUserId": {
"type": "string",
"description": "Randomly generated string at the time of creation. Should be used to reference a unique user by other services as user_id may contain PII."
},
"claims": {
"type": "object"
},
"enabledScopes": {
"type": "object",
"description": "Scopes and status (enable, disable) for a user. Scope is optional. Typically applications will always pass their scope, but it is optional for admin purposes."
},
"addresses": {
"type": "array",
"items": {
"type": "object"
}
},
"contactNumbers": {
"type": "array",
"items": {
"type": "object"
}
},
"roles": {
"type": "array",
"description": "The user's roles. Includes nested roles. Flat list. Read only.",
"items": {
"type": "object"
}
},
"defaultLocale": {
"type": "string"
},
"primarySite": {
"type": "string"
},
"selectedDepartments": {
"type": "array",
"items": {
"type": "string"
}
},
"licenses": {
"type": "array",
"items": {
"type": "object"
}
},
"middleName": {
"type": "string",
"description": "Middle name of the user."
},
"preferredName": {
"type": "string",
"description": "Preferred Name of the user."
},
"isClient": {
"type": "boolean"
},
"assignedRoles": {
"type": "array",
"items": {
"type": "object"
}
},
"inheritedRoles": {
"type": "array",
"items": {
"type": "object"
}
},
"siteMapping": {
"type": "array",
"items": {
"type": "object"
}
},
"primarySelectedDepartments": {
"type": "array",
"description": "The selected departments that the user is assigned to. This is to support UI for getting the details part of the graphQL query.\nIn V3, we can remove the existing selected_departments field and use this one instead.",
"items": {
"type": "object",
"description": "Protobuf created to represent a Department.\nUsing this name because UniqueDepartmentProto is already used for another use case."
}
},
"userStatusLastUpdated": {
"type": "string",
"format": "date-time"
}
}
}
},
"nextPageToken": {
"type": "string"
}
}
}
default — An unexpected error response.
Content type: application/json
Schema
| Property | Type | Required | Description |
|---|---|---|---|
code | integer (int32) | No | |
message | string | No | |
details | array | No |
{
"type": "object",
"properties": {
"code": {
"type": "integer",
"format": "int32"
},
"message": {
"type": "string"
},
"details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"@type": {
"type": "string"
}
}
}
}
}
}