Healthcheck HL7 Scheduler Connector

SDK client for the Healthcheck HL7 Scheduler API.

The connector resolves the Scheduler host from loginClient.getEnvironment():

| Environment | Host | | --- | --- | | dev | https://dev-patient-scheduler.healthcloud-services.com | | uat | https://uat-patient-scheduler.healthcloud-services.com | | prod | https://api-patient-scheduler.healthcloud-services.com |

Installation

npm install @healthcloudai/hc-hl7-scheduler \
  @healthcloudai/hc-login-connector \
  @healthcloudai/hc-http

Import

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

HCHL7SchedulerClient is also exported as a backwards-compatible alias for HCHL7SchedulerClient.

Setup

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

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

const schedulerClient = new HCHL7SchedulerClient(httpClient, loginClient);

If the environment requires an API key, configure it once:

schedulerClient.setApiKey("x-api-key", process.env.HEALTHCLOUD_API_KEY ?? "");

Authentication

HCHL7SchedulerClient requires a logged-in HCLoginClient. Calls are authenticated with Authorization: Bearer <idToken>. The scheduler API does not use the X-Tenant-ID header.

loginClient.configure("healthcheck", "dev");
await loginClient.login("[email protected]", "ExamplePassword123!");
// loginClient must have a valid session before any scheduler call

Response Format

This connector does not use the Healthcheck APIResponse<T> envelope. All methods return raw FHIR resources and bundles (Appointment, AppointmentResponse, SlotSearchResponse, Bundle, etc.) directly.

Network and runtime errors are caught and re-thrown as APIError from @healthcloudai/hc-http.

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

try {
  const response = await schedulerClient.bookAppointment(request);
} catch (err) {
  if (err instanceof APIError) {
    console.error(err.message, err.code, err.statusCode);
  }
}

ID Rules

These IDs are easy to mix up, so keep them separate:

| Where it comes from | Example | Where to send it | | --- | --- | --- | | Slot.resource.id from searchSlots(...) or listSlots(...) | slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661 | Send as slotId to bookAppointment(...) and rescheduleAppointment(...). | | Appointment FHIR id from request/response reference | appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661 | Send as appointmentId to getAppointment(...), cancelAppointment(...), and as previousAppointmentId to rescheduleAppointment(...). | | AppointmentResponse.id | cda421aa-4f24-4ace-ba76-3a87a984b0ba | Do not use this as the appointment path id. It is the response resource id, not the FHIR appointment id used in routes. | | Athena patient id | 948363 | Put in appointment.identifier[].value and participant[].actor.reference as Patient/948363. | | Provider id | prac-26 or identifier value 26 | Provider listing returns this. listProviders(publisherId?) optionally filters by publisher id, not by provider id. | | Publisher id | a8d67eca330447c19c8cb49c6e3e0f19 | Use as publisherId in listSlots(...) or listProviders(...) when you need to filter by publisher. |

For booking and rescheduling, always use a fresh slotId returned by the latest slot search/list response. A successfully booked slot may disappear from the available slot index.

Methods

| Method | API call | Returns | | --- | --- | --- | | getHealth() | GET /health | Promise<HealthResponse> | | searchSlots(request) | POST /slots/search | Promise<SlotSearchResponse> | | listSlots(options?) | GET /slots | Promise<SlotSearchResponse> | | listProviders(publisherId?) | GET /providers | Promise<ProvidersResponse> | | listPublishers() | GET /publishers | Promise<PublishersResponse> | | bookAppointment(request) | POST /appointments/book | Promise<AppointmentResponse> | | getAppointment(appointmentId) | GET /appointments/:id | Promise<Appointment> | | cancelAppointment(appointmentId) | DELETE /appointments/:id | Promise<AppointmentResponse> | | rescheduleAppointment(request) | POST /appointments/reschedule | Promise<AppointmentResponse> | | sync() | POST /sync | Promise<SyncResult> | | getStatus(limit?) | GET /status | Promise<StatusResponse> |

Slots

searchSlots(request)

Request:

{
  "specialty": "General Practice",
  "page": 0,
  "hitsPerPage": 20
}

