Eligibility Verification

Insurance Eligibility Check

Verifies whether a patient's insurance covers a specific medical service.

Contract

check_eligibility

Verify whether a patient is eligible for a specific medical service. Retrieves patient record, checks insurance coverage, and returns a combined eligibility determination.

Inputs
Parameter	Type	Default
patient_id	str	—
service_code	str	—
Output
return	EligibilityResult	—
EligibilityResult Eligibility determination for a medical service. Parameter Type Default eligible * bool — patient_id * str — reason str | None None plan str | None None copay float | None None deductible_remaining float | None None

Execution Flow

Sequence diagram — check_eligibility

sequenceDiagram
    participant check_eligibility
    participant FetchPatientRecord as EHR / FetchPatientRecord
    check_eligibility->>+FetchPatientRecord: patient_id
    FetchPatientRecord-->>-check_eligibility: response

Source Code

def check_eligibility(patient_id: str, service_code: str) -> EligibilityResult:
    """Verify whether a patient is eligible for a specific medical service.

    Retrieves patient record, checks insurance coverage, and returns
    a combined eligibility determination.
    """
    patient = FetchPatientRecord().call(patient_id)

    try:
        coverage = VerifyInsuranceCoverage().call(
            patient.member_id, service_code
        )
    except ServiceError:
        return EligibilityResult(
            eligible=False,
            reason="Unable to verify insurance coverage",
            patient_id=patient_id,
        )

    if not coverage.active:
        return EligibilityResult(
            eligible=False,
            reason="Insurance plan is not active",
            patient_id=patient_id,
        )

    # Map service code to category
    service_category = service_code.split("-")[0] if "-" in service_code else service_code

    if service_category not in coverage.covered_services:
        return EligibilityResult(
            eligible=False,
            reason=f"Service category '{service_category}' is not covered by plan",
            patient_id=patient_id,
            plan=coverage.plan,
        )

    return EligibilityResult(
        eligible=True,
        patient_id=patient_id,
        plan=coverage.plan,
        copay=coverage.copay,
        deductible_remaining=coverage.deductible_remaining,
    )

Try it Live

Playground — check_eligibility

Verify whether a patient is eligible for a specific medical service. Retrieves patient record, checks insurance coverage, and returns a combined eligibility determination.

View source code

def check_eligibility(patient_id: str, service_code: str) -> EligibilityResult:
    """Verify whether a patient is eligible for a specific medical service.

    Retrieves patient record, checks insurance coverage, and returns
    a combined eligibility determination.
    """
    patient = FetchPatientRecord().call(patient_id)

    try:
        coverage = VerifyInsuranceCoverage().call(
            patient.member_id, service_code
        )
    except ServiceError:
        return EligibilityResult(
            eligible=False,
            reason="Unable to verify insurance coverage",
            patient_id=patient_id,
        )

    if not coverage.active:
        return EligibilityResult(
            eligible=False,
            reason="Insurance plan is not active",
            patient_id=patient_id,
        )

    # Map service code to category
    service_category = service_code.split("-")[0] if "-" in service_code else service_code

    if service_category not in coverage.covered_services:
        return EligibilityResult(
            eligible=False,
            reason=f"Service category '{service_category}' is not covered by plan",
            patient_id=patient_id,
            plan=coverage.plan,
        )

    return EligibilityResult(
        eligible=True,
        patient_id=patient_id,
        plan=coverage.plan,
        copay=coverage.copay,
        deductible_remaining=coverage.deductible_remaining,
    )

patient_id (str) *

service_code (str) *

Mock configuration

EHR / FetchPatientRecord — Retrieve patient demographics and medical history (Blackbox).

patient_id (str)

age (int)

conditions (list[str])

member_id (str)

Simulate error

error_code

error_message

http_code

InsurancePayer / VerifyInsuranceCoverage — Real-time eligibility check with the insurance payer (Blackbox).

active (bool)

plan (str)

copay (float)

deductible_remaining (float)

out_of_pocket_max (float)

covered_services (list[str])

Simulate error

error_code

error_message

http_code

Run rule

Save as test case

Test cases

• No test cases saved yet.

---

Patient Cost Estimation

Estimates the patient's out-of-pocket cost considering deductible, copay, and plan limits.

Contract

estimate_patient_cost

Estimate the patient's out-of-pocket cost for a service. Considers deductible, copay, and plan maximums.

Inputs
Parameter	Type	Default
patient_id	str	—
service_code	str	—
billed_amount	float	—
Output
return	CostEstimate	—
CostEstimate Patient out-of-pocket cost estimate. Parameter Type Default covered * bool — reason str | None None plan str | None None billed_amount float | None None deductible_applied float | None None copay float | None None patient_responsibility * float — insurance_pays float | None None

Source Code

def estimate_patient_cost(patient_id: str, service_code: str, billed_amount: float) -> CostEstimate:
    """Estimate the patient's out-of-pocket cost for a service.

    Considers deductible, copay, and plan maximums.
    """
    eligibility = check_eligibility(patient_id, service_code)

    if not eligibility.eligible:
        return CostEstimate(
            covered=False,
            reason=eligibility.reason,
            patient_responsibility=billed_amount,
        )

    deductible = eligibility.deductible_remaining
    copay = eligibility.copay

    if billed_amount <= deductible:
        patient_pays = billed_amount
    else:
        patient_pays = deductible + copay

    return CostEstimate(
        covered=True,
        plan=eligibility.plan,
        billed_amount=billed_amount,
        deductible_applied=min(billed_amount, deductible),
        copay=copay if billed_amount > deductible else 0,
        patient_responsibility=round(patient_pays, 2),
        insurance_pays=round(billed_amount - patient_pays, 2),
    )

Try it Live

Playground — estimate_patient_cost

Estimate the patient's out-of-pocket cost for a service. Considers deductible, copay, and plan maximums.

View source code

def estimate_patient_cost(patient_id: str, service_code: str, billed_amount: float) -> CostEstimate:
    """Estimate the patient's out-of-pocket cost for a service.

    Considers deductible, copay, and plan maximums.
    """
    eligibility = check_eligibility(patient_id, service_code)

    if not eligibility.eligible:
        return CostEstimate(
            covered=False,
            reason=eligibility.reason,
            patient_responsibility=billed_amount,
        )

    deductible = eligibility.deductible_remaining
    copay = eligibility.copay

    if billed_amount <= deductible:
        patient_pays = billed_amount
    else:
        patient_pays = deductible + copay

    return CostEstimate(
        covered=True,
        plan=eligibility.plan,
        billed_amount=billed_amount,
        deductible_applied=min(billed_amount, deductible),
        copay=copay if billed_amount > deductible else 0,
        patient_responsibility=round(patient_pays, 2),
        insurance_pays=round(billed_amount - patient_pays, 2),
    )

patient_id (str) *

service_code (str) *

billed_amount (float) *

Mock configuration

EHR / FetchPatientRecord — Retrieve patient demographics and medical history (Blackbox).

patient_id (str)

age (int)

conditions (list[str])

member_id (str)

Simulate error

error_code

error_message

http_code

InsurancePayer / VerifyInsuranceCoverage — Real-time eligibility check with the insurance payer (Blackbox).

active (bool)

plan (str)

copay (float)

deductible_remaining (float)

out_of_pocket_max (float)

covered_services (list[str])

Simulate error

error_code

error_message

http_code

Run rule

Save as test case

Test cases

• No test cases saved yet.