TheFhirStorm

The healow scheduling API for eClinicalWorks practices

Vendor APIs · · Abhinav Srivastava

A practice that runs eClinicalWorks asks you to let its patients book visits from your app. You open the eClinicalWorks developer portal and it sends you elsewhere. Patient-facing and scheduling apps register on the healow developer portal. That portal states that scheduling APIs require a contract and a pricing review before production. The technical detail sits in the portal's getting started guide, mostly as sandbox instructions.

Registration

Create a healow developer account. Register a Scheduling App. The guide describes two steps: app information, then acceptance of the terms. The developer portal team reviews and approves the app. After approval, a Practices tab offers a Download Practices button that lists practices with FHIR enabled.

Production is a separate step. The portal lists the sequence: an eClinicalWorks practice creates a case, you sign the pricing agreement, and the practice works with an account manager on configuration. The developer agreement points to the eClinicalWorks certified EHR technology page for fees. The developer pages do not state the amounts.

Authentication

The scheduling calls do not use the SMART on FHIR flow that patient apps use. Every request carries a scheduling token: Authorization: Bearer {scheduling_token}. In the sandbox the guide shows the practice code and the scheduling token under a Scheduling Activated Practice entry, with an expiry date. The public documentation does not state how a production scheduling token is issued or rotated. The go-live steps route practice configuration through the account manager.

The booking sequence

The guide tells you to run the sandbox calls in this order: Schedule, Slot, Appointment. The sample URLs in the guide follow a FHIR-style path.

GET https://connect4.healow.com/apps/api/v1/fhir/{practice_code}/fhir/Schedule
GET https://connect4.healow.com/apps/api/v1/fhir/{practice_code}/fhir/Slot

Schedule request

Parameters: the practice code, actor (the provider NPI), date in YYYY-MM-DD with optional ge or gt prefixes, type (a visit type code, or none), identifier, and the actor location (a facility ID). The Slot request takes a schedule ID from this response.

Slot request

Parameters: the practice code, the schedule ID, slot-type, an optional start for paging (a date or a full timestamp), and _count up to 20. Open slots come back in pages of at most 20.

Appointment request

A POST with the patient and visit details. The guide lists these payload fields: family, given, telecom.phone, telecom.email, birthdate, address.text, reason, comment, description, language, insurance, race and ethnicity. The guide notes that comment is free text for the practice, not a FHIR comment element.

A successful booking returns a reservation message with a Reference ID and an encounter ID. If the slot was taken, the response is an error that includes the next available times. Store the encounter ID. Cancel and update calls need it.

Cancel, update and details

Cancel takes the practice code, the appointment ID, a payload and the token. The guide states that cancellation in production must be enabled by your account manager. For a visit booked by staff inside healow, you first find the appointment ID through the Encounter API.

Update Appointment can change the provider, the facility, the visit code, the visit status, or the date and time. A visit status change is allowed only while the appointment is in pending status.

Retrieve Details returns the link a patient uses to join a booked TeleVisit. It needs the practice code, the appointment ID, the visit type and additional info.

After a sandbox booking, the guide asks you to send healow the patient name and the booked times so they can verify the test appointment.

What a booking needs from you

Working back from the field list, a booking call depends on a practice code, a provider NPI and a facility ID to find a schedule, a visit type code, a slot ID from the Slot call, and the patient name, birth date, phone and email. The public documentation does not mark which payload fields are required and which are optional. Test each omission in the sandbox before you depend on it.

What the public docs leave out

  • Request and response schemas. The pages name fields but show no JSON bodies or response examples for the scheduling calls.
  • Error codes. Only the taken-slot case is described.
  • Production token issuance and rotation.
  • Rate limits for the scheduling endpoints.
  • Visit type codes and slot-type values. These are practice configuration. The public pages do not say how to list them.
  • Whether the Schedule and Slot responses are conformant FHIR R4 resources. The URL path contains fhir, but the API documentation page lists the scheduling calls as six request types outside the FHIR resource list.
  • Fees. The pricing agreement is signed before production and the amounts are on a separate eClinicalWorks page.

The healow FHIR R4 endpoints are a different thing. The portal's endpoint page states that the healow FHIR endpoint is for patient-facing apps only, and the API documentation describes those resources as read-only. Scheduling writes go through the scheduling token path above.

The TheFhirStorm Python and TypeScript connectors for eClinicalWorks are open source and cover the token and request plumbing.

All posts