# List users

List users of a specific TMC or a company.

Endpoint: POST /v3/users/list
Version: v2
Security: Bearer

## Request fields (application/json):

  - `userStatusFilter` (string)
    Retrieve active, inactive, or all users.
    Enum: "ACTIVE", "INACTIVE", "ALL"

  - `searchText` (string)
    Query text to search users. The match would be case-insensitive.
    Example: "chi"

  - `pagination` (object, required)
    Pagination parameters for requests.

  - `pagination.offset` (integer)
    The starting index in the list from which results are returned. The value must be greater than or equal to 0.

  - `pagination.limit` (integer)
    Maximum number of results to be fetched.

  - `filters` (array)
    Filters to refine the list of users returned. Users matching with any of the filters would be returned.

  - `filters.legalEntityIds` (array)
    Filter by legal entity ids.

  - `filters.legalEntityIds.id` (string, required)
    Example: "b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3"

  - `filters.officeIds` (array)
    Filter by offices.

  - `filters.departmentIds` (array)
    Filter by department IDs.

  - `filters.costCenterIds` (array)
    Filter by cost center IDs.

  - `filters.userIds` (array)
    Filter by user IDs.

  - `filters.emails` (array)
    Filter by user email IDs.

  - `filters.externalIds` (array)
    Filter by partner-assigned external identifiers for users.

  - `filters.personas` (array)
    Filter by user personas.
    Enum: "UNKNOWN_PERSONA", "EMPLOYEE", "GUEST", "PERSONAL", "RELATIVE", "ADHOC"

  - `filters.roles` (array)
    Filter by user roles.
    Enum: "UNKNOWN_TYPE", "COMPANY_ADMIN", "COMPANY_TRAVEL_ARRANGER", "TRAVEL_ARRANGER", "COMPANY_REPORT_ADMIN", "GLOBAL_ADMIN", "GLOBAL_AGENT", "TMC_AGENT", "TMC_ADMIN"

  - `filters.designations` (array)
    Filter by job titles or designations.

  - `filters.tiers` (array)
    Filter by tiers.
    Enum: "BASIC", "SEAT1A"

  - `sort` (object)

  - `sort.sortBy` (string, required)
    The column on which the sorting should be applied.
    Enum: "NAME"

  - `sort.sortOrder` (string, required)
    Order of sorting ie ascending or descending.
    Enum: "ASCENDING", "DESCENDING"

## Response 200 fields (application/json):

  - `users` (array)
    Users matching the filters specified in the request.

  - `users.userId` (object, required)
    User identifier

  - `users.userId.id` (string, required)

  - `users.organization` (object, required)
    The organization associated with the user.

  - `users.organization.name` (string)
    Example: "Name"

  - `users.persona` (string, required)
    Persona of the user like EMPLOYEE, GUEST etc.
    Enum: "UNKNOWN_PERSONA", "EMPLOYEE", "GUEST", "PERSONAL", "RELATIVE", "ADHOC"

  - `users.isActive` (boolean, required)
    Whether user is active or not.

  - `users.externalId` (string)
    External ID of the user.

  - `users.personalDetail` (object, required)
    Personal details of the user.

  - `users.personalDetail.name` (object)
    Full name containing first, middle, last (family) names, and suffix.

  - `users.personalDetail.name.family1` (string, required)
    Last (family) name.
    Example: "Gandas"

  - `users.personalDetail.name.family2` (string)
    Example: "FamilyTwo"

  - `users.personalDetail.name.given` (string, required)
    First (given) name.
    Example: "Vichitr"

  - `users.personalDetail.name.middle` (string)
    Middle name.
    Example: "Kumar"

  - `users.personalDetail.name.suffix` (string)
    Suffix used with the name. For example SR or JR.
    Enum: "NAME_SUFFIX_UNKNOWN", "SR", "JR", "MD", "PHD", "II", "III", "IV", "DO", "ATTY", "V", "VI", "ESQ", "DC", "DDS", "VM", "JD", "SECOND", "THIRD"

  - `users.personalDetail.name.preferred` (string)
    Informal preferred name added by traveler. This is not used on any PNR or tickets
    Example: "Don"

  - `users.personalDetail.title` (string)
    Enum: "TITLE_UNKNOWN", "MR", "MS", "MRS", "MX", "MASTER", "MISS", "DR", "PROFESSOR", "CAPTAIN", "REVEREND", "HONOURABLE", "SIR", "LADY", "AMBASSADOR", "LORD", "BRIGADIER", "SENATOR", "DAME", "JUSTICE", "UK"

  - `users.personalDetail.gender` (string)
    Enum: "MALE", "FEMALE", "UNSPECIFIED", "UNDISCLOSED"

  - `users.personalDetail.pronoun` (string)
    Enum: "SHE_HER_HERS", "HE_HIM_HIS", "THEY_THEM_THEIRS"

  - `users.personalDetail.preferredLanguage` (string)
    Preferred language of the user

  - `users.personalDetail.nationality` (string)
    Nationality of the user

  - `users.personalDetail.profilePicture` (object)
    An image with meta data. Either the data or url property must be supplied to load the image.

  - `users.personalDetail.profilePicture.data` (string)
    Example: "6935813e12584abda0e43d71cd2ea260"

  - `users.personalDetail.profilePicture.dimensions` (object)
    Image dimensions ie width and height.

  - `users.personalDetail.profilePicture.dimensions.height` (integer)
    Example: 120

  - `users.personalDetail.profilePicture.dimensions.width` (integer)
    Example: 240

  - `users.personalDetail.profilePicture.url` (string)
    Example: "https://static.wixstatic.com/media/73f2e2_6935813e12584abda0e43d71cd2ea260~mv2.png/v1/fill/w_630,h_94,al_c,q_85,usm_0.66_1.00_0.01/Spotnana%403x.webp"

  - `users.businessDetail` (object, required)
    Business details of the user.

  - `users.businessDetail.legalEntity` (object, required)
    The legal entity associated with the user.

  - `users.businessDetail.office` (object)
    The office associated with the user.

  - `users.businessDetail.department` (object)
    The department associated with the user.

  - `users.businessDetail.costCenter` (object)
    The cost center associated with the user.

  - `users.businessDetail.businessEmail` (string)
    Business email of the user.

  - `users.businessDetail.designation` (string)
    Designation or job title of the user.

  - `users.businessDetail.employeeId` (string)
    Employee ID of the user.

  - `users.createdAt` (object, required)
    Date and time of the user profile creation.

  - `users.createdAt.iso8601` (string, required)
    Example: "2017-07-21T17:32"

  - `users.lastUpdatedAt` (object, required)
    Date and time of the latest update made to the user profile.

  - `pagination` (object)
    Pagination parameters for response.

  - `pagination.totalNumResults` (integer, required)
    Total number of results.

## Response 401 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 403 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.

## Response 404 fields (application/json):

  - `debugIdentifier` (string)
    Link to debug the error internally.

  - `errorMessages` (array)

  - `errorMessages.errorCode` (string)
    Error code to identify the specific errors.

  - `errorMessages.message` (string)
    Message containing details of error.

  - `errorMessages.errorParameters` (array)
    Error message parameters.

  - `errorMessages.errorParameters.name` (string)
    Parameter name

  - `errorMessages.errorParameters.value` (string)
    Parameter value

  - `errorMessages.errorDetail` (string)
    More details about the error.