Level 2d - Under the hood: how slots are derived

📌

Go back to the main guide here: https://docs.nexhealth.com/docs/scheduling-configuration-guide#/

You now have all three inputs: working hours (when a provider is available), calendar unavailabilities (when a provider explicitly is not available), and NexHealth appointment types (what type of appointment a provider can be booked for). The /available_slots endpoint utilizes these inputs in order to calculate available time slots.

Going back to Dr. Patel from Level 2a, they have a 9:00–12:00 morning block and a 1:00–5:00 afternoon block in Operatory 1. Now layer on what a real day looks like: he has a booked appointment from 8:00–9:00, a calendar block from 9:00–11:00, a lunch break from 12:00–1:00, and the rest of the afternoon is open.

Three things drive what /available_slots returns:

1. The request window. start_date plus days defines the range. The endpoint looks at every working hour record that falls inside that window.
2. Working hours as the source of truth. Within the window, the endpoint uses Dr. Patels's /working_hours records to determine when he's working. Anything outside those records isn't a candidate.
3. appointment_type_id narrows scope and sets slot length. Passing appointment_type_id tells the endpoint two things: what slot length to use (the appointment type's minutes value), and which working hour records to consider (only those associated with that NexHealth appointment type).

Example

If the 9:00–12:00 block is assigned Cleaning and the 1:00–5:00 block is assigned Exam, a request for Cleaning availability only evaluates the 9:00–12:00 window. The afternoon never enters the calculation. With Cleaning set to 30 minutes, the endpoint returns 30-minute slots minus the 9:00–11:00 calendar unavailability. This means 11:00 and 11:30 come back as bookable from the /available_slots endpoint response.

Where appointment descriptors come in

Slot calculation is one thing. Writing the appointment to the EHR is another.

When a patient books one of those 11:00 cleaning slots, the appointment lands in the target health record system associated with the D1110 — Prophylaxis Adult descriptor that the Cleaning NexHealth appointment type was mapped to in Level 2c.

Nexhealth appointment types abstract the scheduling logic. Descriptors localize the EHR write. Slot calculation doesn't care about descriptors, they only matter once an appointment is being inserted into the target system.

Retrieve slots

A GET /available_slots request now spans more providers and more operatories. The response groups slots by pid (provider)and lid
(location id):

Response (trimmed)

"data": [
    {
      "lid": 21241,
      "pid": 158936025,
      "slots": [
        {
          "time": "2026-05-07T11:00:00.000-07:00",
          "end_time": "2026-05-07T11:30:00.000-07:00",
          "operatory_id": 1,
          "working_hour_label_id": null
        },
        {
          "time": "2026-05-07T11:30:00.000-07:00",
          "end_time": "2026-05-07T12:00:00.000-07:00",
          "operatory_id": 1,
          "working_hour_label_id": null
        }
      ]
    },
    }

Gotchas

Multiple provider operatory assignment

When you query /available_slots without specifying an operatory_id, the API returns slots for only the first available operatory, even if the provider has availability in multiple operatories. This means without specifying operatory_id then the /available_slots endpoint would only return Dr. Patels’s availability for one of his configured operatories. To get accurate, complete availability, always specify operatory_id in your query parameters if you need operatory-specific availability.

Working hour records have no appointment type assigned by default.

A request to /available_slots that includes appointment_type_id will return no available time slots if no working hour record is associated with that type. The endpoint isn't broken, it's correctly reporting that the provider has no working hours assigned to that appointment type. Map the type to the working hour record before searching for available time slots by appointment_type_id.