# (NEW!) List Users (Paginated)

Retrieve an offset-paginated, searchable list of users for the authenticated customer. Supports free-text search, status/role/group filtering, and server-side sorting.

This endpoint supersedes GET /user/search/{searchText} — it adds userName to the searchable fields and returns createdEpoch/lastUpdatedEpoch on every result.

Defaults:
- from defaults to 0.
- limit defaults to 100 (values above 100 are capped to 100).
- sortField defaults to firstName.
- order defaults to desc.

Business Rules:
- searchTerm is trimmed and, when non-empty, matched as a case-insensitive substring against first name, last name, friendly name, email, status, phone, company, country, contact, userName, role name, and group name. Literal % and _ are treated as text, not SQL wildcards. Omitted returns all users — no * sentinel required.
- role and group are comma-separated lists of role/group names (not ids); multiple values use OR logic.
- status accepts enabled, disabled, pendingApproval. allDisabled is not a supported value and is rejected with 400. Omitted returns users of any status.
- groupCount (as a sortField value) sorts by the number of group ids in the user's groups array; a user with no groups sorts as 0, never null. It does not add a groupCount field to the response.
- roleName (as a sortField value) sorts using the user's associated role name.
- status (as a sortField value) sorts alphabetically by the stored status value.
- Each result includes both the id and display name for its role (roleId/roleName) and for each group (groupId/groupName) — the front end does not need to resolve ids to names itself.
- connectUser indicates whether the user can access Tenovos Connect. connectRole holds that user's Tenovos Connect role and is null when connectUser is false. The connectUser query parameter filters on this same field: true returns only Tenovos Connect users, false returns only users who are not, and omitting it applies no filter at all rather than defaulting to either.

The user submitting the request must have the User Management privilege.

Endpoint: GET /users
Version: 1.5
Security: ApiKeyAuth, BasicAuth

## Header parameters:

  - `X-API-Key` (string, required)
    Customer-specific API key required to invoke API.

  - `Authorization` (string, required)
    Provided by Authentication Token creation operation.

## Query parameters:

  - `searchTerm` (string)
    Case-insensitive substring match against first name, last name, friendly name, email, status, phone, company, country, contact, userName, role name, and group name. Literal % and _ are treated as text. Omitted returns all users.
    Example: "smith"

  - `role` (string)
    Comma-separated list of role names. Multiple values use OR logic.
    Example: "Admin,Content Editor"

  - `group` (string)
    Comma-separated list of group names. A user matches when they belong to at least one supplied group.
    Example: "Marketing"

  - `status` (string)
    Filters by account status. Omitted returns users of any status. allDisabled is not supported.
    Enum: "enabled", "disabled", "pendingApproval"

  - `connectUser` (boolean)
    Filters by Tenovos Connect access, matching the connectUser field on each result. true returns only Tenovos Connect users; false returns only users who are not. Omitted applies no filter and returns both.
    Example: true

  - `from` (integer)
    Result offset from which to start. Defaults to 0.

  - `limit` (integer)
    Number of results to return per page. Defaults to 100, maximum 100 (values above 100 are capped).
    Example: 100

  - `sortField` (string)
    Field to sort results by. Defaults to firstName.
    Enum: "firstName", "lastName", "emailId", "userName", "friendlyName", "status", "phone", "contact", "country", "company", "createdEpoch", "lastUpdatedEpoch", "groupCount", "roleName"

  - `order` (string)
    Sort direction. Defaults to desc.
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `users` (array)
    Users on this page.

  - `users.userId` (string)
    Unique ID of the user.
    Example: "7d675ef0-f423-11e9-8071-89c0c4052141"

  - `users.customerId` (string)
    Parent customer ID.
    Example: "1234567890"

  - `users.emailId` (string)
    User email address.
    Example: "erlich.bachman@piedpiper.com"

  - `users.firstName` (string)
    User first name.
    Example: "Erlich"

  - `users.lastName` (string)
    User last name.
    Example: "Bachman"

  - `users.roleId` (string)
    ID of the user's assigned role.
    Example: "7d5620e0-f423-11e9-8071-89c0c4052141"

  - `users.roleName` (string)
    Display name of the user's assigned role.
    Example: "Admin"

  - `users.status` (string)
    Account status.
    Enum: "enabled", "disabled", "pendingApproval"

  - `users.groups` (array)
    Groups the user belongs to.
    Example: [{"groupId":"7d6207c0-f423-11e9-8071-89c0c4052141","groupName":"Marketing"}]

  - `users.groups.groupId` (string)
    Unique ID of the group.
    Example: "7d6207c0-f423-11e9-8071-89c0c4052141"

  - `users.groups.groupName` (string)
    Display name of the group.
    Example: "Marketing"

  - `users.connectUser` (boolean)
    Whether the user can access Tenovos Connect.
    Example: true

  - `users.connectRole` (string,null)
    The user's Tenovos Connect role. Null when connectUser is false.
    Example: "Admin"

  - `users.userName` (string,null)
    The username of the Tenovos user, created by the administrator or user at account creation. Can be null for federated user accounts.
    Example: "erlich.bachman"

  - `users.phone` (string)
    Example: "15551234565"

  - `users.contact` (string)
    The person designated as the sponsor/point of contact for this user.
    Example: "Richard Hendricks"

  - `users.country` (string)
    The country in which the Tenovos user is located.
    Example: "USA"

  - `users.company` (string)
    The company that the Tenovos user works for.
    Example: "Pied Piper"

  - `users.friendlyName` (string)
    A "friendlier" version of the username. Used in the UI display and provided by the user.
    Example: "Erlich Bachman"

  - `users.createdEpoch` (integer)
    Unix timestamp (ms) of creation.
    Example: 1690000000000

  - `users.lastUpdatedEpoch` (integer)
    Unix timestamp (ms) of the last update.
    Example: 1700000000000

  - `pageInfo` (object)

  - `pageInfo.from` (integer)
    Offset of the first result on this page.

  - `pageInfo.limit` (integer)
    Maximum number of results requested per page.
    Example: 100

  - `pageInfo.total` (integer)
    Total number of users matching the search and filters, before pagination.
    Example: 842

  - `pageInfo.hasNextPage` (boolean)
    Whether more matching users exist beyond this page.
    Example: true

## Response 400 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 401 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 403 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)

## Response 500 fields (application/json):

  - `status` (string)
    Example: "error"

  - `message` (string)