Risk Adjustment FHIR Models

Note that Zus Risk Adjustment features are currently in public preview and are subject to change.

MeasureReport Profiles

Risk adjustment data is stored as FHIR MeasureReport resources. There are three types:

Resource Type	Profile	Logical Identity	Purpose
Risk Gap	`individual-risk-gap`	patient + calendar year + HCC code	A potential diagnosis/coding gap for a single HCC
RAF Score	`individual-raf-score`	patient + builder + calendar year	Aggregated risk scores (potential, expected, actual) for a patient
Payer Risk Gap	`individual-payer-risk-gap`	patient + reporting period + HCC code + ICD-10 code + payer	Payer reported risk gap data

Risk Gap MeasureReport

A Risk Gap represents a single HCC gap for a patient and calendar year.

Core fields

Field	Description
`measure`	`http://zusapi.com/quality/measure/risk/CMSv28`
`subject`	Reference to the patient (e.g., `Patient/{id}`).
`period`	Calendar year window (e.g., `2025-01-01` → `2025-12-31`).
`status`	Always `"complete"`.
`type`	Always `"individual"`.
`date`	When the gap was first calculated.
`meta.profile[]`	Always contains `https://zusapi.com/fhir/StructureDefinition/risk/risk-gap`.

Within group[0] (the Risk Gap group):

Field	Description
`group[0].id`	`risk-gap`
`group[0].measureScore`	The RAF coefficient for the risk gap (when available). Example: `0.123`
`group[0].code.text`	A human readable description of the risk gap. Example: `HCC 280: Chronic Obstructive Pulmonary Disease, Interstitial Lung Disorders, and Other Chronic Lung Disorders`
`group[0].code.coding[]`	An array of HCC and ICD-10-CM codes attributable to the risk gap. You can expect: Exactly one HCC v28 code (system: `http://terminology.hl7.org/CodeSystem/cmshcc`, version `28`). At least one ICD-10-CM code (system: `http://hl7.org/fhir/sid/icd-10-cm`). (see ICD-10 codes below)

Risk gap extensions

Risk gaps use extensions to capture key workflow and explanation metadata.

Gap type

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-type`
Type	string
Values	`recapture` \| `suspect` \| `net-new`

Confidence level

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-confidence-level`
Type	integer
Values	`1`–`5` (5 = high confidence, 4 = medium confidence, 1-3 = low confidence)

Status update history

Risk gaps maintain a timeline of status updates.

Level	URL / Field	Description
Container	`https://zusapi.com/fhir/StructureDefinition/risk/status-updates`	Extension container holding the status update history.
Element	`https://zusapi.com/fhir/StructureDefinition/risk/status-update`	A single status update entry.
Field	`https://zusapi.com/fhir/StructureDefinition/status`	One of `open-gap`, `closed-gap`, `expected-to-close-1st-party`, `expected-to-close-3rd-party`, `accepted-for-review`, `dismissed`.
Field	`https://zusapi.com/fhir/StructureDefinition/created`	Timestamp when the status was created.
Field	`https://zusapi.com/fhir/StructureDefinition/createdBy`	User/system identifier (e.g., automated calculation vs user action).
Field	`https://zusapi.com/fhir/StructureDefinition/status-source`	Comma-separated list of contributing sources (e.g., rules-based, AI, payer, user).
Field (optional)	`https://zusapi.com/fhir/StructureDefinition/substatuses`	Additional structured categorization (e.g., `resolved`, `acute-in-nature`).
Field (optional)	`https://zusapi.com/fhir/StructureDefinition/note`	Free-text note.

Hierarchy relationships (superseding/superseded)

HCCs can supersede other HCCs based on CMS hierarchy rules. Risk gaps can record those relationships using:

Relationship	Extension URL
Superseded by	`https://zusapi.com/fhir/StructureDefinition/risk/hierarchical-status/superseded-by`
Superseding	`https://zusapi.com/fhir/StructureDefinition/risk/hierarchical-status/superseding`

This allows analytics and UI to distinguish "top-level" gaps from gaps that are effectively covered by a higher-priority HCC.

Related clinical objects

Risk gaps can reference additional clinical context useful for human review (e.g., labs, medications, documents).

