Provider Service

The Provider Service is capable of retrieving details about a specific healthcare provider, as well as scheduling appointments with a specific provider.

Getting Provider Information

The ProviderService.getProvider method provides an API to retrieve information about a specific healthcare provider.

This includes but is not limited to:

  • Name
  • Credentials
  • Departments
  • Types of visits they accept
  • Active status

The ProviderService.getProvider method requires the national identifier of the provider to retrieve information about. This National Provider Identifier (NPI) needs to be retrieved or pre-determined from a source outside DexCare.

The method returns a Provider object that contains details about the requested provider.

  • let dexcareSDK = DexcareSDK(configuration: ...)

dexcareSDK.providerService.getProvider(
    providerNationalId: "2323233"),  // The method requires an NPI to look up information about the provider.
    success: { provider in
        // provider object contains info about the requested provider
    },
    failure: { error in
            // handle the error, show an error dialog, log the error, etc.
    }
// Swift Concurrency
do {
    let provider = try dexcareSDK.providerService.getProvider(providerNationalId: "23232323")
} catch {
     // handle the error, show an error dialog, log the error, etc.
}

  • DexCareSDK.providerService.getProvider("1234567890") // The method requires an NPI to look up information about the provider.
    .subscribe({ provider ->
        // provider object contains info about the requested provider
    }, {
        // handle the error, show an error dialog, log the error, etc.
    })

Getting a Provider’s Available Time Slots

In order to schedule a visit directly with a Provider, you first need to fetch available time slots.

The ProviderService.getProviderTimeslots method provides an API to fetch available time slots for a Provider. The method has 4 parameters:

  1. The NPI of the Provider to fetch time slots for
  2. The id of the visit type to fetch time slots for
  3. Optionally, the start date of the time range to search. Must be before the end date, and not in the past. Defaults to the current day.
  4. Optionally, the end date of the time range to search. Must be after the start date, and not further than the result of ProviderService.getMaxLookaheadDays days in the future. Defaults to one week ahead of the current day.
  • let dexcareSDK = DexcareSDK(configuration: ...)
dexcareSDK.providerService.getProviderTimeslots(
    providerNationalId: providerNationalId,
    visitTypeShortName: .illNess,
    startDate: startDate, // Passing in nil to both startDate/EndDate will default to 7 days ahead. 
    endDate: endDate, // NOTE: The endDate cannot be further in the future than the result of ProviderService.getMaxLookaheadDays!
    success: { providerTimeSlot in
        // providerTimeSlot contains a list of ScheduleDay, each containing TimeSlots for a day in the requested date range.
        // Each ScheduleDay contains a list of TimeSlot
        // Each TimeSlot represents a time at which the Provider is available to see a patient.
        // These models are the same for the Retail and Provider Services.
        // You'll want to display the time slots to the user for them to select one.
    },
    failure: { error in
        // handle the error, show an error dialog, log the error, etc.
    }
)

// Swift Concurrency
do {
    let providerTimeslot = try dexcareSDK.providerService.getProviderTimeslots(
    providerNationalId: .illNess,
    visitTypeShortName: visitTypeId,
    startDate: startDate,
    endDate: endDate)
} catch {
  // handle the error, show an error dialog, log the error, etc.
}

  • DexCareSDK.providerService.getProviderTimeslots(
    providerNationalId,
    providerVisitTypeId,
    startDate = Calendar.getInstance().apply { // optionally, you can change the startDate of the time range to search.
        add(Calendar.DAY_OF_YEAR, 1) // This sets the startDate to tomorrow.
    }.time,
    endDate = Calendar.getInstance().apply { // optionally, you can change the endDate of the time range to search.
        add(Calendar.DAY_OF_YEAR, 30) // This sets the endDate to next month.
    }.time,
    // NOTE: The endDate cannot be further in the future than the result of ProviderService.getMaxLookaheadDays!
).subscribe({ providerTimeSlot ->
    // providerTimeSlot contains a list of ScheduleDay, each containing TimeSlots for a day in the requested date range.
    // Each ScheduleDay contains a list of TimeSlot
    // Each TimeSlot represents a time at which the Provider is available to see a patient.
    // These models are the same for the Retail and Provider Services.
    // You'll want to display the time slots to the user for them to select one.
}, {
    // handle the error, show an error dialog, log the error, etc.
})

Determining the Max Lookahead Days

As stated above, the ProviderService.getProviderTimeslots has an upper limit on how far in the future it can look for time slots.

