API

Hard Eligibility

The hard eligibility check is done by creating a Service Eligibility resource.

1

Soft Eligibility

It’s not a strict requirement to have run a Soft Eligibility check before this. However, the Hard Eligibility check will always try to resolve the patient’s benefits. This API has a usage cost, Soft Eligibility does not. Consider always running Soft Eligibility first, even if the UX does not make a distinction to the patient.

2

Patient Input

Use the Payer Search API for the Patient’s discovery of Payers. This API is designed to be used to drive autocomplete. An empty string for the query, will return the top national payers.

Use the accepted list of States.

Patients will need to input the following information.

  • First Name
  • Last Name
  • Date of Birth
  • State
  • Payer
  • Member ID (optional)

Inspect Payer.memberId to determine whether to prompt for their Member ID. Be prepared to prompt for Member ID regardless, if an error code requires it (see below).

3

Resolve the Policy

The first step, is to resolve the Patient’s Policy, using the Create Policy API.

Whether the benefits are found or not, or if they’re active or inactive, the Policy object will be created. Inspect the status field, to determine what to do.

  • CONFIRMED the Policy and benefits were found, move on to the next step. Note, the Policy may be found but with inactive coverage.
  • INVALID the Payer was reached, and the benefits could not be found, review the errors (below)
  • UNKNOWN the benefits for this payer aren’t available. This is possible if a Payer’s system is down, or there are unexpected errors from the clearing house. Whether the patient is moved through your UX here, is your choice. If you proceed, a complete and valid benefits check must be completed before the visit.

Other status values (PENDING, REVALIDATING) are not expected from this endpoint.

If the Policy status is INVALID, inspect the errors field. See the Policy Errors for detail.

Note, there are some errors that require you to override a Payer’s optional Member ID behavior, and collect it (72 and 76).

4

Create the Service Eligibility

This flow creates an “anonymous” Service Eligibility, untied to a Patient or Service object. This is the most straightforward use case. If you have a Patient resource already, contact us to discuss implementation.

Use the Create Service Eligibility endpoint. Feed through the Policy ID from the previous step, as a single entry in the policyIds array.

Status

Evaluate the status value, we’re looking for ELIGIBLE to proceed. Given any other value, show appropriate messages.

  • PENDING should never be received here
  • UNINSURED Policy was found but is not active
  • INELIGIBLE Policy is active, but the required benefits aren’t available
  • INEFFECTIVE Policy is active, the service is covered, but the date of service falls outside coverage dates

Providers

As with Soft Eligibility, the services may be covered by the patient’s insurance but your organization may not have Providers available. See the providers array, there must be at least one to proceed. x

Supporting multiple Provider types

If your workflow allows patients to schedule across multiple Provider Types, call the Create Service Eligibility endpoint with each Service Type in parallel. Combine the lists of Providers before filtering your schedule. This does not result in multiple “hard checks”, paid requests through to the Payer.

5

Estimate

See the patientResponsibility field for an estimate and a breakdown. Values are in USD cents. The total value is the amount expected to be paid, other fields describe the split.

The fallback values indicate a potentially unknown, or “maximum” amount. Generally, UX should indicate that the patient’s normal copayments, deductibles and coinsurance’s apply.

The oop values breakdown the waived amounts (the amounts that were calculated, but deducted from the total due to already-met OOP limits).

In the Sandbox environment, use the Test Payers to test out your UI with all permutations of PR.

6

Patients / Services

The above integration does not create Patient/Service resources. See the Create Patient and Create Service API’s.

If you have the pre-reqs for creating these (a User in your system, an Appointment to map to), there are other ways to manage the Policy and Service Eligibility - talk to us if this is an option.