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
- Appointment cancellation
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 creation
Please note that creating an appointment via the NexHealth API is asynchronous, therefore it is strongly recommended that you also subscribe to the appointment insertion webhook which will fires upon
complete
orfailed
response from an integration when inserting a patient appointment into an EHR.
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",
}
},
"page_info": {
"has_previous_page": false,
"has_next_page": false,
"start_cursor": "AAAAA",
"end_cursor": "BBBBBB"
}
}