Response:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 11,
  "entry": [
    {
      "resource": {
        "resourceType": "Slot",
        "id": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
        "identifier": [
          {
            "system": "https://healthcheck.com/fhir/scheduling/ehr-id",
            "value": "a8d67eca330447c19c8cb49c6e3e0f19"
          },
          {
            "system": "https://healthcheck.com/fhir/scheduling/ehr-type",
            "value": "athena"
          },
          {
            "system": "https://athenahealth.com/appointmentid",
            "value": "3167661"
          },
          {
            "system": "https://athenahealth.com/appointmenttypeid",
            "value": "1411"
          },
          {
            "system": "https://athenahealth.com/practiceid",
            "value": "1959418"
          },
          {
            "system": "https://athenahealth.com/departmentid",
            "value": "1"
          },
          {
            "system": "https://athenahealth.com/providerid",
            "value": "26"
          }
        ],
        "schedule": {
          "reference": "Schedule/sched-26"
        },
        "status": "free",
        "start": "2026-05-30T14:00:00.0000000+00:00",
        "end": "2026-05-30T14:15:00.0000000+00:00",
        "appointmentType": {
          "coding": [
            {
              "system": "https://athenahealth.com/appointmenttypeid",
              "code": "1411",
              "display": "Telehealth Office Visit"
            }
          ],
          "text": "Telehealth Office Visit"
        },
        "serviceCategory": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/service-category",
                "code": "17",
                "display": "General Practice"
              }
            ]
          }
        ],
        "serviceType": [
          {
            "reference": {
              "reference": "HealthcareService/hs-healthcheck"
            }
          }
        ],
        "comment": "Healthcheck PMC"
      },
      "fullUrl": "Slot/slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
      "search": {
        "extension": [
          {
            "url": "https://example.org/fhir/StructureDefinition/slot-context",
            "valueAttachment": {
              "contentType": "application/json",
              "data": {
                "practitioners": [
                  "Gregory House"
                ],
                "locations": [
                  "Healthcheck PMC"
                ],
                "healthcareServices": [],
                "organization": "Healthcheck PMC"
              }
            }
          }
        ]
      }
    },
    {
      "resource": {
        "resourceType": "Slot",
        "id": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659",
        "status": "free",
        "start": "2026-05-30T16:00:00.0000000+00:00",
        "end": "2026-05-30T16:15:00.0000000+00:00",
        "comment": "Healthcheck PMC"
      },
      "fullUrl": "Slot/slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659"
    }
  ],
  "meta": {
    "page": 0,
    "nbPages": 1,
    "hitsPerPage": 20
  }
}

Use entry[].resource.id as the slotId.

listSlots(options?)

Example:

const response = await schedulerClient.listSlots({
  status: "free",
  specialty: "General Practice",
  page: 0,
  hitsPerPage: 20
});

Response:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 178,
  "entry": [
    {
      "resource": {
        "resourceType": "Slot",
        "id": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167439",
        "identifier": [
          {
            "system": "https://healthcheck.com/fhir/scheduling/ehr-id",
            "value": "a8d67eca330447c19c8cb49c6e3e0f19"
          },
          {
            "system": "https://healthcheck.com/fhir/scheduling/ehr-type",
            "value": "athena"
          },
          {
            "system": "https://athenahealth.com/appointmentid",
            "value": "3167439"
          }
        ],
        "schedule": {
          "reference": "Schedule/sched-26"
        },
        "status": "free",
        "start": "2026-05-30T17:00:00.0000000+00:00",
        "end": "2026-05-30T17:15:00.0000000+00:00",
        "appointmentType": {
          "coding": [
            {
              "system": "https://athenahealth.com/appointmenttypeid",
              "code": "1411",
              "display": "Telehealth Office Visit"
            }
          ],
          "text": "Telehealth Office Visit"
        },
        "serviceCategory": [
          {
            "coding": [
              {
                "system": "http://terminology.hl7.org/CodeSystem/service-category",
                "code": "17",
                "display": "General Practice"
              }
            ]
          }
        ],
        "comment": "Healthcheck PMC"
      },
      "fullUrl": "Slot/slot-a8d67eca330447c19c8cb49c6e3e0f19-3167439"
    },
    {
      "resource": {
        "resourceType": "Slot",
        "id": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167438",
        "status": "free",
        "start": "2026-05-30T16:00:00.0000000+00:00",
        "end": "2026-05-30T16:15:00.0000000+00:00"
      },
      "fullUrl": "Slot/slot-a8d67eca330447c19c8cb49c6e3e0f19-3167438"
    }
  ],
  "meta": {
    "page": 0,
    "nbPages": 9,
    "hitsPerPage": 20
  }
}

