Provider Direct Time Slots

This page walks through the process of booking a patient with primary care providers and specialists through calls to our provider API and timeslot endpoints.

The following order of operations will be used to book an appointment time slot with a provider

  1. List the available providers using our provider APIs
  2. Retrieve available time slots for a specific provider
  3. Retrieve patient identifying information using our patient APIs
  4. Book the time slot for a provider with our booking API

Listing Providers

Typically a client application will provide end users with a list of providers.

From this list, available appointment time slots for a specific provider or set of providers can retrieved based on the providers’ National Provider ID (NPI).

Typically this list of providers would be rendered:

  1. On a list of providers on the health systems “Find A Doctor” section
  2. A primary care office web page that has the list of providers
  3. A list of all providers which support digital scheduling through the DexCare platform.

If you are implementing the third option, you would issue a call to the following endpoint:

GET v1/providers?product=yourUseCaseDescriptorHere

Parameters

excludeInactive

Option to filter providers to include or exclude providers that are that are inactive (e.g., to retrieve active providers, set this parameter to false )

type: query    
default: N/A    
values: true   false

acceptingNewPatients

Option to filter providers to include or exclude providers that are accepting new patients (e.g., to retrieve only providers accepting new patients, set this parameter to true )

type: query    
default: N/A    
values: true   false

Responses

The returned payload is a list of the providers.

To accommodate health systems that have more than one EMR the data will be returned in a JSON payload that looks like:

	 {
	     "system":"org.customer.emr.instance",
	     "npi":"999999999"
	 }

If there are 500 providers participating in digital scheduling then there will be 500 of these JSON structures returned.

From these lists, it is the National Provider Identifier (NPI) that will be used in the next step.

Retrieving Provider Information

Once you have an NPI you are ready to make the call to get the provider information.

The URL for call is:

	 /v3/providers/{npi}?product={yourUseCaseDescriptorHere}

or

	 /v3/providers/{emr system name}|{npi}?product={yourUseCaseDescriptorHere}

for example:

	/v3/providers/org.customer.emr.instance|999999999?product=my_org_mobileapp

In the second case the NPI is prepended with your EMR instance identifier with a pipe (|) character delimiting the two values.

These two calls return the same payload.

However, by including the EMR information you are instructing the system to call the EMR for additional information.

The first call returns the data that the DexCare platform stores which is used to support digital scheduling. This encompasses just the information needed to continue the booking process.

If you want a superset of this information for displaying things like an image, which might be stored (referenced) in Epic, then you should make the second call.

The following is the payload returned. Data that comes from the EMR is indicated.

