> ## 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 Sessions

> Get a paginated list of sessions (appointments) with optional filtering by client, staff member, and date range.

## Get All Sessions

Retrieve a paginated list of sessions (appointments) with optional filtering by client, staff member, and date range. Results are scoped to the organization that owns the API key.

### Headers

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

### Query Parameters

* `page` (optional): Page number (1-indexed). Default: `1`. Minimum: `1`, Maximum: `1000000`
* `pageSize` (optional): Number of items per page. Default: `25`. Minimum: `1`, Maximum: `100`
* `clientId` (optional): Filter by client public id
* `technicianId` (optional): Filter by staff member (technician) public id
* `clinicianId` (optional): Filter by clinician public id
* `startDate` (optional): Only sessions on or after this calendar date (`YYYY-MM-DD`). Must be on or before `endDate`
* `endDate` (optional): Only sessions on or before this calendar date (`YYYY-MM-DD`)

### Session Model

Each item in `data` has the following shape:

* `publicId`: Session public id
* `title`: Human-readable session title
* `status`: Current scheduling status
* `startTime` / `endTime`: Session instants in UTC (ISO-8601). Naive `date` + `startTime`/`endTime` supplied at creation are resolved to instants server-side using the request timezone
* `isSupervision`: Session flag
* `isClientPresent`: Whether the client is present for the session
* `placeOfService`: CMS place-of-service enum
* `locationId`: Public id of the session location
* `technicianId` / `clientId`: Public ids of the related resources, or `null`
* `isBillable`: Discriminates the response shape. **Billable** (`true`) sessions add `isTelehealth`, `clinicianId`, `providerLocationId` and `services`; **non-billable** (`false`) sessions add `nonBillableCode` instead

Billable-only fields (present when `isBillable` is `true`):

* `isTelehealth`: Whether the session is delivered via telehealth
* `clinicianId`: Public id of the assigned clinician, or `null`
* `providerLocationId`: Public id of the provider location the care was delivered from, or `null`
* `services`: Public id of the billable service line rendered

Non-billable-only field (present when `isBillable` is `false`):

* `nonBillableCode`: Public id of the non-billable code

### Success Response (200)

```json theme={null}
{
  "data": [
    {
      "publicId": "apt_1a2b3c4d5e",
      "title": "John Doe — Adaptive behavior treatment",
      "status": "CONFIRMED",
      "startTime": "2026-01-05T14:00:00.000Z",
      "endTime": "2026-01-05T15:00:00.000Z",
      "isSupervision": false,
      "isClientPresent": true,
      "placeOfService": "HOME",
      "locationId": "loc_1a2b3c",
      "technicianId": "usr_tech123",
      "clientId": "usr_client789",
      "isBillable": true,
      "isTelehealth": false,
      "clinicianId": "usr_clin456",
      "providerLocationId": "loc_9f8e7d",
      "services": "svc_1a2b3c"
    },
    {
      "publicId": "apt_9z8y7x",
      "title": "Travel",
      "status": "CONFIRMED",
      "startTime": "2026-01-05T12:00:00.000Z",
      "endTime": "2026-01-05T12:30:00.000Z",
      "isSupervision": false,
      "isClientPresent": false,
      "placeOfService": "OTHER",
      "locationId": "loc_1a2b3c",
      "technicianId": "usr_tech123",
      "clientId": null,
      "isBillable": false,
      "nonBillableCode": "nbc_1a2b3c"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 25,
    "totalCount": 100,
    "totalPages": 4
  }
}
```

### Error Responses

#### 400 - Validation Error

```json theme={null}
{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "custom",
      "message": "startDate must be on or before endDate.",
      "path": ["startDate"]
    }
  ]
}
```

#### 401 - Unauthorized

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

#### 403 - Forbidden

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

## Examples

### cURL Example

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

# Filter by client and date range
curl -X GET "https://app.hipp.health/api/v1/sessions?clientId=usr_client789&startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer your-api-key"
```

### JavaScript Example

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

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

  return response.json();
};

// Usage
try {
  const result = await getSessions({
    page: 1,
    pageSize: 25,
    technicianId: "usr_tech123",
  });
  console.log("Sessions:", result.data);
  console.log("Pagination:", result.pagination);
} catch (error) {
  console.error("Error fetching sessions:", error.message);
}
```


## OpenAPI

````yaml GET /v1/sessions
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/sessions:
    get:
      tags:
        - V1
      summary: Get sessions
      description: >-
        Get a paginated list of sessions (appointments) with optional filtering
        by client, staff member, and date range.
      operationId: get-v1-sessions
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000000
            default: 1
        - in: query
          name: pageSize
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
          required: false
        - in: query
          name: clientId
          description: Filter by client public id
          schema:
            type: string
          required: false
        - in: query
          name: technicianId
          description: Filter by staff member (technician) public id
          schema:
            type: string
          required: false
        - in: query
          name: clinicianId
          description: Filter by clinician public id
          schema:
            type: string
          required: false
        - in: query
          name: startDate
          description: >-
            Only sessions on or after this calendar date (YYYY-MM-DD). Must be
            on or before endDate.
          schema:
            type: string
            format: date
            example: '2026-01-01'
          required: false
        - in: query
          name: endDate
          description: Only sessions on or before this calendar date (YYYY-MM-DD).
          schema:
            type: string
            format: date
            example: '2026-12-31'
          required: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSessionsResponseSchema'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '405':
          $ref: '#/components/responses/405'
        '500':
          $ref: '#/components/responses/500'
      security:
        - BearerAuth: []
