Virtual Visits

v8

This page walks you through the API calls required to build a user facing experience to get a user into the DexCare virtual visit waiting room.

IMPORTANT NOTE

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

See the latest version of the documentation for the latest API documentation.

The calls below assume that the user interface (UI) will provide information to the user about whether the virtual clinic is open. If the clinic is open, the UI will display the current duration of time the user must wait in order to be seen. This duration is known as the Wait Time.

The user will then need to sign-in before progressing to the waiting room.  

This flow requires the following additional pieces of patient information (to being signed in):  

the patient’s current location (selected from a pulldown of “practice regions”)
the patient’s major complaint / reason-for-visit.

The following order of operations will be used to create the virtual visit

Retrieve the Available Practice Regions for a Practice
Retrieve a selected Practice Region
Calculate a Wait Time for the Practice Region
Retrieve a Patient Identifying Information
Create the Visit

Practice Regions

Virtual Visits are delivered based on a Practice Region.  Practice Regions in the DexCare API correspond to a state provider licensure.

Practice Regions are used to collect the physical location of the patient to assign them to a properly licensed provider.

You will use Practice Regions to query if service is available (i.e. is the clinic open), hours of operation, and wait times.

Retrieving Available Practice Regions

In order to determine a patient’s Practice Region you will initiate a call is to get the list of selectable Practice Regions based on the identifier of the Practice. 

Endpoint

get Practice

api/8/DexCare/practices/{practiceId}

Parameters

practiceId

identifier for a Practice belonging to a client. This value is set up and provided by DexCare and may be hardcoded in your application.

REQUIRED

type:	path
default:	N/A
example:	`0cee700e-f4c1-4459-b390-263e4ded436c` (Acme)
values:	string

Responses

200

Practice entity instance

{
  "id": "string",
  "displayName": "string",
  "careMode": "enum: 'virtual' | 'retail'",
  "payment": {
    "insurance": "boolean",
    "selfPay": "boolean",
    "serviceKey": "boolean"
  },
  "epicBookingEnabled": "boolean",
  "practiceRegions": [
    {
      "id": "string",
      "practiceId": "string",
      "displayName": "string",
      "regionCode": "string",
      "active": "boolean",
      "availability": [
        {
          "start": "2020-11-05T03:18:25.102Z",
          "end": "2020-11-05T03:18:25.102Z"
        }
      ],
      "busy": "boolean",
      "busyMessage": "string",
      "paymentAccountId": "string",
      "visitPrice": "number",
      "departments": [
        {
          "id": "string",
          "epicDepartmentId": "string",
          "ehrSystemName": "string",
          "defaultDepartmentName": "string"
        }
      ]
    }
  ]
}

praticeRegions: List of Practice Regions belonging to the Practice that can be shown to the user in a UI element such as select box. ; You will need to add “Other” to the list returned.  If the user selects “Other” you will want to provide a message that they are out of service area.

Retrieving Practice Region Availability

After the user selects a supported Practice Region you will need to call the following endpoint to see if that Practice Region is currently open for patients using the practiceRegionId.

Endpoint

get Availability

GET api/8/practiceRegions/{practiceRegionId}/availability 

Parameters

practiceRegionId

REQUIRED

The identifier for the Practice Region for which availability is being queried

type:	path
default:	N/A
example:	`cc11788e-7d33-463d-a385-d378ff3a9966` (Montana)
values:	string

Responses

200

Returns an “available” state (true or false), and if not available, it will also return the reason why.

If the Practice Region is ‘available’, the booking button can be set to an active state with the display of a wait time.

If the Practice Region is not available, it is recommended that the user not be allowed to proceed and be displayed the correct messaging.

{ 

    "available": "boolean: 'true' | 'false'", 

    "reason": "enum: null | 'NO_REGIONS_FOUND' | 'REGION_BUSY' | 'OFF_HOURS' | 'NO_ONCALL_PROVIDERS'"

}

available: indicates whether or not the practice is available as a boolean value
reason: explanation as to why no wait time is available

Calculating Wait Times

Wait Times are calculated by Practice Region.

Endpoint

get Practice Region Wait Time

GET api/8/practiceRegions/{practiceRegionId}/waittime

Parameters

practiceRegionId

REQUIRED

The identifier for the Practice Region for which the wait times is being calculated

type:	path
default:	N/A
example:	`cc11788e-7d33-463d-a385-d378ff3a9966` (Montana)
values:	string

Responses

200

Wait Time will be in seconds

{ 

    "estimateGeneratedAt": "2020-11-05T18:00:57.867Z", 

    "estimatedWaitTimeSeconds": 30.0 

}

estimateGeneratedAt: Date that estimate was generated at
estimatedWaitTimeSeconds: The duration the patient is estimated to have to wait (N.B. although returned as float, this is always an integer value)

Retrieve a Patient Identifying Information

A Patient GUID and other patient identifying information is necessary to create a visit.

Our page on Patient related APIs details how this information may retrieved or added to the system.

Creating a Visit

The final step in this workflow will create a visit within DexCare’s system as well as an appointment in Epic.

Endpoint

request a new visit

POST api/8/practices/{practicesID}/visits  AUTH TOKEN REQUIRED 

