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:

availabilityspecifying that the provider and operatory can be booked see Availabilities.
subdomain and location_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 location map_by_operatory attribute is true see Operatories.

❗️
Monitoring appointment creation
Please note that creating an appointment is asynchronous, therefore it is strongly recommended that you also subscribe to the appointment insertion webhook which will fires upon complete or failed 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

Please note that the associated entities listed below (patient, procedures, descriptors, booking details) are available if explicitly added to a call via the include[] parameter and will be included in the appointment_created and appointment_updated webhook payloads but these entities are excluded from appointment_insertion webhook payloads.

{
  "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
}