Use the slot id, for example slot-a8d67eca330447c19c8cb49c6e3e0f19-3167439, as slotId in appointment requests.

Providers

listProviders(publisherId?)

Response:

{
  "resourceType": "Bundle",
  "type": "collection",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Practitioner",
        "id": "prac-26",
        "identifier": [
          {
            "system": "https://athenahealth.com/providerid",
            "value": "26"
          }
        ],
        "name": [
          {
            "family": "House",
            "given": [
              "Gregory"
            ]
          }
        ],
        "gender": null,
        "communication": [
          {
            "coding": [
              {
                "system": "urn:ietf:bcp:47",
                "code": "en",
                "display": "English"
              }
            ]
          }
        ]
      },
      "fullUrl": "Practitioner/prac-26",
      "search": {
        "extension": [
          {
            "url": "https://example.org/fhir/StructureDefinition/provider-stats",
            "valueAttachment": {
              "contentType": "application/json",
              "data": {
                "slotCount": 178,
                "publishers": [
                  "8d0ba4f7574a43b48f9c307ef0410198",
                  "a8d67eca330447c19c8cb49c6e3e0f19"
                ]
              }
            }
          }
        ]
      }
    }
  ]
}

Provider response IDs:

• resource.id is the FHIR practitioner id, for example prac-26.
• resource.identifier[] with system https://athenahealth.com/providerid contains the Athena provider id, for example 26.
• search.extension[].valueAttachment.data.publishers[] contains publisher ids you can use to filter slots or providers.

Appointments

bookAppointment(request)

Request:

{
  "slotId": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
  "appointment": {
    "resourceType": "Appointment",
    "id": "appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
    "identifier": [
      {
        "system": "https://athenahealth.com/patientid",
        "value": "948363"
      }
    ],
    "status": "booked",
    "comment": "Healthcheck PMC",
    "participant": [
      {
        "actor": {
          "reference": "Patient/948363",
          "type": "Patient",
          "display": "Athena Patient 948363"
        },
        "required": "required",
        "status": "accepted"
      }
    ]
  }
}

Required IDs:

• slotId must be a fresh Slot.resource.id from a slot search/list response.
• appointment.id should be the FHIR appointment id you want to track, usually appt-${slotId}.
• The patient id is the Athena patient id. In this example it is 948363.

Response:

{
  "resourceType": "AppointmentResponse",
  "id": "cda421aa-4f24-4ace-ba76-3a87a984b0ba",
  "identifier": null,
  "appointment": {
    "reference": "Appointment/appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
    "type": null,
    "display": null
  },
  "start": "2026-05-30T14:00:00.0000000+00:00",
  "end": "2026-05-30T14:15:00.0000000+00:00",
  "participantType": null,
  "actor": null,
  "participantStatus": "accepted",
  "comment": "Appointment booked successfully"
}

After booking, use appointment.reference without the Appointment/ prefix as the route appointment id:

appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661

getAppointment(appointmentId)

Response:

{
  "resourceType": "Appointment",
  "id": "appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
  "identifier": [
    {
      "system": "https://athenahealth.com/patientid",
      "value": "948363"
    },
    {
      "system": "https://healthcheck.com/fhir/scheduling/ehr-id",
      "value": "a8d67eca330447c19c8cb49c6e3e0f19"
    },
    {
      "system": "https://healthcheck.com/fhir/scheduling/ehr-type",
      "value": "athena"
    },
    {
      "system": "https://athenahealth.com/appointmentid",
      "value": "3167661"
    }
  ],
  "status": "booked",
  "serviceCategory": null,
  "serviceType": null,
  "specialty": null,
  "appointmentType": null,
  "reasonCode": null,
  "description": null,
  "start": "2026-05-30T14:00:00.0000000+00:00",
  "end": "2026-05-30T14:15:00.0000000+00:00",
  "minutesDuration": null,
  "slot": [
    {
      "reference": "Slot/slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
      "type": null,
      "display": null
    }
  ],
  "created": "2026-05-29T16:18:11Z",
  "comment": "Healthcheck PMC",
  "participant": [
    {
      "type": null,
      "actor": {
        "reference": "Patient/948363",
        "type": "Patient",
        "display": "Athena Patient 948363"
      },
      "required": "required",
      "status": "accepted"
    }
  ]
}

