Deprecated Provider Timeslots APIs

IMPORTANT NOTE

This documentation reflects a version of the API that is considered deprecated.

For the most up to date version of this API see our documentation for the v5/slots endpoint.

Provider Timeslots v4

Using information from the provider information above you will be able to construct a timeslot call.

There are two forms of timeslot call, one is for an individual provider and the other is a bulk call (which has a few more options).

The timeslot calls will provide all the information necessary to:

use the booking API to create an appointment
navigate the user into the DexCare booking flow

Max Lookahead Days

The EMR has a configured value of how far into the future it will return slots. It is an error to ask for slots beyond this date. To retrieve this date, you can use the following API.

	 /v2/lookups/maxLookaheadDays?visitTypeName=AdultPhysical
	                                   &epicInstanceName=org.customer.emr.instance
	                                   &product=yourUseCaseDescriptorHere

Please note that the line separations are to make reading the call easy and would not function if sent this way.

This will return a payload as follows:

 {
      "maxLookaheadDays": 0
 }

This indicates that the current date plus the value of maxLookaheadDays will be the last date that time slots can be requested.

Single Provider Call

The most simple of the calls to find a timeslot is the call to find timeslots for a single individual provider.

For this API call, you will supply the identifier of the provider as a path parameter and additional query parameters to specify the visit type and the timeframe in which to search for timeslots.

The product parameter is used to identify the source of the API call for debugging purposes.

In previous releases, the departmentId parameter was optional and only used only to select the correct timezone for the results, requiring an ehrSystemName parameter as well. If you have been updated to the latest version of the software, this parameter will now filter the returned results by department and the ehrSystemName is optional.

	 /v4/providers/{providerID}/timeslots?visitTypeId={visitTypeID}&departmentId={departmentID}     
	                                   &startDate={YYYY-MM-DDThh:mm:ss±hh:mm}       
	                                   &endDate={YYYY-MM-DDThh:mm:ss±hh:mm}          
	                                   &product={yourUseCaseDescriptorHere}

For example:

	 /v4/providers/999999999/timeslots?visitTypeId=55555&departmentId=88888888     
	                                   &startDate=2021-03-05T12:00:00-08:00        
	                                   &endDate=2021-04-04T12:00:00-07:00          
	                                   &product=myorg_mobileapp

Note that the time portion of the startDate and endDate are ignored.

(ISO 8601 date format used by the API requires a time to have a timezone)

Below is a sample output payload:

	 {
	    "providerNationalId":"1417026030",
	    "providerId":"WM1232",
	    "timezone":"America/Los_Angeles",
	    "startDate":"2021-03-05",
	    "endDate":"2021-04-04",
	    "scheduleDays":
	       [
	          {
	             "date":"2021-03-05T12:00:00-08:00",
	             "providerNationalId":"1417026030",
	             "providerId":"WM1232",
	             "timeSlots":[]
	          },
	          {
	             "date":"2021-03-06T12:00:00-08:00",
	             "providerNationalId":"1417026030",
	             "providerId":"WM1232",
	             "timeSlots":
	                [
	                   {
	                      "providerNationalId":"1417026030",
	                      "providerId":"WM1232",
	                      "id":"base64 slot ID",
	                      "slotDateTime":"2021-03-06T09:30:00-08:00",
	                      "departmentId":"3100035001",
	                      "departmentIdentifier":"org.yourorg.epic.yourdept|4210000000",
	                      "slotType":"Returning",
	                      "duration":30,
	                      "visitTypeId":"122859"
	                   },
	                   {
	                      ...
	                   }
	                ]
	           }
	           ...
	      ]
	 }

There are several things to note in the returned payload.

startDate: startDate is not guaranteed to be the same as the dates requested. If your health system has a buffer set for digital scheduling the DexCare platform will mirror this (a configured setting in the DexCare platform). If you health system as a buffer of 3 days and a request is made for a startDate of today, the returned startDate will be today plus the 3 day buffer.
endDate: endDate will be the requested endDate unless it exceeds the EMR configured lookahead days for requesting slots. This EMR configured value is not the span between startDate and endDate but is the number of days from today that slots are available. So, even asking for a time range of three days that span this future date will fail.

Note that date fields are ISO 8601 compliant date-time fields so that they include a time zone.

scheduleDays: every day in the span returned will have an entry in the scheduleDays array. In the example above the first requested date for time slots, 03/05/2021, does not have any available slots.
The next entry, 03/06/2021, has two entries (data for just the first). The slot description has all the information to properly display the slot to the user and for booking the slot.

Batch Provider Call / Next N Slots

This call serves two purposes. The first is if you have more than 1 provider for which you wish to get timeslots. The other is when you want a set number of slots and not the slots between a date range. It accepts a date range too.

There are use cases where retrieving a set number of slots is desirable, even if just for one provider. For example if you have a user interface with a scheduling widget that shows only 8 slots at a time, then getting a large payload of 100s of slots may not be desirable when what you want is just the next eight available.

	 /v3/timeslots?providerId=8888888&providerId=99999999
	           &visitTypeId=1000003
	           &startDate=2021-02-22
	           &endDate=2021-04-14
	           &maxSlots=5
	           &product=yourUseCaseDescriptorHere

Note that the list of providers is sent in a repeating list of providerId parameters.

This call works for only a single visit type.

Even though the call contains a start and end date these will be ignored because the maxSlots parameter is also being sent. It would function without the dates being sent too.

The returned payload is different than the previous payload to limit the size of the returned payload.

	 {
	   "providers": 
	   {
	       "8888888": 
	       {
	         "slots": 
	           [
	              {
	                 "date": "2021-03-09",
	                 "time": "08:00:00",
	                 "duration": 30,
	                 "visitTypeId": "1000003",
	                 "timezone": "America/Los_Angeles",
	                 "departmentId": "3100035001",
	                 "slotType": "NewPatient"
	             },
	             {
	                 ...
	             },
	             {
	                 ...
	             },
	             {
	                 ...
	             }
	          ]
		    },
	      "99999999": 
	      {
	         "slots": [ ]
	      }
	   }
	 }

The returned payload reveals that provider 8888888 has only 4 slots of visit type 1000003 between today and the max lookahead range (remember that the start and end date are ignored). The other requested provider has no available slots of this visit type.