Booking Appointments
Once a user has selected a time slot for a retail or a provider specific appointment, there are two primary ways of booking / scheduling an appointment.
For in-person retail appointments, control of the application may be handed off to DexCare’s web user interface to complete the booking flow.
Alternatively, for in-person provider specific visits, an API call may be made to our providerbooking endpoint through which all the relevant patient, visit, and billing information can be passed.
For virtual visits, please see Creating Virtual Visits
Starting the Scheduling Flow for Retail Appointments
Once the user has selected a time slot for an in-person retail visit, you may hand off control to the DexCare scheduling application with the identifier of the selected time slot.
To do, send end users to a URL with the following structure.
https://scheduling.care.dexcarehealth.com/retail?timeSlot=<slotDateTime>&departmentUrlName=<urlName>&brand=<brand>
For example, to start scheduling a retail appointment for the 3:40pm time slot at the AcmeC4 clinic
Note: The slot provided will not work if the date & time has passed. In this case, the user will be presented with a dialog to pick a new time slot.
https://scheduling.care.dexcarehealth.com/retail?timeSlot=2021-04-24T15:40:00-07:00&departmentUrlName=AcmeC4&brand=Acme
Note that brand is a required parameter for this call.
Booking from the Care Options API
For clients working with DexCare through the Care Options API additional parameters are necessary for the booking flow.
In this case, time slots are aggregated across multiple providers
- aggregate — a boolean flag that should be set to true for clients using the Care Options API
- searchContext — a parameter returned by the Care Options API that allows search queries for timeslots and providers to be re-run in the case of a time slot conflict so that alternate time slot options can be shown
Note that the departmentIdentifier parameter is not necessary for this aggregate case, as it is redundant.
https://scheduling.care.dexcarehealth.com/retail?timeSlot=<slotDateTime>&brand=<brand>&aggregate=true&searchContext=<yourSearchContext>
Booking with Providers through the API
Once you have selected the time slot for a specific provider, it is possible to create the booking through your own booking flow and submit all the information to DexCare’s booking endpoint.
POST /api/7/visits/providerbooking
This is a POST so the arguments are in the body.
Note that this endpoint will be hosted on ecvapi.[your.instance].dexcarehealth.com instead of api.[your.instance].dexcarehealth.com
The required body structure is:
{
"actor": { // required when visitDetails.declaration is "other"
"email": "string",
"firstName": "string",
"lastName": "string",
"gender": "other|female|male|unknown|nonbinary", //note that that not all values maybe supported by an EHR system
"dateOfBirth": "YYYY-MM-DD",
"relationshipToPatient": "string", //options provided by a the healthcare provider describing how the actor is realted to the patient (i.e. mother, father, guardian, etc.)
"phone": "string"
},
"billingInfo": {
"paymentMethod": "insurance|couponcode|self",
"declaration": "self|other",
"firstName": "string",
"lastName": "string",
"dateOfBirth": "MM-DD-YYYY",
"couponCode": "string", // coupon code/service key for 'couponcode' paymentMethod
"insuranceType": "manual|other",
"insuranceProviderId": "string", // insurance provider id for 'insurance' paymentMethod
"insuranceMemberId": "string" // insurance member id for 'insurance' paymentMethod
},
"patient": {
"patientGuid": "string", // required, see above
"address": {
"line1": "string",
"line2": "string",
"city": "string",
"state": "string",
"postalCode": "string"
}
},
"visitDetails": { // all fields required
"declaration": "self|other",
"departmentId": "string", // acquired from previously described call
"ehrSystemName": "string", // acquired from previously described call
"nationalProviderId": "string", // acquired from previously described call
"slotId": "string", // acquired from previously described call
"visitReason": "string", // reason entered by patient
"visitTypeId": "string" // acquired from previously described call
}
}
When the visitDetails.declaration is “other” the “actor” structure must also be present. If
visitDetails.declaration is “self” the “actor” structure is optional and any values sent will
be ignored.
When the visitDetails.declaration is “other” the product operates as if a guardian is making an
appointment for someone else. The guardian information is passed in using the actor structure.
In this case the actor information is required.
The billingInfo data is always required. Depending on what paymentType, other fields will be required.
Below is an example of a billingInfo where the end user provides their insurance for manual entry.
"billingInfo": {
"paymentMethod": "insurance",
"insuranceType": "manual",
"insuranceProviderId": "placeholder",
"insuranceMemberId": "22222222222222222222",
"insuranceGroupNumber": "30charsalphanumericisoptional",
"declaration": "self"
}
Alternatively, here example of a billingInfo where the end user is an existing patent.
"billingInfo": {
"paymentMethod": "insurance",
"insuranceType": "manual",
"insuranceProviderId": "placeholder",
"insuranceMemberId": "22222222222222222222",
"insuranceGroupNumber": "30charsalphanumericisoptional",
"declaration": "other",
"firstName": "Jane",
"lastName": "ExistingPatient",
"gender": "female",
"sex": "female",
"dateOfBirth": "2000-11-11"
}
Example — Booking For Self Using Self Pay
The following is an example of how to book an appointment for the current user (that is a user booking for themselves) who will pay upon arrival (referred to as “self” pay).
In this case no “actor” entity is required.
{
"billingInfo": {
"paymentMethod": "self",
"declaration": "self"
},
"patient": {
"patientGuid": "asdff515-09ba-4551-a5c2-e6680fc41111",
"address": {
"line1": "line1",
"line2": "line2",
"city": "city",
"state": "WA",
"postalCode": "98092"
}
},
"visitDetails": {
"declaration": "self",
"departmentId": "123446001",
"ehrSystemName": "org.providence.dig.epic.provwamt",
"nationalProviderId": "1629394572",
"slotId": "ewogICJkYXRlIjogIjIwMjMtMDEtMDUiLAogICJ0aW1lIjogIjE0OjQwOjAwIiwKICAiZHVyYXRpb24iOiAzMCwKICAidmlzaXRUeXBlSWQiOiAiMTIzNDAwMyIsCiAgInZpc2l0VHlwZSI6ICJOZXdQYXRpZW50IiwKICAidGltZXpvbmUiOiAiQW1lcmljYS9Mb3NfQW5nZWxlcyIsCiAgImRlcGFydG1lbnRJZCI6ICIxMjM0NDYwMDEiLAogICJzbG90VHlwZSI6ICJOZXdQYXRpZW50IiwKICAidmVyc2lvbiI6ICIzLjAiCn0=",
"visitReason": "congestion, fever",
"visitTypeId": "1000003"
}
}
Example — Booking for Self With Insurance
In this example, the user is once again booking an appointment for themselves, but they are paying using their insurance.
In this case the insurance information will be collected manually by the provider.
{
"billingInfo": {
"paymentMethod": "insurance",
"insuranceType": "manual",
"insuranceProviderId": "placeholder",
"insuranceMemberId": "22222222222222222222",
"insuranceGroupNumber": "30charsalphanumericisoptional",
"declaration": "self"
},
"patient": {
"patientGuid": "f36af515-09ba-4551-a5c2-e6680fc41886",
"address": {
"line1": "line1",
"line2": "line2",
"city": "city",
"state": "WA",
"postalCode": "98092"
}
},
"visitDetails": {
"declaration": "self",
"departmentId": "301546001",
"ehrSystemName": "org.providence.dig.epic.provwamt",
"nationalProviderId": "1629394572",
"slotId": "eyJkYXRlIjoiMjAyMy0wMS0wNSIsInRpbWUiOiIxNDo0MDowMCIsImR1cmF0aW9uIjozMCwidmlzaXRUeXBlSWQiOiIxMDAwMDAzIiwidmlzaXRUeXBlIjoiTmV3UGF0aWVudCIsInRpbWV6b25lIjoiQW1lcmljYS9Mb3NfQW5nZWxlcyIsImRlcGFydG1lbnRJZCI6IjMwMTU0NjAwMSIsInNsb3RUeXBlIjoiTmV3UGF0aWVudCIsInZlcnNpb24iOiIzLjAifQ==",
"visitReason": "ow my testing hurts",
"visitTypeId": "1000003"
}
}
Example — Booking For a Child Using Insurance
When booking for a patient who is not the same as the user who is making the booking, an actor entity is required, which will define their relationshop to the patient via the relationshipToPatient field.
{
"actor": {
"email": "testpatient@example.com",
"firstName": "Jane",
"lastName": "Doe",
"gender": "female",
"dateOfBirth": "2000-11-11",
"relationshipToPatient": "mother",
"phone": "555-555-5555"
},
"billingInfo": {
"paymentMethod": "insurance",
"insuranceType": "manual",
"insuranceProviderId": "placeholder",
"insuranceMemberId": "22222222222222222222",
"insuranceGroupNumber": "30charsalphanumericisoptional",
"declaration": "self",
"firstName": "ExistingPatient",
"lastName": "ExistingPatient",
"gender": "female",
"sex": "female",
"dateOfBirth": "2000-11-11"
},
"patient": {
"patientGuid": "f36af515-09ba-4551-a5c2-e6680fc41886",
"address": {
"line1": "1234 yay",
"line2": "st",
"city": "portland",
"state": "CA",
"postalCode": "94949"
}
},
"visitDetails": {
"declaration": "other",
"departmentId": "301546001",
"ehrSystemName": "org.providence.dig.epic.provwamt",
"nationalProviderId": "1629394572",
"slotId": "eyJkYXRlIjoiMjAyMy0wMS0wNSIsInRpbWUiOiIxNDo0MDowMCIsImR1cmF0aW9uIjozMCwidmlzaXRUeXBlSWQiOiIxMDAwMDAzIiwidmlzaXRUeXBlIjoiTmV3UGF0aWVudCIsInRpbWV6b25lIjoiQW1lcmljYS9Mb3NfQW5nZWxlcyIsImRlcGFydG1lbnRJZCI6IjMwMTU0NjAwMSIsInNsb3RUeXBlIjoiTmV3UGF0aWVudCIsInZlcnNpb24iOiIzLjAifQ==",
"visitReason": "ow my testing hurts",
"visitTypeId": "1000003"
}
}