Parameters

Body Schema

{ 
  "patient": { 
    "identifier": "patient guid", 
    "phone": "contact number for visit: 5552223334|555-222-3334|(555) 222-3334|*", 
    "email": "contact email for visit", 
    "address": { 
      "line1": "string", 
      "line2": "optional", 
      "city": "string", 
      "state": "string", 
      "postalCode": "string" 
    } 
  }, 
  "actor": { 
    "firstName": "string", 
    "lastName": "string", 
    "phone": "5552223334|555-222-3334|(555) 222-3334|*", 
    "dateOfBirth": "YYYY-MM-DD" 
  }, 
  "billingInfo": { 
    "paymentMethod": "enum: 'creditcard' | 'insurance' | 'couponcode'", 
    "declaration": "enum: 'self' or 'other'", 
    "firstName": "first name of the primary insurance holder", 
    "lastName": " last name of the primary insurance holder", 
    "gender": "enum: 'male' | 'female' | 'other' ", 
    "dateOfBirth": "YYYY-MM-DD", 
    "couponCode": "service key/coupon code (when paymentMethod is 'couponcode')", 
    "insuranceType": "'manual' (when paymentMethod is 'insurance')", 
    "insuranceProviderId": "patient insurance provider id (when paymentMethod is 'insurance')", 
    "insuranceMemberId": "patient membership id (when paymentMethod is 'insurance')", 
    "stripeToken": "stripe payment token (when paymentMethod is 'creditcard')" 
  }, 
  "visitDetails": { 
    "practiceRegionId": "string", 
    "ehrSystemName": "string", 
    "departmentId": "string", 
    "visitReason": "string", 
    "declaration": "self", 
    "acceptedTerms": true, 
    "preTriageTags": [ 
      "string" 
    ] 
  } 
} 

patient: in cases where the patient is requesting a visit for themselves, this information will match the patient information retrieved from GET /v1/patient. When the user requesting visit is acting on behalf of the patient, this information will match the patient information defined in a call to /v1/patient/other
actor: information provided when booking on behalf of another person information, such as a guardian to a patient for child visits. Required when visitDetails.declaration is other and should not be in the request payload when visitDetails.declaration is self
billingInfo: required properties vary based on the paymentMethod selected. N.B. not all payment methods are supported for each service and some payment methods require setup from your DexCare contact

billingInfo for a credit card through Stripe:

...
"billingInfo": { 
    "paymentMethod": "creditcard", 
    "stripeToken": "TokenFromStripe" 
  }
...

billingInfo for a coupon code or service key:

...
"billingInfo": { 
    "paymentMethod": "couponcode", 
    "couponCode": "aSecretServiceKey", 
  }
...

billingInfo when a patient is using their own insurance:

...
"billingInfo": { 
    "paymentMethod": "insurance", 
    "declaration": "self", 
    "firstName": "patient first name", 
    "lastName": "patient last name", 
    "gender": "enum: 'male' | 'female' | 'other' ", 
    "dateOfBirth": "YYYY-MM-DD", 
    "insuranceType": "manual", 
    "insuranceProviderId": "patient insurance provider id", 
    "insuranceMemberId": "patient insurance membership id", 
  }
...

billingInfo when a patient is using someone else’s insurance:

...
"billingInfo": { 
    "paymentMethod": "insurance", 
    "declaration": "other", 
    "firstName": "first name of the primary insurance holder", 
    "lastName": " last name of the primary insurance holder", 
    "gender": "enum: 'male' | 'female' | 'other' ", 
    "dateOfBirth": "YYYY-MM-DD", 
    "insuranceType": "manual", 
    "insuranceProviderId": "insurance holder insurance provider id", 
    "insuranceMemberId": "insurance holder membership id", 
  }
...

visitDetails.departmentId: identifier for the department in which visit will be conducted. Use the id of a department returned when you selected a practice region
visitDetails.declaration: indicates if the visit is for the current user (self) or someone else (other)
visitDetails.ehrSystemName: allows support for health systems with more than one EHR/EMR instance. Use the ehrSystemName of a department returned when you selected a practice region
visitDetails.practiceRegionId: Practice Region in which the patient is currently located — alows for virtual MA to triage patients that might be outside of treatment area
visitDetails.visitReason: patient’s major complaint / symptom. This is used by the virtual MA for triaging patients.

Responses

200

The returned payload is a Visit containing the visitId necessary to navigate to the “waiting room”

i.e. a Waiting Room URL: DexCare/visit/{visitID}?brand={brandID} AUTH TOKEN REQUIRED 

{ 
  "visitId": "string", 
  "userId": "string", 
  "userEmail": "string", 
  "waitingroomId": "string", 
  "conferenceroomId": "string", 
  "visitRedirectUrl": "string", 
  "isTokBox": true, 
  "tokBoxVisit": { 
    "apiKey": "string", 
    "waitingRoomSession": { 
      "sessionId": "string" 
    }, 
    "videoConferenceSession": { 
      "sessionId": "string" 
    } 
  } 

visitId: needed by the browser to navigate into the waiting room

400

Bad request; See response for info

404

Practice not found

500

Internal error