components:
  schemas:
    PaginatedSessionsResponseSchema:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    Session:
      description: >-
        A scheduled session (appointment). The shape depends on isBillable:
        billable sessions expose isTelehealth, clinicianId and services;
        non-billable sessions expose nonBillableCode instead.
      oneOf:
        - $ref: '#/components/schemas/BillableSession'
        - $ref: '#/components/schemas/NonBillableSession'
      discriminator:
        propertyName: isBillable
    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
      required:
        - message
        - statusCode
        - validationErrors
      properties:
        message:
          type: string
          example: Validation Error
        statusCode:
          type: integer
          example: 400
        validationErrors:
          type: array
          description: Zod validation issues
          items:
            type: object
            properties:
              code:
                type: string
                example: invalid_type
              message:
                type: string
                example: Required
              path:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: integer
                example:
                  - email
    ApiErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: User not found
        statusCode:
          type: integer
          example: 404
      required:
        - error
        - statusCode
    BillableSession:
      allOf:
        - $ref: '#/components/schemas/SessionBase'
        - type: object
          properties:
            isBillable:
              type: boolean
              enum:
                - true
              description: Always true for billable sessions.
            isTelehealth:
              type: boolean
              example: false
            clinicianId:
              type: string
              nullable: true
              description: Public id of the assigned clinician, if any.
              example: usr_clin456
            providerLocationId:
              type: string
              nullable: true
              description: >-
                Public id of the provider location the care was delivered from,
                if any.
              example: loc_9f8e7d
            services:
              type: string
              description: >-
                Public id of the billable service line rendered. A session bills
                exactly one service line.
              example: svc_1a2b3c
          required:
            - isBillable
            - isTelehealth
            - clinicianId
            - providerLocationId
            - services
    NonBillableSession:
      allOf:
        - $ref: '#/components/schemas/SessionBase'
        - type: object
          properties:
            isBillable:
              type: boolean
              enum:
                - false
              description: Always false for non-billable sessions.
            nonBillableCode:
              type: string
              description: Public id of the non-billable code.
              example: nbc_1a2b3c
          required:
            - isBillable
            - nonBillableCode
    SessionBase:
      type: object
      properties:
        publicId:
          type: string
          example: apt_1a2b3c4d5e
        title:
          type: string
          example: John Doe — Adaptive behavior treatment
        status:
          $ref: '#/components/schemas/AppointmentStatus'
        startTime:
          type: string
          format: date-time
          description: Session start instant in UTC (ISO-8601).
          example: '2026-01-05T14:00:00.000Z'
        endTime:
          type: string
          format: date-time
          description: Session end instant in UTC (ISO-8601).
          example: '2026-01-05T15:00:00.000Z'
        isSupervision:
          type: boolean
          example: false
        isClientPresent:
          type: boolean
          example: true
        placeOfService:
          $ref: '#/components/schemas/PlaceOfServiceCode'
        locationId:
          type: string
          description: Public id of the session location.
          example: loc_1a2b3c
        technicianId:
          type: string
          nullable: true
          description: Public id of the assigned technician, if any.
          example: usr_tech123
        clientId:
          type: string
          nullable: true
          description: Public id of the client, if any.
          example: usr_client789
      required:
        - publicId
        - title
        - status
        - startTime
        - endTime
        - isSupervision
        - isClientPresent
        - placeOfService
        - locationId
        - technicianId
        - clientId
    AppointmentStatus:
      type: string
      enum:
        - CONFIRMED
        - UNCONFIRMED
        - DECLINED
        - PATIENT_NO_SHOW
        - REQUESTED_TO_CANCEL
      description: >-
        Scheduling status of the session. Matched exactly (uppercase); any other
        value returns a 400.
    PlaceOfServiceCode:
      type: string
      enum:
        - TELEHEALTH_PROVIDED_ELSEWHERE
        - TELEHEALTH_PROVIDED_IN_PATIENT_HOME
        - OFFICE
        - HOME
        - SCHOOL
        - OTHER
        - TEMPORARY_LODGING
        - PLACE_OF_EMPLOYMENT
        - COMMUNITY_MENTAL_HEALTH_CENTER
      description: CMS place-of-service classification for the session
  responses:
    '400':
      description: Bad Request - Validation Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationError'
    '401':
      description: Unauthorized - API key required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: API key required
            statusCode: 401
    '403':
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: Access denied
            statusCode: 403
    '405':
      description: Method Not Allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: Method not allowed
            statusCode: 405
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            error: An unexpected error occurred
            statusCode: 500
  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>'

````