Level	URL	Description
Container	`https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-objects`	Extension container holding related clinical objects.
Element	`https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object`	A single related clinical object reference.

ICD-10 codes

A single risk gap may include one or more ICD-10 codes associated with the HCC. ICD-10 codings can include extensions such as:

URL	Description
`https://zusapi.com/fhir/StructureDefinition/risk/last-encounter-diagnosis-recorded-date`	When that ICD-10 code last appeared as an encounter diagnosis.
`https://zusapi.com/fhir/StructureDefinition/risk/gap-source`	Identifies which source contributed the ICD-10 (e.g., rules-based, AI, payer).

Evidence references (`evaluatedResource`)

Risk gaps use evaluatedResource to link to the inputs that supported the gap:

Evidence type	What you'll see
Rules-based evidence	References to encounter-diagnosis `Condition` resources.
AI suspect evidence	References to supporting evidence resources (often with helpful display context)

Example Risk Gap resource

{
  "resourceType": "MeasureReport",
  "id": "7f8d650f-0721-44c5-b10d-fb5611330f0d",

  "meta": {
    "profile": [
      "https://zusapi.com/fhir/StructureDefinition/risk/individual-risk-gap"
    ]
  },

  "status": "complete",
  "type": "individual",
  "measure": "http://zusapi.com/quality/measure/risk/CMSv28",

  "subject": {
    "reference": "Patient/b8238362-db58-4076-8d72-972e5406b574"
  },
  "reporter": {
    "display": "Zus Health"
  },
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "date": "2026-02-12",

  "extension": [
    {
      "url": "https://zusapi.com/fhir/identifier/universal-id",
      "valueString": "9133c588-5e7d-49a4-93ac-e2fa3bab695c"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-type",
      "valueString": "suspect"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-confidence-level",
      "valueInteger": 5
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-updates",
      "extension": [
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update",
          "extension": [
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/status",
              "valueString": "open-gap"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/created",
              "valueDateTime": "2026-02-12T05:45:44.845Z"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/created-by",
              "valueString": "zus-risk-gap-calculator"
            },
            {
              "url": "https://zusapi.com/fhir/StructureDefinition/risk/status-update/status-source",
              "valueString": "zus-rules"
            }
          ]
        }
      ]
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-objects",
      "extension": [
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "Serum glucose",
            "reference": "Observation/90592907-870e-473b-9f74-afc5285146c2"
          }
        },
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "HbA1c",
            "reference": "Observation/7a759977-fe9c-45d8-8cc3-a1ebaec1153b"
          }
        },
        {
          "url": "https://zusapi.com/fhir/StructureDefinition/risk/related-clinical-object",
          "valueReference": {
            "display": "Lipid Panel",
            "reference": "Observation/90592907-870e-473b-9f74-afc5285146c2"
          }
        }
      ]
    }
  ],

  "group": [
    {
      "id": "risk-gap",
      "code": {
        "text": "HCC 38: Diabetes with Glycemic, Unspecified, or No Complications",
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
            "version": "28",
            "code": "38",
            "display": "Diabetes with Glycemic, Unspecified, or No Complications"
          },
          {
            "system": "http://hl7.org/fhir/sid/icd-10-cm",
            "code": "E11.9",
            "display": "Type 2 diabetes mellitus without complications",
            "extension": [
              {
                "url": "https://zusapi.com/fhir/StructureDefinition/risk/last-encounter-diagnosis-recorded-date",
                "valueDateTime": "2024-11-19"
              },
              {
                "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-source",
                "valueString": "zus-rules"
              }
            ]
          }
        ]
      },
      "measureScore": {
        "value": 0.166
      }
    }
  ],

  "evaluatedResource": [
    {
      "type": "Condition",
      "reference": "Condition/1ce7da26-81b6-4d89-b2a7-f5f6dcc88f09",
      "display": "ICD-10 Code: E11.9 - Suspect Encounter Diagnosis"
    }
  ]
}

RAF Score MeasureReport

A RAF Score aggregates a patient's risk scores for a calendar year.

Core fields

