Appointments Connector

This connector handles authenticated appointment retrieval and appointment booking flows for the active patient session.

HCAppointmentsClient uses the active authenticated session from HCLoginClient, so appointment requests do not require a separate authentication setup.

The resources in this section follow the appointment workflow from retrieving available appointment slots and patient appointments through booking appointments.

Node.js Package

@healthcloudai/hc-appointments-connector

Client

HCAppointmentsClient

Authentication

Reuses the authenticated patient session from HCLoginClient.

Features

1. Retrieve available appointment slots for the authenticated patient
2. Retrieve patient appointments and appointment history
3. Book appointments using available appointment slot IDs
4. Reuse the authenticated login client for headers and base URL
5. Optionally attach API key headers to Appointments connector requests

Setup

Configure and authenticate HCLoginClient before passing it into HCAppointmentsClient.

Reuse the same authenticated HCLoginClient instance so both connectors share the same authentication state.

const httpClient = new FetchClient();

const authClient = new HCLoginClient(
  httpClient
);

authClient.configure(
  "healthcheck",
  "dev"
);

await authClient.login(
  "<PATIENT_EMAIL>",
  "ExamplePassword123!"
);

const appointmentsClient =
  new HCAppointmentsClient(
    httpClient,
    authClient
  );

API Key

Use setApiKey(...) to attach an API key header to Appointments connector requests.

const apiKey =
  process.env.HEALTHCLOUD_API_KEY;

if (!apiKey) {
  throw new Error(
    "HEALTHCLOUD_API_KEY is required."
  );
}

appointmentsClient.setApiKey(
  "x-api-key",
  apiKey
);

Parameters

| Parameter | Type | Description | | ------------ | -------- | ------------------- | | headerName | string | API key header name | | value | string | API key value |

Notes

• Header name should typically be x-api-key.
• API key headers are attached only to Appointments connector requests.

Resources

Get Available Slots

Method Signature

appointmentsClient.listAvailableSlots(): Promise<
  APIResponse<AvailableAppointmentsResponse>
>

Behavior

Sends an authenticated GET request and returns available appointment slots for the authenticated patient.

Does not send a request body.

Returns

Returns a raw backend response:

APIResponse<AvailableAppointmentsResponse>

Usage

const response =
  await appointmentsClient.listAvailableSlots();

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Response

{
  "Data": {
    "appointmentslots": [
      {
        "AppointmentType": "Follow Up",
        "DepartmentId": null,
        "ProviderId": null,
        "PatientAppointmentTypeName": null,
        "Date": "04/08/2026",
        "AppointmentId": "slot-id-example",
        "AppointmentTypeId": "1144",
        "Duration": 30,
        "StartTime": "09:00",
        "EndTime": "09:30",
        "LocalProviderId": null
      }
    ],
    "availability": {
      "DATE_04_08_2026": [
        {
          "id": "slot-id-example",
          "time": "09:00 AM - 09:30 AM",
          "appointmenttypeid": "FOLLOWUP",
          "providerid": "default"
        }
      ]
    }
  },
  "IsOK": true,
  "ErrorMessage": null
}

Notes

• The connector preserves the raw backend response contract.
• Available appointment slots are returned inside the Data field.

Get Patient Appointments

Method Signature

appointmentsClient.listPatientAppointments(): Promise<
  APIResponse<AppointmentData[]>
>

Behavior

Sends an authenticated GET request and returns appointments for the authenticated patient.

Does not send a request body.

Returns

Returns a raw backend response:

APIResponse<AppointmentData[]>

Usage

const response =
  await appointmentsClient.listPatientAppointments();

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Response

{
  "Data": [
    {
      "Date": "05/04/2026",
      "Copay": "0",
      "Claims": null,
      "Patient": null,
      "VisitId": null,
      "Duration": 15,
      "FrozenYn": null,
      "UrgentYn": null,
      "PatientId": null,
      "StartTime": "15:00",
      "Insurances": null,
      "ProviderId": "26",
      "StopCheckIn": null,
      "StopSignOff": null,
      "CustomFields": null,
      "DepartmentId": "1",
      "StartCheckIn": null,
      "AppointmentId": "3167177",
      "CancelledDate": null,
      "Hl7ProviderId": null,
      "AppointmentType": "Telehealth Office Visit",
      "AppointmentStatus": "f",
      "AppointmentTypeId": "1411",
      "AppointmentMessage": null,
      "ReferringProviderId": null,
      "RenderingProviderId": null,
      "SupervisingProviderId": null,
      "NativeAthenaTelehealth": null,
      "RescheduledAppointmentId": null,
      "AppointmentCancelReasonId": null,
      "UseExpectedProcedureCodes": null,
      "PatientAppointmentTypeName": "Telehealth Office Visit"
    }
  ],
  "IsOK": true,
  "ErrorMessage": null
}

