Prior Authorization¶

Overview¶

Some procedures require prior authorization from the insurance payer before they can be performed. This workflow checks clinical necessity and submits the authorization request.

Prior Auth Evaluation¶

Contract¶

`evaluate_prior_auth`

Evaluate whether a procedure requires prior authorization and if so, request it. Steps: 1. Fetch patient record and insurance coverage 2. Check clinical guidelines for medical necessity 3. If required, submit prior auth request to payer

Inputs

Parameter Type Default

patient_id str —

procedure_code str —

Output

return PriorAuthResult —

PriorAuthResult Final prior authorization evaluation result.

Parameter	Type	Default
`status` *	`str`	—
`reason`	`str \| None`	None
`auth_id`	`str \| None`	None
`valid_from`	`str \| None`	None
`valid_until`	`str \| None`	None
`approved_units`	`int \| None`	None
`clinical_guideline`	`str \| None`	None

Execution Flow¶

Sequence diagram — evaluate_prior_auth

sequenceDiagram
    participant evaluate_prior_auth
    participant CheckClinicalGuidelines as ClinicalDB / CheckClinicalGuidelines
    participant FetchPatientRecord as EHR / FetchPatientRecord
    participant SubmitPriorAuth as InsurancePayer / SubmitPriorAuth
    participant VerifyInsuranceCoverage as InsurancePayer / VerifyInsuranceCoverage
    evaluate_prior_auth->>+FetchPatientRecord: patient_id
    FetchPatientRecord-->>-evaluate_prior_auth: response
    evaluate_prior_auth->>+VerifyInsuranceCoverage: patient.member_id, procedure_code
    VerifyInsuranceCoverage-->>-evaluate_prior_auth: response
    evaluate_prior_auth->>+CheckClinicalGuidelines: procedure_code, patient.conditions
    CheckClinicalGuidelines-->>-evaluate_prior_auth: response
    evaluate_prior_auth->>+SubmitPriorAuth: {'patient_id': patient_id, 'member_id': patient.member_id, 'procedure_code': procedure_code, 'clinical_justification': clinical.guideline, 'evidence_level': clinical.evidence_level}
    SubmitPriorAuth-->>-evaluate_prior_auth: response

Source Code¶

def evaluate_prior_auth(patient_id: str, procedure_code: str) -> PriorAuthResult:
    """Evaluate whether a procedure requires prior authorization and if so, request it.

    Steps:
    1. Fetch patient record and insurance coverage
    2. Check clinical guidelines for medical necessity
    3. If required, submit prior auth request to payer
    """
    patient = FetchPatientRecord().call(patient_id)
    coverage = VerifyInsuranceCoverage().call(patient.member_id, procedure_code)

    if not coverage.active:
        return PriorAuthResult(
            status="DENIED",
            reason="Insurance not active",
        )

    clinical = CheckClinicalGuidelines().call(procedure_code, patient.conditions)

    if not clinical.medically_necessary:
        return PriorAuthResult(
            status="DENIED",
            reason="Procedure not deemed medically necessary",
            clinical_guideline=clinical.guideline,
        )

    auth_result = SubmitPriorAuth().call({
        "patient_id": patient_id,
        "member_id": patient.member_id,
        "procedure_code": procedure_code,
        "clinical_justification": clinical.guideline,
        "evidence_level": clinical.evidence_level,
    })

    return PriorAuthResult(
        status=auth_result.status.upper(),
        auth_id=auth_result.auth_id,
        valid_from=auth_result.valid_from,
        valid_until=auth_result.valid_until,
        approved_units=auth_result.approved_units,
        clinical_guideline=clinical.guideline,
    )

Try it Live¶

Playground — `evaluate_prior_auth`

Evaluate whether a procedure requires prior authorization and if so, request it. Steps: 1. Fetch patient record and insurance coverage 2. Check clinical guidelines for medical necessity 3. If required, submit prior auth request to payer

View source code

def evaluate_prior_auth(patient_id: str, procedure_code: str) -> PriorAuthResult:
    """Evaluate whether a procedure requires prior authorization and if so, request it.

    Steps:
    1. Fetch patient record and insurance coverage
    2. Check clinical guidelines for medical necessity
    3. If required, submit prior auth request to payer
    """
    patient = FetchPatientRecord().call(patient_id)
    coverage = VerifyInsuranceCoverage().call(patient.member_id, procedure_code)

    if not coverage.active:
        return PriorAuthResult(
            status="DENIED",
            reason="Insurance not active",
        )

    clinical = CheckClinicalGuidelines().call(procedure_code, patient.conditions)

    if not clinical.medically_necessary:
        return PriorAuthResult(
            status="DENIED",
            reason="Procedure not deemed medically necessary",
            clinical_guideline=clinical.guideline,
        )

    auth_result = SubmitPriorAuth().call({
        "patient_id": patient_id,
        "member_id": patient.member_id,
        "procedure_code": procedure_code,
        "clinical_justification": clinical.guideline,
        "evidence_level": clinical.evidence_level,
    })

    return PriorAuthResult(
        status=auth_result.status.upper(),
        auth_id=auth_result.auth_id,
        valid_from=auth_result.valid_from,
        valid_until=auth_result.valid_until,
        approved_units=auth_result.approved_units,
        clinical_guideline=clinical.guideline,
    )

patient_id (str) *

procedure_code (str) *

Mock configuration

ClinicalDB / CheckClinicalGuidelines — Check clinical necessity against evidence-based guidelines (Blackbox).

medically_necessary (bool)

guideline (str)

evidence_level (str)

notes (str)

Simulate error

error_code

error_message

http_code

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 / SubmitPriorAuth — Submit a prior authorization request to the payer (Blackbox).

auth_id (str)

status (str)

valid_from (str)

valid_until (str)

approved_units (int)

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

Test cases

No test cases saved yet.

External Services¶

Insurance Payer — Prior Auth Submission¶

class SubmitPriorAuth(ExternalService):
    """Submit a prior authorization request to the payer (Blackbox)."""

    component_name = "InsurancePayer"

    def execute(self, auth_request: dict) -> PriorAuthApproval:
        pass  # type: ignore[return-value]

    def mock(self, auth_request: dict) -> MockResponse:
        return MockResponse(data=PriorAuthApproval(
            auth_id="PA-2024-78901",
            status="approved",
            valid_from="2024-01-15",
            valid_until="2024-04-15",
            approved_units=12,
        ))

Clinical Guidelines Database¶

class CheckClinicalGuidelines(ExternalService):
    """Check clinical necessity against evidence-based guidelines (Blackbox)."""

    component_name = "ClinicalDB"

    def execute(self, procedure_code: str, conditions: list) -> ClinicalGuideline:
        pass  # type: ignore[return-value]

    def mock(self, procedure_code: str, conditions: list) -> MockResponse:
        return MockResponse(data=ClinicalGuideline(
            medically_necessary=True,
            guideline="AHA-2023-HBP-MGMT",
            evidence_level="A",
            notes="Recommended for patients with uncontrolled hypertension",
        ))

Prior Authorization¶

Overview¶

Prior Auth Evaluation¶

Contract¶

evaluate_prior_auth

Execution Flow¶

Source Code¶

Try it Live¶

Playground — evaluate_prior_auth

External Services¶

Insurance Payer — Prior Auth Submission¶

Clinical Guidelines Database¶

`evaluate_prior_auth`

Playground — `evaluate_prior_auth`