Book an Appointment

This guide will help you use the NexHealth Synchronizer API to book an appointment for a new or existing patient. The NexHealth Synchronizer API makes it easy to embed online booking into your application and start driving more revenue for practices.

This guide is written with the assumption that you already have created your NexHealth Developer Portal Account, generated your test API key, and have your bearer token ready.

We've also put together an accompanying video tutorial below. Note that you should be able to generate an API key yourself within the Developer Portal instead of requesting access.

Overview

To book an appointment you need to understand the who, what, where, and when of the booking.

Who: The patient who is attending the appointment and the provider who will be providing care.
What: What kind of appointment is being booked
Where: What location the appointment will occur in.
When: What time the appointment should occur.

Who

To avoid creating duplicate patients in a practice's health record system, you should always look for an existing patient before creating an appointment. You can do this with a Get request to the /patients as shown below.

Make sure to fill in your subdomain, location, and bearer token.

curl --request GET \
     --url 'https://nexhealth.info/patients?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION&new_patient=false&include_upcoming_appts=false&location_strict=false&page=1&per_page=5' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

You will get back a response as shown below. Make sure to pick a patient you'd like to book an appointment with and store their ID.

{
  "code": false,
  "description": [
    [
      "Description"
    ]
  ],
  "error": [
    [
      "Error"
    ]
  ],
  "data": [
    {
      "patients": [
        {
          "id": 415,
          "email": "[email protected]",
          "first_name": "John",
          "middle_name": "Anthony",
          "last_name": "Smith",
          "name": "John Smith",
          "display_name": "John Smith",
          "doctor_name": "Dr. John Smith",
          "meta_type": "Dentist",
          "created_at": "2020-06-05T20:16:57.007Z",
          "updated_at": "2020-06-05T20:16:57.007Z",
          "profile_url": "https://storage.googleapis.com/nexassets/app/img/icon/avatar.svg",
          "foreign_id": 0,
          "foreign_id_type": "--DataSource-",
          "npi": "string",
          "inst_ids": [
            [
              1,
              2
            ]
          ],
          "bio": {
            "phone_number": "5163042196",
            "date_of_birth": "1964-05-03"
          },
          "unsubscribe_emails": true,
          "inactive": false,
          "last_sync": true,
          "last_sync_time": "string",
          "unsubscribe_sms": true,
          "last_check_in": "2020-06-05T20:16:57.007Z",
          "prov_ids": [
            [
              504
            ]
          ],
          "invalid_email": [
            [
              ""
            ]
          ],
          "contact_email": "string",
          "guarantor_id": 0,
          "pcp_id": 504,
          "last_visit": {},
          "upcoming_appts": [
            {
              "id": 1822,
              "provider_id": 102,
              "provider_name": "Dr. John Smith",
              "start_time": "2021-12-06T09:45:00.000Z",
              "end_time": "2021-12-06T10:00:00.000Z",
              "location_id": 1,
              "confirmed": true
            }
          ]
        }
      ]
    }
  ],
  "count": 2
}

If you would like to book an appointment for a new patient, create a new patient with a Post request and store the newly created patient ID.

Next we have to pick a provider. You can do this with a Get request to /providers as shown below.

Make sure to fill in your subdomain and bearer token.

curl --request GET \
     --url 'https://nexhealth.info/providers?subdomain=YOUR_SUBDOMAIN&page=1&per_page=5' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Make sure to pick a provider you'd like to book an appointment with and store their ID for later.

What

To book an appointment via NexHealth you have to specify what kind of appointment it is via our appointment types. You can use appointment types to control the length of the appointment as well as what procedure codes are mapped to that appointment when created.

To create an appointment type you can make a Post request to /appointment_types as shown below.

Make sure to fill in your subdomain, location, and bearer token.

curl --request POST \
     --url 'https://nexhealth.info/appointment_types?subdomain=YOUR_SUBDOMAIN' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "appointment_type": {
          "name": "New Patient",
          "minutes": 30,
          "parent_type": "Location",
          "parent_id": YOUR_LOCATION_ID
     },
     "location_id": YOUR_LOCATION_ID
}
'

In the response you will get back an appointment type ID. Keep track of that for later.

Where

You should have received a location ID with your API key. Each location represents a physical office. If you don't have the location ID handy you can query all locations within your subdomain with a Get request to /locations as shown below.

Make sure to fill in your subdomain and bearer token.

curl --request GET \
     --url 'https://nexhealth.info/locations?subdomain=YOUR_SUBDOMAIN' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

Now you have the location where the appointment will be booked.

If you only want to surface appointments in a specific room you can query the operatories in your location as shown below with a Get request to /operatories.

Make sure to fill in your subdomain, location, and bearer token.

curl --request GET \
     --url 'https://nexhealth.info/operatories?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION&page=1&per_page=5' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

When

To use online booking, you MUST have availabilities configured. Availabilities may either read in from the EHR or may be created manual via the /availabilities endpoint (to understand if NexHealth supports synced provider availabilities, please refer to our feature parity sheet or reach out to [email protected]). Availabilities allows you to ensure that providers are only being booked for appointments during the hours and operatories/columns that they want them.

You can create an availability with a Post request to /availabilities. There is a body object to attach this time, where you specify that this availability is Mondays and Tuesdays from 9-5 with the provider, and appointment type you decided on earlier.

As always make sure to fill in your subdomain, location, type ID, and bearer token.

curl --request POST \
     --url 'https://nexhealth.info/availabilities?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "availability": {
          "days": [
               "Monday",
               "Tuesday"
          ],
          "appointment_type_ids": [
               YOUR_TYPE
          ],
          "active": true,
          "provider_id": YOUR_PROVIDER,
          "begin_time": "09:00",
          "end_time": "05:00"
     }
}

Now you can use our utility endpoint, Get /appointment_slots to return available slots for the provider and location you decided upon above.

Make sure to fill in your provider, location, start_date, subdomain, location, and bearer token.

curl --request GET \
     --url 'https://nexhealth.info/appointment_slots?subdomain=YOUR_SUBDOMAIN&start_date=2021-04-18&days=10&lids\[\]=YOUR_LOCATION&pids\[\]=YOUR_PROVIDER' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN'

You should get a response like the one below with times that are available to be booked. Pick one noting the time and operatory ID and lets create this appointment!

{
  "code": false,
  "description": [
    [
      "Description"
    ]
  ],
  "error": [
    [
      "Error"
    ]
  ],
  "data": [
    {
      "lid": 1,
      "pid": 0,
      "operatory_id": 54,
      "slots": [
        {
          "time": "2017-10-09T07:00:00.000-04:00",
          "operatory_id": 0,
          "provider_id": 83
        }
      ]
    }
  ],
  "count": 2
}

Creating an appointment

Putting it all together you can create an appointment with a Post request to /appointments.

Make sure to include everything you pulled above subdomain, location, bearer token, patient, provider, type ID, operatory, and start time.

curl --request POST \
     --url 'https://nexhealth.info/appointments?subdomain=YOUR_SUBDOMAIN&location_id=YOUR_LOCATION&notify_patient=false' \
     --header 'Accept: application/vnd.Nexhealth+json;version=2' \
     --header 'Authorization: Bearer YOUR_BEARER_TOKEN' \
     --header 'Content-Type: application/json' \
     --data '
{
     "appt": {
          "patient_id": YOUR_PATIENT,
          "provider_id": YOUR_PROVIDER,
          "operatory_id": YOUR_OPERATORY,
          "start_time": "YOUR_STARTTIME"
          "appointment_type_id": YOUR_TYPE
     }
}
'