Appointments represent a time booked with a medical provider to receive a service. There are a couple ways of interacting with appointments that will trigger a push into the health record system.
- Appointment creation
- Appointment confirmation
Reading Blocks
Schedule blocks are times where practices do not want any appointments to be booked. In NexHealth these are read as appointments with the
unavailable
property set to true.
Appointment Creation
POST requests to the /appointments
endpoint will insert a new appointment along with its patient, into the health record system. If at insertion time, the patient did not exist in the health record system, it will be created.
Inserting Appointments in the Past
Note that you can only insert appointments in the future. Only pass start_time fields with a value larger than today.
Before attempting to create a new appointment, you want to make sure you have the following:
availability
specifying that the provider and operatory can be booked see Availabilities.subdomain
andlocation_id
, see Institutions and Locations.patient_id
, see Patients.provider_id
, see Providers.start_time
, see Appointment Slots- appointment duration setting (see the Appointment Duration section below)
operatory_id
, if the locationmap_by_operatory
attribute istrue
see Operatories.
Monitoring Appointment Insertion
Because there is a small delay between when an appointment is created via API and when it syncs with the health record system, we recommend using the appointment_insertion webhook to verify that the appointment was correctly inserted.
Appointment Duration
Duration can be set manually by specifying an end_time
. End times can be inferred automatically if one of either category_id
or appointment_type_id
are supplied as parameters. See Appointment Categories.
Appointment Confirmation and Cancellation
PATCH requests that update the confirmed
and/or cancelled
boolean attributes to true
will trigger a command to change the confirmation status in the health record system. At this time, this is the only attribute of appointments that can be individually updated in the health record system via API.
The request body will simply look like this:
{
"appt": {
"cancelled": true
"confirmed": true
}
}
Updating Attributes on an Synced Appointment
If an appointment is synced with a heath record system, we will always keep the data in-sync with what is found in the data source. This means that other than appointment confirmations and cancellations, updating an attribute on an appointment will be undone upon the next synchronization event!
Appointments Response Object
{
"code": false,
"description": "Description",
"error": [
"Error"
],
"data": {
"appt": {
"id": 1822,
"patient_id": 2897,
"provider_id": 104,
"provider_name": "Dr. John Smith",
"start_time": "2020-06-05T20:16:57.007Z",
"confirmed": true,
"patient_missed": false,
"created_at": "2020-06-05T20:16:57.007Z",
"updated_at": "2020-06-05T20:16:57.007Z",
"note": "Patient showing flu symtoms already.",
"end_time": "2020-06-05T20:16:57.007Z",
"unavailable": false,
"cancelled": false,
"timezone": "America/New_York",
"institution_id": 1,
"appointment_type_id": 0,
"checkin_at": "string",
"location_id": 1,
"foreign_id": "94",
"foreign_id_type": "msg-dentrix-DataSource-100",
"misc": {
"is_booked_on_nexhealth": true
},
"last_sync_time": "2020-06-05T20:16:57.007Z",
"patient_confirmed": 0,
"created_by_user_id": 197,
"is_guardian": false,
"patient_confirmed_at": "string",
"cancelled_at": "string",
"is_new_clients_patient": false,
"confirmed_at": "string",
"sooner_if_possible": "string",
"operatory_id": 181,
"deleted": false,
"checked_out": false,
"checked_out_at": "string",
"referrer": "http://mypractice.com/book",
"is_past_patient": true,
"timezone_offset": "-4:00",
"patient": {
...
},
"procedures": [
{
...
}
],
"descriptors": [
{
...
}
],
"booking_details": {
...
}
}
},
"count": 2
}