Overview

The eligibility check integration exposes a $candid-check-eligibility custom operation on the CoverageEligibilityRequest resource. It performs a real-time, pre-encounter eligibility check routed through Stedi, and returns a CoverageEligibilityResponse with the patient's benefit details mapped to FHIR.

Pre-encounter timing

Running eligibility checks before the visit lets you catch lapsed coverage or incorrect plan information before care is delivered — when you can still address it with the patient, collect the correct co-pay at the door, or avoid a claim denial entirely. Candid also runs an automatic post-encounter check (free) as part of its rules engine, but pre-encounter checks give you the earliest possible signal.

Required Resources

• patient
• provider
• insurer
• insurance.coverage
• subscriber
• beneficiary

CoverageEligibilityRequest
Patient (Subscriber)
Patient (Beneficiary)
Coverage
subscriberId: MEM123
subscriber: Patient ref
beneficiary: Patient ref

Organization (Provider)
identifier:
system: http://hl7.org/fhir/sid/us-npi

Organization (Payer)
identifier:
system: https://www.stedi.com/healthcare/network
_or_ https://www.joincandidhealth.com/chc-payerid

CoverageEligibilityRequest

Coverage

If subscriber and beneficiary are different people (e.g. a child on a parent's plan), both must be populated and the bot will include a dependent field in the eligibility request.

Organization (Provider)

Organization (Payer)

The payer identifier system for eligibility checks differs from claim submission — this API routes through Stedi, so use the Stedi payer network ID when available:

Running a Check

Invoke the operation against a stored CoverageEligibilityRequest:

const response = await medplum.post(
  medplum.fhirUrl('CoverageEligibilityRequest', request.id, '$candid-check-eligibility')
);

Or at the type level with a CoverageEligibilityRequest in the request body:

POST {base}/fhir/R4/CoverageEligibilityRequest/$candid-check-eligibility

Response

On success the operation returns a CoverageEligibilityResponse saved to Medplum with coverage status, benefit details, and plan information mapped from the Stedi 271 response. A raw snapshot of the full Candid response is also stored as a DocumentReference (identifier system: https://candidhealth.com/eligibility-check) for debugging.

{
  "resourceType": "CoverageEligibilityResponse",
  "status": "active",
  "purpose": ["benefits"],
  "patient": { "reference": "Patient/{id}" },
  "created": "2025-01-15",
  "insurer": { "reference": "Organization/{payer-id}" },
  "insurance": [
    {
      "coverage": { "reference": "Coverage/{id}" },
      "inforce": true,
      "item": [
        {
          "category": { "coding": [{ "code": "30", "display": "Health Benefit Plan Coverage" }] },
          "benefit": [
            { "type": { "text": "CoinsurancePercent" }, "allowedUnsignedInt": 20 }
          ]
        }
      ]
    }
  ]
}

The top-level status reflects the eligibility outcome:

Staging Mock Scenarios

Candid staging supports mock eligibility checks using specific magic values — no real payer is contacted. Mocks require provider NPI 1999999984.