That limit can vary, and so ProviderService.getMaxLookaheadDays provides an API to determine that upper limit. The method requires two parameters:

  1. The ProviderVisitType.shortName of the type of visit to get the max lookahead days for
  2. The EHR system name, used to get the max lookahead days. A ProviderDepartment (returned from ProviderService.getProvider method) has an ehrSystemName property that can be used here.
  • let dexcareSDK = DexcareSDK(configuration: ...)
dexcareSDK.providerService.getMaxLookaheadDays(
    visitTypeShortName: visitTypeShortName,
    ehrSystemName: ehrSystemName,
    success: { maxDaysLookahed in
       // An Int is returned, representing the maximum number of days in the future that ProviderService.getProviderTimeslots can search.
    },
    failure: { error in
       // handle the error, show an error dialog, log the error, etc.
    }
)

// Swift Concurrency
do {
    let maxDaysLookahead = try dexcareSDK.providerService.getMaxLookaheadDays(
    visitTypeShortName: visitTypeShortName,
    ehrSystemName: ehrSystemName)
} catch {
    // handle the error, show an error dialog, log the error, etc.
}

  • DexCareSDK.providerService.getMaxLookaheadDays(
    visitTypeShortName,
    ehrSystem
).subscribe({
    // An Int is returned, representing the maximum number of days in the future that ProviderService.getProviderTimeslots can search.
}, {
    // handle the error, show an error dialog, log the error, etc.
})

Collecting Payment Information

One of the required parameters for scheduling a provider visit is the patient’s payment/billing information.

Please see the Payment Method for more detail on how to collect the patient’s payment information.

ProviderVisitInformation

ProviderVisitInformation is a model that contains additional information required to book a Provider visit.

The ProviderVisitInformation has several parameters:

  • visitReason - A short description describing the reason for scheduling the provider visit.
  • patientDeclaration An enum used to determine who the visit should be scheduled for.
  • userEmail This should always be a non-empty email address which can be used to contact the app user. Note: the patient email address as returned by Epic is not guaranteed to be present. For this reason, it is recommended to always collect this information from an alternative source, e.g. Auth0 email.
  • contactPhoneNumber A phone number that can be used to communicate with the patient.
  • actorRelationshipToPatient - optional. When booking for a dependent, this must be filled in. It is not required when booking for the logged in patient.

Booking a visit to a Provider

Finally, to schedule a visit directly with a Provider, the ProviderService.scheduleProviderVisit method is available.

The method is similar to the Retail and Virtual scheduling calls in terms of required parameters.

  1. paymentMethod - The payment method. See the Payment Method page.
  2. providerVisitInformation - The ProviderVisitInformation object containing details about the visit request.
  3. timeSlot - The TimeSlot object as selected by the user.
  4. ehrSystemName - The EHR system name of the ProviderDepartment, in which the visit will be scheduled.
  5. patientDexCarePatient - A DexCarePatient object containing the demographics of the patient. This could be either the result of PatientService.getPatient in the case of a “myself” visit, or the result of PatientService.findOrCreateDependentPatient in the case of a “Someone else” visit. See the Patient Service guide for details.
  6. actorDexCarePatient - Only required in the case of a “Someone else” visit. This should bethe demographics of the person doing the scheduling in place of the patient. This should be the result of PatientService.getPatient for “someone else” visits, and null for “myself” visits.
  • let dexcareSDK = DexcareSDK(configuration: ...)
dexcareSDK.providerService.scheduleProviderVisit(
    paymentMethod: paymentMethod,
    providerVisitInformation: providerVisitInformation,
    timeSlot: timeSlot,
    ehrSystemName: ehrSystemName,
    patientDexCarePatient: patientDexCarePatient,
    actorDexCarePatient: actorDexCarePatient,
    success: { scheduleProviderVisit in
         // A ScheduledProviderVisit object is returned, which contains various details about the scheduled visit.
    },
    failure: { error in
        // handle the error, show an error dialog, log the error, etc.
    }
)

// Swift Concurrency
do {
    let scheduleProviderVisit = dexcareSDK.providerService.scheduleProviderVisit(
    paymentMethod: paymentMethod,
    providerVisitInformation: providerVisitInformation,
    timeSlot: timeSlot,
    ehrSystemName: ehrSystemName,
    patientDexCarePatient: patientDexCarePatient,
    actorDexCarePatient: actorDexCarePatient)
} catch {
         // handle the error, show an error dialog, log the error, etc.
}

  • DexCareSDK.providerService.scheduleProviderVisit(
    paymentMethod,
    providerVisitInformation,
    timeSlot,
    ehrSystemName,
    patientDexCarePatient,
    actorDexCarePatient = null
).subscribe({ scheduledProviderVisit -> 
    // A ScheduledProviderVisit object is returned, which contains various details about the scheduled visit.
}, {
    // handle the error, show an error dialog, log the error, etc.
})