Online Appointment Scheduling

The following is an explanation of common workflows for finding open appointment slots within athenaNet that are available to be booked via the API. It is important to note that not all appointment slots are made available by practices for scheduling via the API. Patients should be presented with a choice of appointment reasons, as represented by a reason and description returned from the /patientappointmentreasons call.

The typical workflows are below. The links below document the output of each of these calls. The input parameters can be most easily seen in the I/O Docs.

Please note that patients may not recognize if they are "new" or "existing" (which is the basic difference in step 5 of the workflows below). The patient experience shouldn't indicate if the patient was found or not, unless you are collecting sufficient information from the patient for a 100% positive match using /patients/ (or /patients/bestmatch, though the former is better at looking for exact positive matches).


Common to both New and Existing Patients

  1. Use the following API to get a list of departments at a practice. While this information can be cached, be aware that it does change from time to time.
  2. Use GET /providers to get a list of providers. Again, this is cachable for a period of time, but can change.
  3. Use the following API to narrow down a specific appointment reason. You can use reasontype (or /patientappointmentreasons/existingpatient or /patientappointmentreasons/newpatient) to limit to the patient reasons.
  4. Use open appointments API with a reason ID, department and provider (and date range) to retrieve a set of open appointments.

New Patients

       5. POST to /patients to create a new patient and get a patient ID. You must supply first and last name, a DOB, department ID, and at least one patient phone number (home, mobile, work).

       6.  Use the following API to book a patient, which will require the patient ID (from step 5), a reason ID (asked from the patient using the list from step 3), and an appointment ID (found in step 4).


Existing Patients

      5.  Use a GET to /patients to find the patient ID. There are certain minimum search criteria that must be met to find a patient: first and last name, date of birth, and at least one other demographic field (phone number, SSN, etc.). Refer to the detailed documentation for /patients.

       6. Use the following API to book a patient, which will require the patient ID (from step 5), a reason ID (asked from the patient using the list from step 3), and an appointment ID (found in step 4).


Important Notes


What is an appointment reason?  What is an appointment type?

We introduced the notion of an appointment reason (i.e. /patientappointmentreasons) as a way for practices to use a relatively short list of reasons that a patient might be coming in for a visit. The list of possible reasons is global, and a practice can elect to use any subset of those reasons. Additionally, an appointment reason can be designated as being for new patients only, existing patients only, or for all patients. Appointment reasons are also used by patients of our clients via the Communicator portal for scheduling, and there are several attributes that are set administratively at the appointment reason level (such as how long before the appointment can it be booked online, etc.). The reasons are meant to be patient-facing and a description can be provided for additional detail for the patient.  

We encourage the API user to ask if the patient is new or existing, present a list of applicable appointment reasons to the patient to select from, and query for slots for that particular reason. We do support asking for more than one appointment reason at a time; in this use case, you might pass in, for example, all of the reason IDs related to new patient appointment reasons (from /patientappointmentreasons/newpatient, for example) and the result set would have all possible slots, including the available reason IDs that could be used for that particular slot. (As a fair warning, this call is relatively expensive compared to other calls since it is equivalent to calling the API for each of the reasons passed in. You may want to consider shorter date ranges or even caching the response.) Finally, as an alternate approach, the full set of appointments can be queried initially (using the special -1 reason ID) and later restricted after finding out more about the patient (new/existing and reason). Using the special -1 reason ID, while faster, does not provide the details about which reasons are available for a given slot.

Behind the scenes, an appointment reason is mapped to an underlying appointment type. Appointment types are more familiar to practices since they are used when practices book appointments in the office. However, practices often have a multitude of appointment types for very similar appointments. It is not uncommon to see one department use the appointment type of "PHYS30" for physicals and another department to use "PHYS45". Practices can configure the combination of department, provider, and appointment reason to map to a specific appointment type, allowing the same reason ("Physical," to continue this example) to result an underlying appointment type of either "PHYS30" or "PHYS45" depending on the department or provider. In addition, multiple appointment reasons can be configured to map to the same underlying appointment type.

For Web-based scheduling, the appointment reason should be used; it allows the same reason to be used across departments and providers without the patient needing to know the details about the underlying (and not always patient friendly) appointment type. Open appointment slots available for Web-based scheduling are queried by the reason ID.

Bypassing permissions

When should the "ignoreschedulablepermission" and "bypassscheduletimechecks" flags be used?

The open appointment slots functionality was designed around the use case of a patient scheduling an appointment online and, by default, looks for appointment reasons and obeys the practice's configuration around those appointment reasons. (This configuration is generally done as part of the Communicator setup.) In cases where scheduling is being done for other reasons (e.g. telemedicine, walk-in appointments via Digital Check-in, or other use cases), you may wish to book by appointment type and you may also want to ignore the setup that was done controlling what appointments can be booked. There are two flags that allow the API user to bypass the permissions set up around Web scheduling.

