> ## 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 Session by ID

> Retrieve a single session (appointment) by its public id.

## Get Session by ID

Retrieve a single session (appointment) by its public id. The session must belong to the organization that owns the API key.

### Headers

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

### Path Parameters

* `sessionId` (required): Session public id

### Success Response (200)

The response shape depends on `isBillable`. A **billable** session exposes `isTelehealth`, `clinicianId` and `services` (and never `nonBillableCode`):

```json theme={null}
{
  "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"
}
```

A **non-billable** session exposes `nonBillableCode` instead (and omits `isTelehealth`, `clinicianId` and `services`):

```json theme={null}
{
  "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"
}
```

### Error Responses

#### 400 - Bad Request

Returned when `sessionId` is not a well-formed public id (for example it contains a null byte or other invalid characters):

```json theme={null}
{
  "message": "Validation Error",
  "statusCode": 400,
  "validationErrors": [
    {
      "code": "custom",
      "path": ["sessionId"],
      "message": "sessionId is invalid"
    }
  ]
}
```

#### 401 - Unauthorized

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

#### 403 - Forbidden

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

#### 404 - Not Found

```json theme={null}
{
  "error": "Session not found",
  "statusCode": 404
}
```

## Examples

### cURL Example

```bash theme={null}
curl -X GET "https://app.hipp.health/api/v1/sessions/apt_1a2b3c4d5e" \
  -H "Authorization: Bearer your-api-key"
```

### JavaScript Example

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

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

  return response.json();
};

// Usage
try {
  const session = await getSession("apt_1a2b3c4d5e");
  console.log("Session:", session);
} catch (error) {
  console.error("Error fetching session:", error.message);
}
```


## OpenAPI

````yaml GET /v1/sessions/{sessionId}
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/{sessionId}:
    get:
      tags:
        - V1
      summary: Get session by id
      description: Retrieve a single session (appointment) by its public id.
      operationId: get-v1-session-by-id
      parameters:
        - name: sessionId
          in: path
          description: Session public identifier
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Session not found
                  statusCode:
                    type: integer
                    example: 404
        '405':
          $ref: '#/components/responses/405'
      security:
        - BearerAuth: []
components:
  schemas:
    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
    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
    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
    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
  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>'

````