rescheduleAppointment(request)

Request:

{
  "previousAppointmentId": "appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661",
  "slotId": "slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659",
  "appointment": {
    "resourceType": "Appointment",
    "id": "appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659",
    "status": "booked",
    "comment": "Rescheduled",
    "participant": [
      {
        "actor": {
          "reference": "Patient/948363",
          "display": "Athena Patient 948363"
        },
        "status": "accepted",
        "required": "required"
      }
    ]
  }
}

Required IDs:

• previousAppointmentId is the old FHIR appointment id, for example appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661.
• slotId is a new fresh free slot id, for example slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659.
• appointment.id should match the new appointment id you want to track, usually appt-${slotId}.

Response:

{
  "resourceType": "AppointmentResponse",
  "id": "6d24b49e-73da-432f-a8ff-802e569c4dbf",
  "identifier": null,
  "appointment": {
    "reference": "Appointment/appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659",
    "type": null,
    "display": null
  },
  "start": "2026-05-30T16:00:00.0000000+00:00",
  "end": "2026-05-30T16:15:00.0000000+00:00",
  "participantType": null,
  "actor": null,
  "participantStatus": "accepted",
  "comment": "Rescheduled from Appointment/appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167661"
}

cancelAppointment(appointmentId)

Use the FHIR appointment id in the route:

DELETE /appointments/appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659

Response:

{
  "resourceType": "AppointmentResponse",
  "id": "eeb152ec-3090-4c61-851b-ed594731e420",
  "identifier": null,
  "appointment": {
    "reference": "Appointment/appt-slot-a8d67eca330447c19c8cb49c6e3e0f19-3167659",
    "type": null,
    "display": null
  },
  "start": null,
  "end": null,
  "participantType": null,
  "actor": null,
  "participantStatus": "declined",
  "comment": "Appointment cancelled"
}

Publishers

listPublishers()

Returns the organizations that publish appointment slots.

{
  "resourceType": "Bundle",
  "type": "collection",
  "total": 2,
  "entry": [
    {
      "fullUrl": "Organization/org-healthcheck",
      "resource": {
        "resourceType": "Organization",
        "id": "org-healthcheck",
        "name": "Healthcheck PMC"
      },
      "search": {
        "extension": [
          {
            "url": "https://example.org/fhir/StructureDefinition/publisher-stats",
            "valueAttachment": {
              "contentType": "application/json",
              "data": {
                "publisherId": "a8d67eca330447c19c8cb49c6e3e0f19",
                "slotCount": 26,
                "freeSlotCount": 26,
                "practitionerCount": 1,
                "locations": ["Healthcheck PMC"]
              }
            }
          }
        ]
      }
    }
  ]
}

Use search.extension[].valueAttachment.data.publisherId to filter slots or providers by publisher.

System

sync()

Pulls fresh slot data from the EHR into the slot index. Call this before listing slots to ensure the index reflects the current Athena state.

{
  "id": 15,
  "status": "success",
  "started_at": "2026-05-29T12:21:29Z",
  "finished_at": "2026-05-29T12:21:38Z",
  "details": {
    "publishers": {
      "a8d67eca330447c19c8cb49c6e3e0f19": { "slots": 13 }
    },
    "totalSlots": 178,
    "errors": [],
    "mock": false
  },
  "mock": false
}

getStatus(limit?)

Returns the most recent sync history. Default limit is 20.

Notes

• Slot IDs are not stable after booking. Always search/list again before a new booking or reschedule.
• Appointment route IDs are FHIR appointment ids like appt-slot-..., not the UUID in AppointmentResponse.id.
• appointment.reference in AppointmentResponse includes the Appointment/ prefix. Strip that prefix when passing the value to getAppointment(...), cancelAppointment(...), or previousAppointmentId.
• Athena patient id must be carried in the appointment payload when booking or rescheduling.