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

Zus provides customers with the ability to upload CSV files to bulk upload risk-related claim diagnoses, which will appear as Risk Diagnoses ExplanationOfBenefit resources within the Risk Gaps product.

Each row of a Risk Diagnoses CSV is one encounter whose risk-adjustment eligibility has already been determined by the source (for example, a CMS MAO-004 report). Risk-eligible encounters feed recapture and net-new Risk Gap calculation, while non-eligible encounters feed suspecting.

It's important to enroll your patients before uploading Risk Diagnoses information for them. See our documentation on Enrolling your Patients for more info.

Risk Diagnoses CSV Upload Process

CSV Imports are handled through SFTP. Reach out to your Zus support representative to set up a secure SFTP connection to the Zus system.

Once an SFTP upload folder is properly mounted, uploading a properly formatted Risk Diagnoses CSV File in that folder will create corresponding Risk Diagnoses ExplanationOfBenefit FHIR Resources.

Files may be uploaded and processed in any order. The latest state of each encounter is resolved by the SOURCE_UPDATED_AT column, not by upload order - see Encounter Restatements and Deduplication.

Required File Naming

risk-diagnoses_<schemaVersion>_<producedAt>[_<producerRef>].csv

• <schemaVersion> - the version of this format the file conforms to; currently v1.
• <producedAt> - the UTC time the file was generated, in compact ISO 8601 format (YYYYMMDDTHHMMSSZ). This is for human/operational ordering only - the SOURCE_UPDATED_AT column is the correctness signal.
• <producerRef> - an optional free-form token for your own batch or run identifier.

Example: risk-diagnoses_v1_20260201T000000Z_mao004-jan.csv

Risk Diagnoses CSV File Format

Provide Final-State Data Only

Every row is one encounter whose risk-adjustment eligibility has already been determined by the source. The file carries no add/delete nor void/replace flags; whoever produces the file must resolve each encounter to its final state first. For MAO-004 sources, this means replaying each encounter's void/replace correction chain per the CMS reporting rules (see the CMS MAO-004 User Guide) before producing the file.

The file should not be filtered to eligible encounters only: include every final-state risk-related encounter, flagged eligible or not via the RISK_ELIGIBLE column.

Because the grain is one row per encounter (with all of the encounter's diagnosis codes in a single column), an encounter's diagnoses can never be split across rows or files. Include each encounter at most once per file. To restate / edit an encounter, submit it again in a later file with the same ENCOUNTER_IDENTIFIER and a newer SOURCE_UPDATED_AT.

File Structure

• Encoding: UTF-8, no BOM.
• Delimiter: comma. Quoting per RFC 4180: fields containing a comma, double quote, or line break must be enclosed in double quotes; embedded double quotes are doubled ("").
• Diagnosis list sub-delimiter: semicolon (;) inside the ICD_10_CM_CODES field, e.g. E11319;I509. Semicolons never appear in an ICD-10-CM code, so the list requires no quoting.
• Line endings: LF or CRLF, both accepted.
• Header row: required, with the exact column names below (uppercase). Columns are matched by header name, not by position. A header containing an unrecognized column name rejects the whole file.
• Dates: YYYY-MM-DD, strictly.

Columns

Every column is required. Empty or whitespace-only values are treated as absent, and an absent value invalidates the row.

Sample File

PATIENT_IDENTIFIER_SYSTEM,PATIENT_IDENTIFIER_VALUE,ENCOUNTER_IDENTIFIER,ICD_10_CM_CODES,RISK_ELIGIBLE,SERVICE_START_DATE,SERVICE_END_DATE,SERVICE_TYPE,PAYER,PROVIDER,SOURCE_UPDATED_AT
https://fhir.athena.io/sid/ah-patient,a-12345.E-98765,9999999999999,E11319;I509,true,2026-01-02,2026-01-02,P,MEDICARE,Acme Medical Group,2026-02-01T00:00:00Z
http://hl7.org/fhir/sid/us-mbi,1EG4TE5MK72,8888888888888,F0390;J189,false,2026-03-14,2026-03-15,I,MEDICARE,Acme Regional Hospital,2026-04-01T00:00:00Z

Row 1 is a risk-eligible professional encounter with two diagnoses. Row 2 matches the patient by MBI and carries an inpatient encounter that is not risk-eligible.

Encounter Restatements and Deduplication

During CSV import, ENCOUNTER_IDENTIFIER is the identity of each encounter: one Risk Diagnoses ExplanationOfBenefit exists per encounter, and resubmitting an encounter - in a later file or in the same file re-uploaded - updates the existing resource in place rather than creating a new one.

Restatements follow these rules:

• Resubmission fully replaces the encounter's record - its diagnosis set, eligibility, service dates, and all other fields. For example, re-uploading encounter 9999999999999 with only E11319 (and a newer SOURCE_UPDATED_AT) leaves the encounter with a single diagnosis - I50.9 is removed. To retract a diagnosis, resubmit the encounter without it. There is no explicit delete mechanism.
• SOURCE_UPDATED_AT decides which version wins. Zus keeps the newest SOURCE_UPDATED_AT value it has seen per encounter and applies an incoming restatement only if its value is newer. An equal value is idempotent (safe to re-upload the same file), and an older value is rejected as a stale restatement (skipped and logged, never applied).
• Upload order doesn't matter. Because "latest" is a property of SOURCE_UPDATED_AT rather than of arrival order, out-of-order, delayed, or retried uploads cannot regress an encounter to older data.

Patient Matching at Import Time

Before creating or updating a Risk Diagnoses ExplanationOfBenefit in our CSV pipeline, we require that a Patient record exists in the current builder that matches the PATIENT_IDENTIFIER_SYSTEM and PATIENT_IDENTIFIER_VALUE.

For example, if you have uploaded a CSV with a row that has the values

• https://fhir.athena.io/sid/ah-patient for PATIENT_IDENTIFIER_SYSTEM
• a-12345.E-98765 for PATIENT_IDENTIFIER_VALUE

Then a Patient FHIR record is expected to exist in your builder with a similar Identifier:

{
  "id": "[uuid]",
  "identifier": [{
     "system": "https://fhir.athena.io/sid/ah-patient",
     "value": "a-12345.E-98765"
  },
  ... other identifiers
  ],
  ... additional Patient Data
}

If there is no Patient in your builder with that identifier, then no Risk Diagnoses ExplanationOfBenefit will be created for that row.

Matching on MBI: if your files identify patients by Medicare Beneficiary Identifier (common for MAO-004 sources), your builder's Patient records must already carry MBI identifiers under the system http://hl7.org/fhir/sid/us-mbi. This is an onboarding requirement - make sure MBIs are included when enrolling your patients.

Please see our docs about Enrolling your Patients for more information.

FHIR Canonical URLs

Imported rows are stored as ExplanationOfBenefit resources using the following canonical URLs:

See Risk FHIR Models for the full resource shape and a worked example.