Level 2c - Appointment Types
Go back to the main guide here: https://docs.nexhealth.com/docs/scheduling-configuration-guide#/
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:
- Read the appointment types and procedure codes from the target health record system for a given appointment.
- 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.