Field	Description
`measure`	`http://zusapi.com/quality/measure/risk/CMSv28`
`subject`	Reference to the patient (e.g., `Patient/{id}`).
`period`	Calendar year window (e.g., `2025-01-01` → `2025-12-31`).
`status`	Always `"complete"`.
`type`	Always `"individual"`.
`date`	When the score was calculated.
`meta.profile[]`	Always contains `https://zusapi.com/fhir/StructureDefinition/risk/individual-raf-score`.

The resource contains three group entries, each representing a different score:

Group ID	Description
`potential-raf-score`	Score if all non-dismissed risk gaps were paid.
`expected-raf-score`	Score using HCCs from gaps with status `expected-to-close-*` or `closed-gap`.
`actual-raf-score`	Score using only HCCs from risk gaps with status `closed-gap` (acknowledged by payer).

RAF Score extensions

RAF Score MeasureReports use extensions to describe the risk adjustment modeling process.

Gap RAF Score Model

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/gap-raf-score-model`
Type	string
Values	`CNA` (Community Non-Dual Aged)

Example RAF Score resource

{
  "resourceType": "MeasureReport",
  "id": "[uuid]",

  "meta": {
    "profile": [
      "https://zusapi.com/fhir/StructureDefinition/risk/individual-raf-score"
    ],
    "tag": [
      {
        "system": "https://zusapi.com/lens/owner",
        "code": "builder/[uuid]"
      }
    ]
  },

  "status": "complete",
  "type": "individual",
  "measure": "http://zusapi.com/quality/measure/risk/CMSv28",

  "subject": {
    "reference": "Patient/[uuid]"
  },
  "period": {
    "start": "2026-01-01",
    "end": "2026-12-31"
  },
  "date": "2026-02-12",

  "extension": [
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/gap-raf-score-model",
      "valueString": "CNA"
    }
  ],

  "group": [
    {
      "id": "potential-raf-score",
      "measureScore": {
        "value": 1.245
      }
    },
    {
      "id": "expected-raf-score",
      "measureScore": {
        "value": 0.892
      }
    },
    {
      "id": "actual-raf-score",
      "measureScore": {
        "value": 0.654
      }
    }
  ]
}

Payer Risk Gap MeasureReport

A Payer Risk Gap is payer-reported information about a risk gap. We use it as evidence for risk adjustment and for building Risk Gap MeasureReport resources

Core fields

Field	Description
`measure`	`http://zusapi.com/quality/measure/risk/CMSv28`
`subject`	Reference to the patient (e.g., `Patient/{id}`).
`period`	Reporting period window (e.g., `2025-01-01` → `2025-12-31`).
`status`	Always `"complete"`.
`type`	Always `"individual"`.
`meta.profile[]`	Always contains `https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap`.

Within group[0] (the Payer Risk Gap group):

Field	Description
`group[0].id`	`payer-risk-gap`
`group[0].code.coding[]`	An array of HCC and ICD-10-CM codes attributable to the payer risk gap. You can expect: Exactly one HCC v28 code (system: `http://terminology.hl7.org/CodeSystem/cmshcc`, version `V28`). Exactly one ICD-10-CM code (system: `http://hl7.org/fhir/sid/icd-10-cm`).

Field

Description

group[0].id

payer-risk-gap

group[0].code.coding[]

An array of HCC and ICD-10-CM codes attributable to the payer risk gap. You can expect:

Exactly one HCC v28 code
(system: http://terminology.hl7.org/CodeSystem/cmshcc, version V28).
Exactly one ICD-10-CM code (system: http://hl7.org/fhir/sid/icd-10-cm).

Payer Risk Gap extensions

Payer Risk Gaps use extensions to describe originally provided payer data.

Gap Source

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/gap-source`
Type	string
Values	`payer-risk-gap-csv-file` for Payer Risk Gaps created via CSV Import Files. This is currently the only source for Payer Risk Gap MeasureReports

Item

Value

Extension

https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/gap-source

Type

string

Values

payer-risk-gap-csv-file for Payer Risk Gaps created via CSV Import Files.

This is currently the only source for Payer Risk Gap MeasureReports

Payer

Customer specific value used for tracking which Payer this Payer Risk Gap is associated to.

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/payer`
Type	string
Values	The value of the `PAYER` column in the original row in the Payer Risk Gap CSV file

Reporting Period

The year most closely associated with this Payer Gap.

Depending on your company policy and relationship with your payer you may need to calculate this value from Calendar Year and/or Payment Year.

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/reporting-period`
Type	string
Values	The value of the `REPORTING_PERIOD` column in the original row in the Payer Risk Gap CSV file

Payer Risk Gap Status

Whether the payer claimed that the risk gap was open or closed.

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/status`
Type	string
Values	`open` or `closed` The value of the `GAP_STATUS` column in the original row in the Payer Risk Gap CSV file

Item

Value

Extension

https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/status

Type

string

Values

open or closed

The value of the GAP_STATUS column in the original row in the Payer Risk Gap CSV file

Payer Risk Gap Recapture Flag

Whether the payer determined this risk gap to have already occurred in the immediately previous reporting period.

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/recapture-flag`
Type	string
Values	`1` or `0` The value of the `RECAPTURE_FLAG` column in the original row in the Payer Risk Gap CSV file

Item

Value

Extension

https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/recapture-flag

Type

string

Values

1 or 0

The value of the RECAPTURE_FLAG column in the original row in the Payer Risk Gap CSV file

Reason

Human readable string describing the evidence behind the payer gap being "open" or "closed" and "recaptured" or "not recaptured".

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/payer`
Type	string
Values	The value of the `REASON` column in the original row in the Payer Risk Gap CSV file

Last Claim Date

The date that the ICD-10 code for this patient last appeared on a claim (or closest approximation).

Item	Value
Extension	`https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/last-claim-date`
Type	string
Values	The value of the `LAST_CLAIM_DATE` column in the original row in the Payer Risk Gap CSV file

Example Payer Risk Gap resource

{
  "extension": [
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/gap-source",
      "valueString": "payer-risk-gap-csv-file"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/recapture-flag",
      "valueString": "1"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/status",
      "valueString": "open"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/last-claim-date",
      "valueString": "2025-08-10"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/reporting-period",
      "valueString": "2026"
    },
    {
      "url": "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap/payer",
      "valueString": "ACME_INSURANCE_MA"
    },
    {
      "url": "https://zusapi.com/fhir/identifier/universal-id",
      "valueString": "[uuid]"
    }
  ],
  "group": [
    {
      "code": {
        "coding": [
          {
            "code": "J44.9",
            "system": "http://hl7.org/fhir/sid/icd-10-cm"
          },
          {
            "code": "280",
            "system": "http://terminology.hl7.org/CodeSystem/cmshcc",
            "version": "V28"
          }
        ]
      },
      "id": "payer-risk-gap"
    }
  ],
  "id": "[uuid]",
  "measure": "http://zusapi.com/quality/measure/risk/CMSv28",
  "meta": {
    "extension": [
      {
        "url": "https://zusapi.com/stream",
        "valueString": "third-party"
      },
      {
        "url": "https://zusapi.com/created-at",
        "valueInstant": "2026-02-25T15:52:30.59+00:00"
      }
    ],
    "lastUpdated": "2026-02-25T15:52:30.571+00:00",
    "profile": [
      "https://zusapi.com/fhir/StructureDefinition/risk/individual-payer-risk-gap"
    ],
    "tag": [
      {
        "code": "builder/[uuid]",
        "system": "https://zusapi.com/accesscontrol/owner"
      }
    ],
    "versionId": "1"
  },
  "period": {
    "end": "2026-12-31",
    "start": "2026-01-01"
  },
  "resourceType": "MeasureReport",
  "status": "complete",
  "subject": {
    "reference": "Patient/[uuid]",
    "type": "Patient"
  },
  "type": "individual"
}

MeasureReport Profiles

Risk Gap MeasureReport

Core fields

Risk gap extensions

Gap type

Confidence level

Status update history

Hierarchy relationships (superseding/superseded)

Related clinical objects

ICD-10 codes

Evidence references (evaluatedResource)

Example Risk Gap resource

RAF Score MeasureReport

Core fields

RAF Score extensions

Gap RAF Score Model

Example RAF Score resource

Payer Risk Gap MeasureReport

Core fields

Payer Risk Gap extensions

Gap Source

Payer

Reporting Period

Payer Risk Gap Status

Payer Risk Gap Recapture Flag

Reason

Last Claim Date

Example Payer Risk Gap resource

Evidence references (`evaluatedResource`)