{
  
  "minAge": 0, 
  "name": "John Doe", 
  "credentials":"M.D.",                                                 // Overridden by EMR
  "providerGender": "M", 
  "acceptingNewPatients": false, 
  "imageURL":"https://providerassetdirectory-JohnDoe.jpg",              // From EMR
  "specialty":["Family Medicine"],                                      // Overridden by EMR
  "subSpecialties": [], 
  "departments": [
    {
      "ehrSystemName": "org.customer.emr.instance", 
      "name": "Acme Family Medicine", 
      "brand": "Acme", 
      "supportedVisitTypeIds": [
        "e9314950-10e8-4250-bf15-8caf0a9a50cc", 
        "c4f4c99a-d4c5-4296-8f97-16236b23678c", 
        "917de50e-5f6f-428a-95a4-c8d858e65934", 
        "173a34f5-d671-4c0e-807f-094d0b6d3896", 
        "8bd07581-95a1-4603-8d1c-39b6dd84e613"
      ], 
      "departmentUrlName": "ACME", 
      "departmentId": "e6b46851-fb2f-46e8-9729-ee122f0296f4", 
      "clinicType": "Primary Care", 
      "address": {
        "newPatientPhone": "", 
        "city": "Olympia", 
        "countryCode": "USA", 
        "facility": "ACME FAM MED", 
        "line2": "", 
        "line1": "525 ACME RD NE", 
        "phone": "360-555-7230", 
        "state": "WA", 
        "postalCode": "98506"
      }, 
      "directions": "ACME FAM MED", 
      "timezone": "America/Los_Angeles", 
      "relationshipType": "SECONDARY", 
      "emrId": "304504000", 
      "center": "ACME FAM MED"
    }
  ], 
  "providerExternalIds": [
    {
      "system": "org.providence.dig.epic.provwamt", 
      "value": "11111111"
    }
  ], 
  "providerId": "999999999", 
  "scheduleStatus": {
    "allowsOpenSchedule": true, 
    "allowsDirectSchedule": false
  }, 
  "providerNationalId": "999999991", 
  "isActive": true, 
  "visitTypes": [
    {
      "group": "illness", 
      "description": "New symptoms or conditions (INGRESS MATCH In-Person: New Concern )", 
      "bufferDays": 0, 
      "name": "New Problem Clinic Visit", 
      "visitTypeId": "77777", 
      "sortOrder": "1", 
      "shortName": "NewSymptoms", 
      "maxLookAheadDays": 100, 
      "preferenceLogic": null, 
      "id": "917de50e-5f6f-428a-95a4-c8d858e65934", 
      "reasonLabel": "What are the symptoms and when did they start?"
    }, 
    {
      "group": "checkup", 
      "description": "Yearly check-up for your overall health ( INGRESS MATCH In-Person: Well-Child or Adult Wellness )", 
      "bufferDays": 0, 
      "name": "Adult Annual or Physical Clinic Visit", 
      "visitTypeId": "55555", 
      "sortOrder": "1", 
      "shortName": "AdultPhysical", 
      "maxLookAheadDays": 90, 
      "preferenceLogic": null, 
      "id": "8bd07581-95a1-4603-8d1c-39b6dd84e613", 
      "reasonLabel": "What other concerns, if any, would you like to discuss during your wellness visit?"
    }
  ], 
  "email": "", 
  "maxAge": 130
}

There are several important aspects to note about this data structure:

providerId
National Provider Id, which was used for this call and will be used in the remaining booking calls.
departments
contains the departmentId that will be used in the remaining booking calls (departments.departmentId)
visitTypes
contains a list of visit types that can be displayed to the user and will be used in the remaining booking calls.

There will be 1 or more visit types for each provider. In the example above there are two shown, one being for a returning patient visit (Direct booking) and one for new patient (Open booking). The returning visit type is first item in the list with the visitTypeId of “77777.” The patient with a visitTypeId of “55555” in this example is a new patient and is identifiable as such because new patients are always have the value “NewPatient” assigned to their shortName property.

The visitType structure has information that allows for displaying the information to the user, grouping and “tool tips” for the user.

In this data structure, note the following flags

	    "isActive":true,
	    "acceptingNewPatients":true,                                          
	    "scheduleStatus": {
	           "allowsOpenSchedule":true,                      
	           "allowsDirectSchedule":true
	    },

These flags are important if you are building a widget that will display booking options on your health care website.

isActive
if true then the provider is active and if false they are turned off for digital booking through the DexCare platform.
acceptingNewPatients
when true this means that the provider is accepting new patients
scheduleStatus.allowsOpenSchedule
when true this means that the EMR is configured to allow new patient booking.
acceptingNewPatients and scheduleStatus.allowsOpenSchedule
only when this is true should the provider be considered to allow digital new patient booking
scheduleStatus.allowsDirectSchedule
when true this means that the EMR is configured to allow returning patient booking.

In the example above, when all the flags are true, this indicates that the provider would work (and accepts) all visit types for which they are configured.

Example — Provider Without a Digital Scheduling Option

Another case is below, where the EMR is not configured to allow returning patient to book their appointments directly.


	    "isActive":true,
	    "acceptingNewPatients":false,                                          
	    "scheduleStatus": {
	           "allowsOpenSchedule":true,                      
	           "allowsDirectSchedule":false
	    },

