> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hipp.health/llms.txt
> Use this file to discover all available pages before exploring further.

# Get All Users

> Retrieve a paginated list of users with optional filtering and sorting

## Get All Users

Retrieve a paginated list of users with optional filtering and sorting.

### Headers

```
Authorization: Bearer <your-api-key>
```

### Query Parameters

* `page` (optional): Page number (1-indexed). Default: `1`. Minimum: `1`
* `pageSize` (optional): Number of items per page. Default: `25`. Minimum: `1`, Maximum: `100`
* `search` (optional): Search term to filter users
* `role` (optional): Filter by user role
  * Available roles: `ADMIN`, `BILLING_MANAGER`, `SCHEDULING_MANAGER`, `CLINICIAN`, `TECHNICIAN`, `PATIENT`, `CAREGIVER`, `HIPP_ADMIN`, `HIPP_BILLING_MANAGER`, `CLINICAL_ADMIN`, `PAYROLL_ADMIN`, `CLINICAL_SUPERADMIN`
  * Note: `HIPP_ADMIN` users are never included in the results, even when filtered for.
* `email` (optional): Filter by email address
* `sort` (optional): Sort order in format `field_direction` (e.g., `createdAt_desc`). Multiple sorts can be comma-separated (e.g., `createdAt_desc,updatedAt_asc`)
  * Allowed fields: `createdAt`, `updatedAt`
  * Allowed directions: `asc`, `desc`

### Success Response (200)

```json theme={null}
{
  "data": [
    {
      "publicId": "usr_1234567890_abc123def",
      "firstName": "John",
      "lastName": "Doe",
      "sex": "MALE",
      "caregiverId": null,
      "role": "PATIENT",
      "birthDate": "1990-01-15",
      "addressLine1": "123 Main St",
      "addressLine2": "Apt 4B",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 100,
    "totalPages": 4
  }
}
```

### Error Responses

#### 400 - Validation Error

```json theme={null}
{
  "error": "Validation error",
  "details": [
    {
      "code": "invalid_string",
      "message": "Invalid parameter value",
      "path": ["page"]
    }
  ]
}
```

#### 401 - Unauthorized

```json theme={null}
{
  "error": "API key required"
}
```

#### 403 - Forbidden

```json theme={null}
{
  "error": "Access denied"
}
```

## Examples

### cURL Example

```bash theme={null}
# Get all users with pagination
curl -X GET "https://app.hipp.health/api/v1/users?page=1&pageSize=25" \
  -H "Authorization: Bearer your-api-key"

# Get users with filtering and sorting
curl -X GET "https://app.hipp.health/api/v1/users?role=CLINICIAN&search=john&sort=createdAt_desc" \
  -H "Authorization: Bearer your-api-key"
```

### JavaScript Example

```javascript theme={null}
const getUsers = async (params = {}) => {
  const queryParams = new URLSearchParams(params);
  const response = await fetch(`/api/v1/users?${queryParams}`, {
    method: "GET",
    headers: {
      Authorization: "Bearer your-api-key",
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error || "Failed to fetch users");
  }

  return response.json();
};

// Usage
try {
  const result = await getUsers({
    page: 1,
    pageSize: 25,
    role: "CLINICIAN",
    sort: "createdAt_desc",
  });
  console.log("Users:", result.data);
  console.log("Pagination:", result.pagination);
} catch (error) {
  console.error("Error fetching users:", error.message);
}
```


## OpenAPI

````yaml GET /v1/users
openapi: 3.0.0
info:
  title: Hipp Health API
  version: 1.0.0
  description: API for managing users and resources within your Hipp Health organization
servers:
  - url: https://app.hipp.health/api
    description: Production Server
security: []
paths:
  /v1/users:
    get:
      tags:
        - users
      summary: Get paginated list of users
      description: Retrieve a paginated list of users with optional filtering and sorting
      operationId: getUsers
      parameters:
        - in: query
          name: page
          description: Page number (1-indexed)
          schema:
            type: integer
            minimum: 1
            default: 1
          required: false
        - in: query
          name: pageSize
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          required: false
        - name: search
          in: query
          description: Search term to filter users
          required: false
          schema:
            type: string
        - name: role
          in: query
          description: Filter by user role
          required: false
          schema:
            $ref: '#/components/schemas/UserRole'
        - name: email
          in: query
          description: Filter by email address
          required: false
          schema:
            type: string
            format: email
        - name: sort
          in: query
          description: >-
            Sort order in format 'field_direction' (e.g., 'createdAt_desc').
            Multiple sorts can be comma-separated (e.g.,
            'createdAt_desc,updatedAt_asc'). Allowed fields: createdAt,
            updatedAt. Allowed directions: asc, desc
          required: false
          schema:
            type: string
            pattern: >-
              ^(createdAt|updatedAt)_(asc|desc)(,(createdAt|updatedAt)_(asc|desc))*$
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsersResponse'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
      security:
        - BearerAuth: []
components:
  schemas:
    UserRole:
      type: string
      enum:
        - ADMIN
        - BILLING_MANAGER
        - SCHEDULING_MANAGER
        - CLINICIAN
        - TECHNICIAN
        - PATIENT
        - CAREGIVER
        - HIPP_ADMIN
        - HIPP_BILLING_MANAGER
        - CLINICAL_ADMIN
        - PAYROLL_ADMIN
        - CLINICAL_SUPERADMIN
      description: >-
        User role. All values may be returned by the API; a smaller subset may
        be assigned when creating a user (see the create user endpoint). Note
        that HIPP_ADMIN users are never returned by the list users endpoint.
    GetUsersResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: Array of users
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    User:
      type: object
      properties:
        publicId:
          type: string
          description: User public identifier
        firstName:
          type: string
          nullable: true
          description: User's first name
        lastName:
          type: string
          nullable: true
          description: User's last name
        sex:
          type: string
          nullable: true
          description: User's sex
          enum:
            - MALE
            - FEMALE
            - OTHER
        caregiverId:
          type: string
          nullable: true
          description: Caregiver public identifier (if user is a patient)
        role:
          $ref: '#/components/schemas/UserRole'
        birthDate:
          type: string
          format: date
          nullable: true
          description: User's birth date in YYYY-MM-DD format
        addressLine1:
          type: string
          nullable: true
          description: First line of address
        addressLine2:
          type: string
          nullable: true
          description: Second line of address
        city:
          type: string
          nullable: true
          description: City
        state:
          type: string
          nullable: true
          description: State
        postalCode:
          type: string
          nullable: true
          description: Postal code
      required:
        - publicId
        - role
    Pagination:
      type: object
      properties:
        page:
          type: integer
          description: Current page number (1-indexed)
        pageSize:
          type: integer
          description: Number of items per page
        totalCount:
          type: integer
          description: Total number of items
        totalPages:
          type: integer
          description: Total number of pages
      required:
        - page
        - pageSize
        - totalCount
        - totalPages
    ValidationError:
      type: object
      properties:
        error:
          type: string
          example: Validation error
        details:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_string
              message:
                type: string
                example: Valid email is required
              path:
                type: array
                items:
                  type: string
                example:
                  - email
  responses:
    '400':
      description: Bad Request - Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: API key required
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Access denied
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API key authentication. Include your API key in the Authorization header
        as 'Bearer <your-api-key>'

````