Book Appointment

Method Signature

appointmentsClient.bookAppointment(
  appointmentId: string,
  appointmentTypeId: string,
  options?: BookAppointmentOptions
): Promise<
  APIResponse<BookAppointmentResponse>
>

Behavior

Sends an authenticated POST request and books an appointment using the provided appointment slot ID.

Parameters

| Parameter | Type | Description | | ------------------- | ------------------------ | ----------------------------------------------- | | appointmentId | string | Appointment slot ID used in the route | | appointmentTypeId | string | Appointment type ID sent in the request payload | | options | BookAppointmentOptions | Optional appointment booking fields |

Optional Payload Fields

| Field | Type | | ----------------------------- | --------- | | PracticeId | string | | ProviderName | string | | ProviderID | string | | IgnoreSchedulablePermission | boolean |

Returns

Returns a raw backend response:

APIResponse<BookAppointmentResponse>

Usage

const response =
  await appointmentsClient.bookAppointment(
    "3167177",
    "1411",
    {
      ProviderName: "Dr. Smith",
      ProviderID: "26",
      PracticeId: "1"
    }
  );

if (!response.IsOK) {
  console.error(
    response.ErrorMessage
  );

  return;
}

console.log(response.Data);

API Request

{
  "Data": {
    "AppointmentTypeId": "1411",
    "PracticeId": "1",
    "ProviderName": "Dr. Smith",
    "ProviderID": "26"
  }
}

API Response

{
  "Data": {
    "AppointmentType": "Telehealth Office Visit",
    "PatientId": "948680",
    "AppointmentStatus": "f",
    "DepartmentId": "1",
    "ProviderId": "26",
    "PatientAppointmentTypeName": "Telehealth Office Visit",
    "Date": "05/04/2026",
    "AppointmentId": "3167177",
    "AppointmentTypeId": "1411",
    "ChargeEntryNotRequired": false,
    "Duration": 15,
    "StartTime": "15:00",
    "TelehealthDeeplink": "https://telehealth-preview.px.athena.io/deeplink/example-token",
    "Expiration": "2026-05-02T12:27:53Z"
  },
  "IsOK": true,
  "ErrorMessage": null
}

Notes

• appointmentId is used only as the route parameter.
• appointmentId is not sent inside the request payload.
• The connector preserves the raw backend response contract.

Notes

• HCLoginClient must be configured and authenticated before calling appointment methods.

• Reuse the same authenticated HCLoginClient instance when constructing HCAppointmentsClient.

• Public SDK methods do not require consumers to manually provide:

  • Data wrappers
  • authorization headers
  • tenant identifiers
  • resolved service URLs

• The connector returns raw backend APIResponse<T> responses without response transformation or unwrapping.

• Backend-defined failure responses remain part of the returned API contract.

Prerequisites

HCLoginClient must be configured and the patient must be logged in before calling any method on this connector.

import { HCLoginClient } from "@healthcloudai/hc-login-connector";
import { FetchClient } from "@healthcloudai/hc-http";

const httpClient = new FetchClient();
const loginClient = new HCLoginClient(httpClient);

loginClient.configure("healthcheck", "dev");
await loginClient.login("[email protected]", "ExamplePassword123!");

See the hc-login-connector documentation for the full authentication flow.

Error Handling

All methods throw errors that extend APIError from @healthcloudai/hc-http.

Backend business failures (IsOK: false) are thrown as HCServiceError.

import { HCServiceError, APIError } from "@healthcloudai/hc-http";

try {
  const result = await client.someMethod();
} catch (err) {
  if (err instanceof HCServiceError) {
    console.error("Backend error:", err.backendMessage);
  } else if (err instanceof APIError) {
    console.error("SDK error:", err.message, err.code);
  }
}