Implementation Guide

What This Engine Does

The FHIR Risk Assessment Engine evaluates diagnosis codes submitted by Medicare Advantage organizations to identify codes that are likely to be flagged in CMS or OIG audits. It cross-references each diagnosis against supporting clinical evidence — encounters, medications, and procedures — to determine whether the code is adequately supported.

Why It Matters

CMS recovers billions annually from Medicare Advantage plans through Risk Adjustment Data Validation (RADV) audits. The OIG has identified specific diagnosis categories that are frequently miscoded, leading to improper payments. This engine targets the four highest-risk categories:

How It Works — At a Glance

API Endpoint

Accepted Input Formats

The engine accepts three input structures. Use whichever fits your system best:

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Condition",
        "id": "cond-001",
        "code": {
          "coding": [{
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "I63.9",
            "display": "Cerebral infarction, unspecified"
          }]
        },
        "subject": { "reference": "Patient/pat-001" },
        "onsetDateTime": "2024-09-15"
      }
    },
    {
      "resource": {
        "resourceType": "Encounter",
        "id": "enc-001",
        "class": { "code": "AMB" },
        "subject": { "reference": "Patient/pat-001" },
        "period": { "start": "2024-09-15" }
      }
    }
  ]
}

[
  {
    "resourceType": "Condition",
    "id": "cond-001",
    "code": {
      "coding": [{
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "code": "I21.3",
        "display": "STEMI of unspecified site"
      }]
    },
    "subject": { "reference": "Patient/12345" },
    "onsetDateTime": "2024-09-01"
  },
  {
    "resourceType": "Encounter",
    "id": "enc-001",
    "class": { "code": "IMP" },
    "subject": { "reference": "Patient/12345" },
    "period": { "start": "2024-09-01", "end": "2024-09-05" }
  }
]

{
  "resourceType": "Condition",
  "id": "cond-001",
  "code": {
    "coding": [{
      "system": "http://hl7.org/fhir/sid/icd-10-cm",
      "code": "C34.1",
      "display": "Malignant neoplasm of upper lobe, bronchus or lung"
    }]
  },
  "subject": { "reference": "Patient/67890" },
  "onsetDateTime": "2024-06-01"
}

FHIR Resource Reference

Each resource type plays a specific role in the risk assessment. The more supporting resources you include, the more accurate the assessment.

Supported Code Systems

The engine recognizes the following ICD-10 code system URIs in Condition.code.coding[].system:

• http://hl7.org/fhir/sid/icd-10
• http://hl7.org/fhir/sid/icd-10-cm
• http://www.cms.gov/Medicare/Coding/ICD10

Encounter Class Codes

The engine checks the Encounter.class.code field for inpatient context. Recognized values:

Response Structure

Every successful response follows this structure:

{
  "status": "success",
  "diagnosis_results": [
    {
      "code": "I63.9",
      "description": "Cerebral infarction, unspecified",
      "risk_level": "high",
      "reason": "One stroke diagnosis on physician claim, no inpatient/outpatient claim"
    },
    {
      "code": "I21.3",
      "description": "STEMI of unspecified site",
      "risk_level": "low",
      "reason": "No risk factors identified"
    }
  ]
}

Field-by-Field Breakdown

Understanding Risk Levels

What Triggers Each Risk Level

Error Responses

When something goes wrong, the response includes an error field instead of diagnosis_results:

{
  "status": "error",
  "error": "No data provided or invalid JSON format"
}

Let's walk through a complete example: a patient with an acute stroke diagnosis seen in an outpatient setting.

Step 1 — Build Your FHIR Bundle

Assemble the patient's Condition (the diagnosis) and any supporting Encounter data into a FHIR Bundle:

{
  "resourceType": "Bundle",
  "type": "collection",
  "entry": [
    {
      "resource": {
        "resourceType": "Condition",
        "id": "cond-stroke-01",
        "code": {
          "coding": [{
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "I63.9",
            "display": "Cerebral infarction, unspecified"
          }]
        },
        "subject": { "reference": "Patient/pat-100" },
        "onsetDateTime": "2024-09-15"
      }
    },
    {
      "resource": {
        "resourceType": "Encounter",
        "id": "enc-outpatient-01",
        "class": { "code": "AMB" },
        "subject": { "reference": "Patient/pat-100" },
        "period": {
          "start": "2024-09-15",
          "end": "2024-09-15"
        }
      }
    }
  ]
}

Step 2 — Send the Request

• cURL
• Python
• JavaScript

curl -X POST https://your-domain.com/api/assess \
  -H "Content-Type: application/json" \
  -d @bundle.json

import requests
import json

with open("bundle.json") as f:
    bundle = json.load(f)

response = requests.post(
    "https://your-domain.com/api/assess",
    json=bundle
)

results = response.json()
for dx in results["diagnosis_results"]:
    print(f"{dx['code']}: {dx['risk_level']} — {dx['reason']}")

const bundle = { /* your FHIR Bundle */ };

const response = await fetch("/api/assess", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(bundle)
});

const data = await response.json();
data.diagnosis_results.forEach(dx => {
  console.log(`${dx.code}: ${dx.risk_level} — ${dx.reason}`);
});

Step 3 — Read the Response

Because the only encounter is ambulatory (AMB) — not inpatient — the engine flags the stroke diagnosis as high risk:

{
  "status": "success",
  "diagnosis_results": [
    {
      "code": "I63.9",
      "description": "Cerebral infarction, unspecified",
      "risk_level": "high",
      "reason": "One stroke diagnosis on physician claim, no inpatient/outpatient claim"
    }
  ]
}

Step 4 — Fix and Re-submit

If you add an inpatient encounter and re-submit, the risk level drops:

{
  "resource": {
    "resourceType": "Encounter",
    "id": "enc-inpatient-01",
    "class": { "code": "IMP" },
    "subject": { "reference": "Patient/pat-100" },
    "period": {
      "start": "2024-09-15",
      "end": "2024-09-20"
    }
  }
}

New response:

{
  "status": "success",
  "diagnosis_results": [
    {
      "code": "I63.9",
      "description": "Cerebral infarction, unspecified",
      "risk_level": "low",
      "reason": "No risk factors identified"
    }
  ]
}

• Include all supporting resources. Encounters, medications, and procedures dramatically improve accuracy.
• Set onsetDateTime on every Condition. Without it, time-window rules cannot fire.
• Use standard code systems. Stick to the three recognized ICD-10 URIs listed in Section [2].
• Batch your submissions. Send all of a patient's resources in one Bundle for complete assessment.
• Review all HIGH results. Each comes with a specific, actionable reason.