RCI for Clearinghouses

Claim received from provider
    │
    ├─ Parse CCN from claim
    ├─ RCI: GET /v1/knowledge/layers/{ccn}
    │       Returns L1-L4 (no CPT needed for form/POS/payer checks)
    │
    ├─ Validate billing form against L2
    ├─ Validate POS code against L3
    ├─ Validate timely filing against L4
    │
    ├─ If CPT present:
    │   ├─ RCI: POST /v1/knowledge/resolve (full L1-L6)
    │   ├─ Validate modifiers against L3/L5
    │   └─ Calculate expected payment from L6 (for anomaly detection)
    │
    ├─ Pass → Route to payer
    └─ Fail → Return to provider with specific correction needed

import httpx
import asyncio

async def enrich_claims(claims: list[dict], api_key: str):
    """Enrich a batch of claims with knowledge, grouped by facility."""
    facility_cache = {}

    async with httpx.AsyncClient(
        base_url="https://api-dev.rcintell.com",
        headers={"X-API-Key": api_key},
        timeout=30.0,
    ) as client:
        for claim in claims:
            ccn = claim["facility_ccn"]

            if ccn not in facility_cache:
                resp = await client.get(f"/v1/knowledge/layers/{ccn}")
                facility_cache[ccn] = resp.json()

            facility_knowledge = facility_cache[ccn]

            if claim.get("cpt_code"):
                resp = await client.post("/v1/knowledge/resolve", json={
                    "ccn": ccn,
                    "cpt": claim["cpt_code"],
                    "payer": claim.get("payer", "Medicare"),
                })
                claim["knowledge"] = resp.json()
            else:
                claim["knowledge"] = facility_knowledge

            claim["validation_errors"] = validate_against_knowledge(
                claim, claim["knowledge"]
            )

    return claims


def validate_against_knowledge(claim: dict, knowledge: dict) -> list[str]:
    errors = []
    layers = knowledge.get("layers", [])

    for layer in layers:
        layer_name = layer.get("layer", "")

        if layer_name == "l2_facility_type":
            expected_form = layer.get("billing_form")
            if expected_form and claim.get("billing_form") != expected_form:
                errors.append(f"Billing form mismatch: expected {expected_form}")

        if layer_name == "l3_care_setting":
            expected_pos = layer.get("pos_code")
            if expected_pos and str(claim.get("pos_code")) != str(expected_pos):
                errors.append(f"POS code mismatch: expected {expected_pos}")

        if layer_name == "l4_payer":
            filing_limit = layer.get("timely_filing_federal")
            if filing_limit:
                pass  # check claim date_of_service vs today

    return errors

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────┐
│   Provider /    │     │   Your Clearinghouse  │     │   Payer     │
│   EHR System    │────►│                       │────►│             │
│                 │     │   ┌─────────────────┐ │     │             │
│   837P / 837I   │     │   │  RCI Knowledge  │ │     │   Adjudicate│
│                 │     │   │  Validation     │ │     │             │
│                 │◄────│   │  Enrichment     │ │◄────│   835 ERA   │
│   Rejections    │     │   └─────────────────┘ │     │             │
└─────────────────┘     └──────────────────────┘     └─────────────┘