When showing visit types or requesting timeslots, you should not show requests for any returning patient (Direct) visit types.

For new patient visit types (Open), even though the EMR is configured for the provider to accept digital booking (scheduleStatus.allowsOpenSchedule keyword), the provider doesn’t accept new patients (acceptingNewPatients keyword).

So this provider effectively has no digital scheduling solution.

Provider Timeslots

Once you have a provider, our Slot Availability API can be used to retrieve available appointment times within a given timeframe.

DexCare has created a mechanism for caching the provider data as well as slot inventory data from Electronic Medical Record (EMR) systems such that it may be returned quickly and efficiently by this API.

The Slot Availability API is distinct from the Care Options API, in that the Slots API provides availability for a specified clinician or set of clinicians. The Care Options API provides availability by aggregating with intelligence across multiple departments without needing to specify a clinician.

Using information from the provider information above you will be able to construct a call to the slot availability service (OAS).

The timeslot calls will provide all the information necessary to:

  1. Use the booking API to create an appointment
  2. Navigate the user into the DexCare booking flow

You will use the providerId (as npi) returned from the previous provider queries in order to retrieve available slots.

Department information is only needed when a provider has multiple departments and/or ehrSystems and there is a desire to specify which to use. In that case, you will need to provide both the ehrInstance (from the ehrSystemName value) and the departmentId.

For previous versions of the timeslot API, see our deprecated APIs.

Timeslots for a Single Provider

The timeslots endpoint allows clients to select appointment time slots for a single provider. It supports pagination.

This endpoint uses the GET HTTP method.

GET /v5/providers/:npi/timeslots

The slots returned by this endpoint may be narrowed by a list of various criteria, including:

  • visit type (by name or identifier within an EMR)
  • department (by EMR identifier combined with EMR System identifier, or departmentUrlName)
  • whether the patient is new or established (using the newOrEstablishedPatient request variable)

Parameters

See the full OAS Specifiction for complete details on all parameters.

npi

At a minimum clients will need to provide a National Provider Identifier (NPI) as a path paremeter

startDate and endDate

The startDate and endDate parameters are optional.

A string with the format YYYY-MM-DDThh:mm:ss-Z is required. Valid values would include 2024-03-23, 2024-03-23T08:30:00Z, or 2024-03-23T08:30:00-07:00

The number of days of slots returned by the API defaults to 90 days when not using the startDate and endDate parameters.

  • If both startDate and endDate are not present, a search of up to 90 days from the current date is performed.
  • If only a startDate is provided, the endDate will be 90 days after the startDate
  • If only an endDate is provided, the startDate will be 90 days prior to the endDate or the the current date if the end date is less than 90 days from the current date (no data will be returned prior to the current date).
  • The 90 day default limit may be overridden by customer configuration.

departmentUrlName or departmentEmrSystemId and departmentEmrId

Allows clients to filter slots by department.

visitTypeName

Clients can narrow the time slots based on an optional list of visitTypeNames. The actual values for visit type names will be dependent on your implementation.

Pass in multiple by repeating param visitTypeName

newOrEstablishedPatient

enum of newPatient, establishedPatient bothNewAndEstablishedPatient

Allows filtering of slots by patient type of new or established patient. Both types will be returned by default.

daysOfSlots

Indicates pagination should be used (see below).

Pagination

The timeslots endpoint supports pagination of results to help reduce latency and optimize performance for client applications.

Pagination is used for the results only if the daysOfSlots parameter is included in the API request. This parameter indicates the maximum number of days of slots to be returned in the API response.

When results are paginated, the properties nextStartDate and previousEndDate will appear under the slotsByVisitType sub-entity of the slots objects that are returned.

