In Happy Smiles Dental - Configuration 2 you saw that lunch is modeled as the absence of a working hour. There is a 9:00 - 12:00 working hour, a gap in between, and a 1:00 - 5:00 working hour. That's one way to make time unbookable. There's another way to do this.

Practices can place dedicated calendar unavailabilities (often called events or blocks) on the schedule. These are discrete blocks of time on a provider's calendar that mark the time slot as unavailable and are configured directly in the target health record system.

Instead of splitting a working hour record, the office adds a block onto the calendar (a staff meeting, a team huddle, a recurring admin hour) and the Synchronizer API treats that block as an unavailable appointment. The slot is automatically excluded from /available_slots.

The Synchronizer API returns these blocks as an unavailable appointment (unavailable is true) through the /appointments endpoint as they are scheduled breaks on the calendar.

Example response from /appointments:
Response (trimmed)

{
  "code": true,
  "description": null,
  "error": null,
  "data": {
    "id": 1484450509,
    "patient_id": null,
    "provider_id": null,
    "provider_name": null,
    "start_time": "2026-07-07T16:00:00.000Z",
    "end_time": "2026-07-07T17:00:00.000Z",
    "unavailable": true,
    "cancelled": false,
    "location_id": 21241,
    "foreign_id": "block_47",
    "foreign_id_type": "remote_db-opendental-DataSource-9326",
    "misc": {},
  },
  "count": null
}

Two fields are the markers:

• patient_id is null - no patient is associated with the block
• unavailable is true - the slot is explicitly marked as unbookable

When /available_slots derives bookable time, it filters out any window that overlaps with a record where unavailable: true. You don't need to filter these out yourself.

This concept is source-agnostic. Calendar unavailabilities exist whether the practice uses manual or synced configuration.

Dentrix

For Dentrix event blocks are recognized as calendar unavailabilities.

Open dental

For Open dental non-scheduling blockouts and holidays are recognized as calendar unavailabilities.

Eaglesoft

For Eaglesoft, closed chairs (enabled upon configuration request) and time blocks are recognized as calendar unavailabilities.

A working hour record tells you when a provider is available. It doesn't tell you what they can be booked for. That's the job of appointment types.

For example, in Happy Smiles Dental - Configuration 2 the office needs to start booking specific kinds of appointments. They define Cleaning (30 minutes), Exam (15 minutes), and Root Canal (60 minutes) as NexHealth appointment types. When your product asks the patient "what are you scheduling for?", these are the categories it offers.

There are two related concepts here, and the distinction matters: NexHealth appointment types are categories defined only inside NexHealth. Appointment descriptors are the EHR's native appointment types and procedure codes, read directly from the practice's system.

NexHealth appointment types

These are a NexHealth construct. They are not read from or written to the target EHR. You create them through the API to define what kinds of appointments a provider can serve, how long each takes and when patients can book for certain appointment types.

Configure

POST to /appointment_types:

curl -X POST 'https://nexhealth.info/appointment_types?subdomain=YOUR_SUBDOMAIN' \
  -H 'Nex-Api-Version: v20240412' \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_type": {
      "name": "Cleaning",
      "minutes": 30,
      "bookable_online": false
    },
    "location_id": YOUR_LOCATION_ID
  }'

minutes is the duration the appointment occupies. This is what determines slot length when the type is requested.

NexHealth appointment types can then be assigned to a working hour record to define what types of appointments a provider can be booked for. You can bind these appointment types by including appointment_type_ids when creating or editing a working hour record.

For the full field reference, see the appointment types documentation.

Appointment descriptors (EHR-specific)

For supported health record systems, the API also surfaces the EHR's native appointment types and procedure codes through appointment descriptors. Descriptors are read from the EHR.

They have two use cases:

1. Read the appointment types and procedure codes from the target health record system for a given appointment.
2. Write appointments into the EHR with specific procedure codes or appointment types.

Descriptors matter when a posted appointment needs to land in the EHR with a specific code that the practice's downstream systems depend on. For example, a D1110 — Prophylaxis Adult code for the billing system, or a procedure code that drives recall messaging and patient outreach.

Retrieve

GET /locations/{id}/appointment_descriptors returns all the possible descriptors available for a given location. See the appointment descriptors documentation for the full reference.

Map an appointment descriptor to a NexHealth appointment type

Once you've identified the descriptors you want, PATCH the NexHealth appointment_type record to associate it. Subsequent posted appointments with the appointment_type_id included will include the EHR specific procedure codes or appointment types directly in their system.

curl -X PATCH 'https://nexhealth.info/appointment_types/YOUR_APPOINTMENT_TYPE_ID?subdomain=YOUR_SUBDOMAIN' \
  -H 'Nex-Api-Version: v20240412' \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "appointment_type": {
      "emr_appt_descriptor_ids": [9816179, 9815469]
    },
    "location_id": YOUR_LOCATION_ID
  }'

For a full guide please see: https://docs.nexhealth.com/v20240412/docs/access-procedure-codes

Example

Happy Smiles Dental - Configuration 2 needs to start booking specific kinds of appointments. They define Cleaning (30 minutes), Exam (15 minutes), and Root Canal (60 minutes) as NexHealth appointment types. When your product asks the patient "what are you scheduling for?", these are the categories it offers.

Inside the target health record system, the practice already has its own appointment types and procedure codes used for billing: D1110 — Prophylaxis Adult for the cleaning, D0150 — Comprehensive Oral Evaluation for the exam, D3310 — Endodontic Therapy for the root canal.

These codes are commonly shared across practices, but their NexHealth IDs may differ in the API by location. These are appointment descriptors that are read in from the target health record system, not created in NexHealth.

For example, you can configure NexHealth Appointment type Cleaning to map to the descriptor D1110 — Prophylaxis Adult so that when an appointment is posted, it lands in the target health record system with the correct billing code.

Gotchas

Appointment Types and Appointment Descriptors are different things, easy to conflate.

A name on a NexHealth appointment type ("Cleaning") and an EHR appointment type ("New Patient Cleaning") may overlap conceptually but they're separate records in separate systems. The NexHealth appointment type categorizes the appointment for scheduling; the descriptor controls how the appointment is written into the EHR. Treat them as independent entities.

Forgetting to map a descriptor.

An appointment POSTed without a mapped descriptor will land in the EHR using the practice's default appointment type, which may not match what your application intended and the office would need to manually make the appropriate changes in their target health record system. If the practice's billing depends on specific procedure codes you may want to include those in your posted appointments.

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.