Care Options API
Introduction to Care Options
The DexCare Care Options API has been designed for customers who want to use DexCare to publish their care availability to enable intelligent navigation to the options available.
This API has been designed to allow client applications to find all available time slots for appointments within a given location agnostic of provider or find providers that meet their needs in terms of location, specialty, or gender preference.
The underlying goal is to help patients who just want to find care — they will be able to find a time slot and book with the provider who owns that time slot potentially without ever needing to know the provider.
The Care Options API will support upcoming DexCare products and features.
Care Options API Use Cases
The Care Options API allows health systems to:
-
aggregate available time slots for both generic and named providers for in-person visits to retail locations and primary care providers across multiple departments as well as scheduled virtual visits
-
intelligently route patients to providers based on the patient’s criteria and the provider’s availability and proximity as well as provider utilization metrics
-
provide patients with alternative recommendations that will meet their needs when their preferred primary care provider is unavailable
Care Options API Features
DexCare provides high capacity, high performance caching of available time slots for appointments with providers imported from EHR systems such as Epic. This ensures that the availability of these time slots is accurately reflected to end users.
Time slots are aggregated across multiple primary care providers and retail clinics for both in-person and virtual visits and can be queried through the Care Options API.
Filters refine Care Options API results such that only the care options that fulfill a given set of criteria are surfaced.
The Care Options API supports searching for providers and time slots by a variety of parameters including:
-
location (via latitude, longitude and radius) of the provider or zipcode
-
specialty of the provider
-
gender of the provider
-
health system defined “visit types” that describe the purpose for which a patient would seek care
-
identifiers for the departments
Sorting rules enable a selection of care options returned by the API to be sorted or matched in order, based on a given variable, such as provider availability or proximity.
Care Options API Operations
The Care Options API consists of two main endpoints that allow you to retrieve either providers or time slots.
Get Available Providers
The providers availability endpoint allows providers to be queried by a flexible set of criteria including the type of visit (as defined by the health system), as well as the provider’s location, specialty, and gender.
When querying for providers you must provide either:
-
latitudeandlongitudegeospatial coordinates (with an optional radius that otherwise defaults to 30 miles) -
a
postalCode -
a list of
departmentIds
Please refer to the complete reference documentation for get available provider for a comprehensive definition of all the parameters and responses.
The response payload consists of a list of provider objects.
Sample Request Payloads for Getting Providers
Below is a sample request that returns female providers practicing family medicine available for a “New Patient” visit type and the specialty “Family Medicine” within 10 miles of a given location (using latitude and longitude geospatial coordinates )
The sortBy is the default, which is “mostAvailable” — this is based on a ratio of windowDays to slotCount.
The alternative value for sortBy is “nextAvailable” — as the system is dealing with cached data and not real time data, the ordering that is returned is based on slot density relative to other providers.
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/providers' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"visitTypeNames": [
"NewPatient"
],
"gender": "female",
"specialty": "Family Medicine",
"latitude": 47.610692,
"longitude": -122.321216,
"radius": 10,
"sortBy": "mostAvailable"
}'
Alternatively, here is an example searching for the same criteria using a postalCode
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/providers' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"visitTypeNames": [
"NewPatient"
],
"gender": "female",
"specialty": "Family Medicine",
"postalCode": "98102",
"sortBy": "mostAvailable"
}'
Finally, here is an example where the list of providers returned are limited to providers belonging to a list departments defined by the departmentIds string array:
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/providers' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"visitTypeNames": [
"NewPatient"
],
"gender": "female",
"specialty": "Family Medicine",
"departmentIds": ["3200080024","405517000"],
"sortBy": "mostAvailable"
}'
Sample Providers Response Payload
Below is an example payload of the data structure returned by a query to the Care Options providers endpoint.
[
{
"npi": "1245662048",
"name": "Jane Doe",
"gender": "Female",
"specialties": [
"Family Medicine",
"Internal Medicine"
],
"departmentId": "3200080024",
"departmentName": "Seattle Medical Center",
"ehrInstance": "ehr.region",
"address": {
"line1": "2324 Eastlake Ave E",
"line2": "Suite 500",
"city": "Seattle",
"state": "WA",
"zipCode": "98102"
},
"timezone": "America/Los_Angeles",
"distanceFrom": 10,
"visitTypes": [
{
"visitTypeId": "124532",
"visitTypeName": "Video",
"availability": {
"windowDays": 40,
"slotCount": 250
}
}
]
}
]
Working with the Provider Response Payload
The provider object contains identifying information about the given Provider, including their name, gender, specialties, and address (with the distance from the user in the ``distanceFrom` field provided in miles).
Note the visit types supported by a given provider are returned as the visitTypes array.
The windowDays and slotCount days are used by DexCare for sorting purposes and are not necessarily relevant to the client.
curl --location --request POST 'https://<your-server-name>/v5/slots/search' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"startDate": "2022-07-05",
"endDate": "2022-07-25",
"visitTypeNames": ["NewPatient"],
"criteriaItems": [
{
"npi": "1124519293",
"ehrInstance": "org.providence.dig.epic.swedish",
"departmentId": "3100018001"
}
]
}'
Get Available Slots
The slots availability endpoint allows providers to be queried by a flexible set of criteria, including the type of visit (as defined by the health system) and timeframe criteria (as start and end dates), as well as the provider’s location, specialty, and gender.
When querying for providers you must provide both a list of visitTypeNames and one of the following:
-
latitudeandlongitudegeospatial coordinates (with an optional radius that otherwise defaults to 30 miles) -
a
postalCode -
a list of
departmentIds
Alternatively, you may provide a searchContextID (see below).
Please refer to the complete reference documentation for get available slots for a comprehensive definition of all the parameters and responses.
This operation returns a list of slots, as well as a collection of providers and departments.
Sample Request Payloads — Getting Time Slots by Location
Below is a simple request looking available slots for a set of visit types that includes “new patients” and “new symptoms” within 5 miles (i.e. the given radius) of the center of the given postalCode. The actual values for the visitTypeNames will be implementation dependent.
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/slots' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"visitTypeNames": [
"NewPatient",
"NewSymptoms"
],
"postalCode": "98104",
"radius": 5
}'
Sample Request Payload — Getting Time Slots By Clinic Type
To retrieve time slots for retail clinics you would specify a value for the clinicType parameter of your request, in addition to the required visitTypeNames and other parameters.
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/slots' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '
{
"clinicType": [
"retail"
],
"latitude": 47.610692,
"longitude": -122.321216,
"radius": 3,
"startDate": "2022-08-01",
"endDate": "2022-08-08",
"patient": {
"patientId": "900332632",
"patientIdType": "MRN",
"ehrInstance": "ehr.region"
},
"visitTypeNames": [
"illness"
]
}'
Sample Request Payload — Getting Time Slots By SearchContext
As part of the response payload when querying time slots, a property called searchContext is returned. This is a unique identifier assigned to a copy of the search criteria that was submitted to generate the given response which has been cached by DexCare. This identifier may be used to re-run the query, in which case it is the only required parameter in the request payload.
This type of request is useful in the case where there is a conflict when booking a time slot (i.e. the selected time slot was booked by someone else) in which case a query to show alternate time slots based on the previously used criteria can easily be executed without retaining the full details of the original query.
A given searchContext will be valid for 1 day after the initial request that created it (this duration may be configured for the deployment of a given health system).
curl --location --request POST 'https://api.<yourinstance>.care/v1/availability/slots' \
--header 'x-api-key: <Your-API-Key>' \
--header 'Content-Type: application/json' \
--data-raw '
{
"searchContext": "f55ffea269ba54d65d190a7225f01208"
}'
Sample Slots Response Payload
Below is an example payload of the data structure returned by a query to the Care Options slots endpoint.
{
"slots": [
{
"slotDateTime": "2020-08-01T09:30:00-00:00",
"visitTypeName": "phone",
"providerOptions": [
{
"npi": "1245662048",
"departmentEhrIdentifier": "org.ptc.dig.epic.northwest|3200080024",
"visitTypeId": "100005",
"duration": 20
},
{
"npi": "1245662051",
"departmentEhrIdentifier": "org.ptc.dig.epic.northwest|3200080024",
"visitTypeId": "100005",
"duration": 20
}
]
}
],
"providers": {
"1245662048": {
"name": "John Doe",
"gender": "male",
"specialties": [
"video",
"phone"
]
},
"1245662051": {
"name": "Jane Doe",
"gender": "female",
"specialties": [
"phone"
]
}
},
"departments": {
"org.ptc.dig.epic.northwest|3200080024": {
"departmentId": "3200080024",
"ehrInstance": "org.ptc.dig.epic.northwest",
"departmentName": "SMG PRIMARY CARE MAGNOLIA",
"distanceFrom": 10,
"timezone": "America/Los_Angeles",
"address": {
"line1": "2324 Eastlake Ave E",
"line2": "Suite 500",
"city": "Seattle",
"state": "WA",
"zipCode": "98102"
}
}
},
"searchContext": "f55ffea269ba54d65d190a7225f01208"
}
Working with the Slots Returned Payload
The slotDateTime will indicate when the time slot begins.
The duration of the time slot is specified under providerOptions
The available options for providers corresponding to that time slot are listed under providerOptions
The order of these provider options is determined by DexCare and should be respected. In the future, there will be options to configure how these providers are listed.
Customers can work with DexCare to adjust this ordering to their needs. Options for sorting will include using the distance from the given location parameters or a measure of “availability” within a given time period.
The providers attribute of the response is an associative array mapped to the NPI of a given provider. These represent normalized data for all the providers included as providerOptions in the slots list.
Likewise, departments attribute of the response is an associative array of normalized department entities mapped to the ehrInstance, concatenated with the unique identifier of the department separated by a pipe (|) character, also known as the departmentEhrIdentifier.
Client code should render each time slot such that it is clear when and by what modality the appointment will be available. Further details, such as the location of the department, should be revealed as necessary.
The searchContext is a unique identifier assigned to a copy of the search criteria that was submitted to generate the given response which has been cached by DexCare. This identifier may be used to re-run the query, in which case it is the only required parameter in the request payload. It is also used as part of the booking flow.
Booking Appointments
Use the selected slotDateTime, departmentEhrIdentifier, and searchContext properties that are returned from a call to the /availability/slots endpoint to initiate the DexCare booking flow.
Supporting Data and Functionality
Using the Care Options API will require clients to supply various parameters, the values for which will need to be retrieved from various different Sources.
Visit Types
A Visit Type describes the type of care a patient intends to access and may be used to filter providers and time slots from the Care Options API.
Example of Visit Types might include one for patients with new symptoms, an adult physical, or a follow up visit.
A visitTypeName is a human readable string. You will use this value when making queries to the Care Options API to filter your results for providers and time slots.
A visitTypeId is a numeric identifier.
The available visit types will vary from health system to health system.
If you query by providers, you will be able to see all of the visitTypes available for a given provider.
{
"results": [
{
"distanceFrom": 1.1,
"npi": "1487186490",
...
"visitTypes": [
{
"visitTypeId": "12214648",
"visitTypeName": "NewSymptoms",
"availability": {
"slotCount": 787,
"windowDays": 45
}
},
{
"visitTypeId": "122859",
"visitTypeName": "FollowUp",
"availability": {
"slotCount": 575,
"windowDays": 45
}
},
{
"visitTypeId": "122861",
"visitTypeName": "AdultPhysical",
"availability": {
"slotCount": 575,
"windowDays": 45
}
},
...
Departments
Departments represent the physical locations at which services are provided, and at which healthcare providers generally work. The Care Options API allows queries for providers and slots to be filtered by the identifiers for departments.
As with Visit Types, there is both a unique departmentId and a human readable text departmentName (e.g. “Seattle Medical Center”) associated with a department. The departmentId is scoped to a particular EHR instance. There is also an id property that is generated by DexCare.
Departments are defined in the DexCare Self Service Portal and can be found under the “Departments” section, which may be selected through the lefthand navigation menu.
Both the departmentName and departmentId associated with a provider are returned as part of the provider data structure when you query for providers.
A normalized set of department objects is returned when you query for slots. This object contains details about the location of the department, including its relative distance from the current user. This is designed to reduce the size of the overall payload. A department is mapped to the time slot by a combination of EHR instance identifier and department identifier, which is referred to as departmentEhrIdentifier
Provider Specialties
Both providers and slots may be filtered by the branch of medicine or surgery in which a physician specializes. These specialties vary from health system to health system and are defined as human readable strings.
The specialties of a provider are returned as a list when you query the care options API for specialties.
Patient Information
There are three fields contained within the patient structure that may be provided as part of the request payload, patientId, patientIdType, and ehrInstance. These are values required by DexCare to look up patient information.
"patient": {
"patientId": "900123123",
"patientIdType": "MRN",
"ehrInstance": "ehr.region"
}
This information is currently used for logging. Dexcare uses this information to correlate a search request to an appointment being booked.
For more information on looking up patient information, see our documentation on Retrieving and Creating Patient Information.
EHR Instances
Some health systems may want to limit the providers and departments that are returned from our APIs because their members are not able to go out of their market.
In this case, client applications can limit the results to a set of specific EHR systems based on an identifier that has been defined with DexCare.
Obtaining Longitude / Latitude
All queries of the Care Options API will require a longitude and a latitude in order to find providers and slots within a given radius (the default radius in 30) of the user for whom you are making the query.
You will have to obtain these geolocation coordinates for the current user from the browser or by converting a given address to an address using one of a variety of tools available for that purpose, such as Google’s Geocode API.