The first, "ignoreschedulablepermission", allows you to ignore the setup about which appointment types (as mapped to from appointment reasons) are available and, when set to true, will retrieve all appointment slots that are available without regard to the appointment reason setup. The other setting to use in this situation is "bypassscheduletimechecks". Setting this to true will allow you to get appointment slots that are either soon (default configuration is 24 hours) or far from now (default is 90 days). If you use these flags to retrieve open appointment slots, you must also use the same flags when booking the appointment (PUT /appointments/{appointmentid}).

What is a frozen appointment slot?

There are times when a user may want to temporarily prevent any appointment from being scheduled into a specific open slot, but not necessarily want to remove that slot completely from the schedule. In this case (or for other use cases where this behavior is desirable), an appointment slot can be marked as "frozen." Frozen slots are not returned in the result set of an /appointments/open GET call (unless you specifically request to show them, using the "showfrozenslots" argument). To freeze a slot, call /appointments/{appointmentid}/freeze PUT. An open appointment slot can later be unfrozen in order to free it up for scheduling (also by using /appointments/{appointmentid}/freeze PUT, but with different arguments). 

Booked appointment slots can also be frozen. Frozen booked slots will always display in the result set of the /appointments/booked GET call (however, frozen booked slots will have the attribute "frozen" set to true). Frozen booked slots have an effect on what happens to the booked time when an appointment is cancelled. Depending on a number of factors, when a booked appointment is cancelled, a new open slot is created in its place to make that time available once again for booking future appointments. However, if that booked slot was frozen when it was cancelled, the new open slot (if created) will be created as a frozen open slot.

Note: /appointments/{appointmentid}/freeze is being provided on a temporary basis for our partners that have a immediate need for this behavior and no viable workaround. As we improve our scheduling model, this "frozen" concept should ultimately go away. We advise against building any major functionality around this resource, as it is intended as a stopgap.

Outbound Communications

Reminder and confirmation emails and calls tied to a Web-scheduled appointment are handled solely by athenaNet via Communicator functionality. Partners should not expose their product functionality to message clients about booked appointments, as it conflicts with core athenaNet features.

Additional Notes

  • Appointmentid values are NOT unique across practices; they are unique only to the individual practice ID being queried.
  • When you call PUT /appointments/{appointmentid}, all of the insurance information (fields that start with "insurance" and "patientrelationshiptopolicyholder") is optional. Today, this generates a document (a patient case) in the practice's workflow with that information and it must be worked on manually. In the future, we will be using that information to determine the actual insurance and eligibility for the patient. While other calls have insurance information in the output, these are generally not used for the appointment booking workflow; they are useful for Digital Check-in purposes.
  • Once an appointment has been booked, you can cancel or reschedule an appointment using the /appointments/{appointmentid}/cancel or /appointments/{appointmentid}/reschedule calls. If you cancel an appointment, the appointment notes associated with the cancelled appointment will no longer surface via the API unless you turn on the SHOWDELETED flag.  One thing to note is that if you schedule a new appointment that replaces the cancelled one (ie. cancel and reschedule),  the appointment notes will be moved over to the new appointment.  
  • To minimize duplicate patients being created, we actually attempt to determine on the backend if a patient already exists during a POST to /patients. In essence, a POST to /patients actually does a GET /patients/bestmatch and a little bit of additional duplicate matching logic and returns a patient ID which might actually be for an existing patient in the system. For purposes of the API, however, you can ignore this detail and simply use the patient ID returned from POST to /patients, regardless of whether it actually created a new patient or not.
  • For new patients, a new patient case is created upon appointment booking, unless the nopatientcase flag is set to true, that can contain the patient’s insurance and notes entered into the partner’s application. This process gives practices the ability to see new patients in their workflow. Practices may elect (via a setting) to also create patient cases for existing patients who book appointments via the API (or athenaCommunicator's portal).
  • When creating or updating a patient record, you will find that athenaNet will ignore bad phone numbers. For example, if a patient enters in 617-555-1212 as the home phone, athenaNet will not populate this phone number because 555 is not a valid phone number.   
  • If you are looking to replace an HL7 SIU message to track changed appointment information for your client with an API solution, you will want to look at the appointments/Changed  API calls. See the Changed Data Subscriptions page for more details.
  • As noted in the Providers documentation, an individual provider may have multiple provider IDs (as defined by a unique NPI) in athenanet. This occurs typically when the provider practices across multiple departments. We have combined these multiple provider IDs into a single canonical ID which is used for processing API calls, even if one of the provider’s other IDs is submitted. Partners will only need to refer to a provider using their canonical ID which can be found via the GET /providers and GET /providers/{providerid} API.
  • In certain exceptional circumstances the practice will create more than one record for a provider within a single department and the same provider group. In these unique situations, the GET /appointments/open, GET /appointments/booked, and GET /appointments/booked/multipledepartment APIs will return appointments for the specific provider ID that is submitted.
  • The Practice Setting "Walk-In Encounter Management" must be turned on for Urgent flags to be supported at a practice.
Was this information helpful? Yes | No Thank you for your feedback! What went wrong? Incomplete or incorrect information | Irrelevant Content | Others

On this Page