{
    "slots": [
        {
            "departmentId": "3100039001",
            "departmentIdentifier": "org.providence.dig.epic.swedish|3100039001",
            "ehrSystemName": "org.{yourEmrSystemName}",
            "npi": "1447201234",
            "slotsByVisitType": [
                {
                    "visitTypeId": "122859",
					...
                    "previousEndDate": null,
                    "nextStartDate": "2024-01-18"
                }
           ],
            "timezone": "America/Los_Angeles"
        }
    ],
    ...

  • nextStartDate indicates to the client application what date to use for the startDate of the next page of available slots. A null value means there are no additional slots after this current “page”. The nextStartDate may be different for each visit type.

  • previousEndDate provides the last day of the previous page of available slots, and could be used for an API request as the endDate to retrieve a previous page. A null value means there are no available slots preceding this current “page”.

The date value for previousEndDate or nextStartDate does not mean there are slots on that specific date. It means there will be slots within the default date range if that endDate or startDate is used.

Note that a provider’s slot availability can vary by visit type. To paginate through the slots for a specific visit type:

  • Pass in the desired visit type via visitTypeName or visitTypeEmrId parameters
  • Use the previousEndDate or nextStartDate within the response of a desired visit type

Below are some examples as to what results would look like in a given scenario given the following days with available time slots (highlighted in blue) and the current date (indicated with the red outline).

If:

  • The parameters are daysOfSlots=3 (no startDate or endDate).
  • The current date is used as starting point, which is 3/22.

This is the first “page”.

The response will be:

  • slots returned for 3-22, 3-24, 3-30.
  • previousEndDate: null
  • nextStartDate: 2024-03-31 (there are slots on 4-1).
  • Slots will not be returned for:: 3-4, 3-25 to 3-29, 3-31.

If:

  • The parameters are daysOfSlots=3,startDate=2024-03-31
  • Today is 2024-03-22

This is the second “page”.

The response will be:

  • slots returned for 4-1, 4-3, 4-4.
  • previousEndDate: 2024-03-31
  • nextStartDate: 2024-04-05
  • Slots will not be returned for: 3-31, 4-2.

If:

  • The parameters are daysOfSlots=3,endDate=2024-03-31
  • Today is 2024-03-22

Returning to previous (first) “page”.

The response will be:

  • slots returned for 3-22, 3-24, 3-30.
  • previousEndDate: null
  • nextStartDate: 2024-03-31 (there are slots on 4-1)
  • Slots will not be returned for: 3-4, 3-25 to 3-29, 3-31.

Open API Specification

See the full OAS Specifiction for the Slot Availability API.

Sample Request

curl --location 'https://api.{customerShorthand}/v5/providers/9876/timeslots?daysOfSlots=3'

Sample Response

{
    "slots": [
        {
            "departmentId": "3100039001",
            "departmentIdentifier": "org.some.department|3100039001",
            "ehrSystemName": "org.some.emr.system",
            "npi": "1447201234",
            "slotsByVisitType": [
                {
                    "visitTypeId": "122859",
                    "visitTypeName": "NewSymptoms",
                    "visitTypeTitle": "New Problem Clinic Visit",
                    "visitTypeGuid": "236f64e3-f964-4035-834e-54a022f6948b",
                    "forNewPatient": false,
                    "forEstablishedPatient": true,
                    "isBookable": true,
                    "scheduleDays": [
                        {
                            "date": "2024-01-15",
                            "slotTimes": [
                                {
                                    "slotDateTime": "2024-01-15T05:00:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-15T05:15:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-15T05:30:00-08:00",
                                    "duration": 15
                                }
                            ]
                        },
                        {
                            "date": "2024-01-16",
                            "slotTimes": [
                                {
                                    "slotDateTime": "2024-01-16T05:00:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-16T05:15:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-16T05:30:00-08:00",
                                    "duration": 15
                                }
                            ]
                        },
                        {
                            "date": "2024-01-17",
                            "slotTimes": [
                                {
                                    "slotDateTime": "2024-01-17T05:00:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-17T05:15:00-08:00",
                                    "duration": 15
                                },
                                {
                                    "slotDateTime": "2024-01-17T05:30:00-08:00",
                                    "duration": 15
                                }
                            ]
                        }
                    ],
                    "previousEndDate": null,
                    "nextStartDate": "2024-01-18"
                }
           ],
            "timezone": "America/Los_Angeles"
        }
    ]
}

Querying for Multiple Providers

Dexcare also provides an endpoint for selecting slots for multiple providers with its slots availability service.

This endpoint uses the POST HTTP method.

POST https://api.{customerShorthand}.dexcare.io/v5/slots/search

Parameters

For full details, consult the Open API Spec for the slots service.

npi

At a minimum you will need to supply at least one National Provider Identifier (NPI)

In cases where a provider has multiple departments, you may pass in the ehrInstance and departmentId along with the provider’s npi to restrict which slots will be returned.

startDate and endDate

The startDate and endDate parameters are optional.

  • If both startDate and endDate are not present, a search of up to 30 days from the current date is performed.
  • If only a startDate is provided, the endDate will be 30 days after the startDate
  • If only an endDate is provided, the startDate will be 30 days prior to the endDate or the the current date if the end date is less than 30 days from the current date (no data will be returned prior to the current date)
  • If both startDate and endDate are present, the search range will be limited to 90 days from the start date.
  • Both the 30 day and 90 day limits may be overriden by customer configuration.

visitTypeNames

You can narrow the time slots based on an optional list of visitTypeNames. The actual values for visit type names will be dependent on your implementation.

Open API Specification

See the full OAS Specifiction for the Slot Availability API.

Sample Request

Below is an example payload illustrating the different parameters.

{
  "startDate": "2022-06-01",
  "endDate": "2022-06-10",
  "visitTypeNames": [
    "AudltWellness",
    "PediatricWellness"
  ],
  "criteriaItems": [
    {
      "npi": "7890612345",
      "ehrInstance": "pacific.nw",
      "departmentId": "34589431"
    }
  ]
}

Sample Response

A successful response payload will return a 200 response code and look as follows:

{
  "results": [
    {
      "npi": "7890612345",
      "ehrInstance": "pacific.nw",
      "departmentId": "34589431",
      "timezone": "America/Los_Angeles",
      "visitTypes": [
        {
          "visitTypeId": "4378",
          "visitTypeName": "AdultWellness",
          "slots": [
            {
              "dateTime": "2022-03-09T15:00:00-08:00",
              "duration": 30
            }
          ]
        }
      ]
    }
  ]
}

For each visit type a dateTime and a duration is returned for all available tiemslots for the given provider.

Using that information, you will be able to construct a slotId for the purpose of booking a given timeslot.

Constructing a SlotId

Subsequent calls to our booking APIs will a require a slot identifier (slotId) to be generated based on the slot information.

To create a slotId, you will need to create a JSON structure, stringfy it and convert it to base64encoding.

The example below shows what the values would be for the different component parts based on the previous slot service payload example.

  var slotIdStruct = {
    date, //2022-03-09, (yyyy-MM-dd)
    time, //15:00:00-08:00
    duration, //30
    visitTypeId, //4378
    visitType, //AdultWellness
    timezone, //America/Los_Angele
    departmentId, //34589431
    slotType, //'NewPatient' || 'Returning'
    version, //'2.0' (a constant)
  };

  var slotIdStr = JSON.stringify(slotIdStruct)
  var slotIdStrBase64 = Buffer.from(slotIdStr, 'utf8').toString('base64');

Getting Patient Identifying Information

At this point you will have most of the data you need to make an appointment for a patient.

The last thing that needs to be done is to identify the patient through their unique identifier.

See our Patient APIs for details how the patient identifier may retrieved.

Booking With the Provider

Now that you have selected a timeslot, you may book the appointment using our book api endpoint