Claim CSV Import

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

Zus provides customers with the ability to upload claims as CSV files in the Zus Claim CSV format, which will appear as Claim FHIR Resources within Zus. It's important to enroll your patients before uploading claims information for them.

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 Zus Claim CSV file in that folder will create corresponding Claim FHIR Resources.

File Naming and Structure

Name every file with the spec version token so Zus knows which version of this contract to validate it against:

{customer-file-name}_raw_claims_v1_<suffix>.csv

For example: acme_raw_claims_v1_20260312.csv. The suffix is conventionally a date (YYYYMMDD) but is not constrained. A file without the _raw_claims_v1_ token is validated against an older layout and will be rejected on every column described on this page, so the token is required.

Encoding: UTF-8.
Header row: required. Columns are matched by name, not by position, so they may appear in any order. Names are case-insensitive and surrounding whitespace is ignored, so CLAIM_IDENTIFIER and claim_identifier are equivalent.
Only the columns listed below are accepted. An unrecognized column, or a missing required column, rejects the whole file.
Validation is all-or-nothing. Any failure on any row (an empty required value, a value that does not match its format, a value over its maximum length, or a claim-consistency violation) rejects the entire file. Nothing is partially imported. Fix the reported rows and upload the file again.
One claim per CLAIM_IDENTIFIER. Rows sharing the same CLAIM_IDENTIFIER form a single Claim, with one line item per row. Columns marked claim-level below must be identical on every row of the claim, and CLAIM_LINE_NUMBER must be unique within the claim.

File Format

Columns are optional unless marked Required. A required column must be present in the header and non-empty on every row. Optional columns may be omitted from the header entirely or left blank on individual rows. Diagnosis codes are provided as a semicolon-delimited list in ICD_10_CM_CODES. Each Claim passes through our deduplication process to either create or update a Claim.

Format legend

string: free text.
URI: an absolute URI, including the scheme (for example https://).
enum: one of a fixed list of values, case-insensitive.
decimal: a number, such as 123.45.
ICD-10 list: semicolon-delimited ICD-10-CM codes, at least one and at most 25.
modifier list: semicolon-delimited procedure modifier codes, at most 6, each at most 4 characters.
bill type: UB-04 type of bill, three digits with or without the leading zero.
date/time: an ISO 8601 date (YYYY-MM-DD) or an RFC 3339 date-time (2025-03-01T08:00:00-05:00).
epoch millis or date/time: either of the above, or epoch milliseconds as a bare integer (1741564800000).

Max length is the maximum number of characters in a value after surrounding whitespace is trimmed. A longer value rejects the file.

Columns

Column	Required	Format	Max length	Description	Example
`PATIENT_IDENTIFIER_VALUE`	Required	string	128	Claim-level. Patient identifier value, resolved against `PATIENT_IDENTIFIER_SYSTEM` to match the patient. If no patient matches, the whole claim is skipped and produces nothing.	`patient-id-1`
`PATIENT_IDENTIFIER_SYSTEM`	Required	URI	256	Claim-level. System URL for `PATIENT_IDENTIFIER_VALUE`. Recognized MBI systems automatically retry the alternate MBI system.	`http://hl7.org/fhir/sid/us-mbi`
`CLAIM_IDENTIFIER_SYSTEM`	Required	URI	256	Claim-level. System URL for `CLAIM_IDENTIFIER` and `ORIGINAL_CLAIM_IDENTIFIER`, identifying whose claim numbering it is — the BA (Business Associate), the CE (Covered Entity), or your own builder-specific system.	BA — `https://sprinterhealth.com/sid/claim/humana`; CE — `https://fhir.munsonhealthcare.org/sid/claim`; Builder — `https://claims.yourdomain.com/sid/claim`
`CLAIM_IDENTIFIER`	Required	string	64	Claim-level. The claim number as assigned by the payer for this version of the claim. Rows sharing this value are grouped into a single claim, with one line item per row.	`CLM-MULTI-001`
`ORIGINAL_CLAIM_IDENTIFIER`	Required	string	128	Claim-level. Stable identity of the claim, used to deduplicate and version it across re-imports; the newest `SOURCE_UPDATED_AT` within it wins. For a claim that has never been adjusted, this is simply its own identifier. When a payer issues a new claim number for an adjustment, keep the original claim's identifier here so the new version replaces the old one. Must be unique within your builder — compose the scope in if your claim numbers repeat.	`H1234:CLM-ORIG-000`
`CLAIM_LINE_NUMBER`	Required	string	16	Line-level. The service line number within the claim, unique among the rows sharing the same `CLAIM_IDENTIFIER`. Each CSV row becomes one line item on the Claim.	`1`
`SOURCE_UPDATED_AT`	Required	epoch millis or date/time	35	Claim-level. When your source system last updated this claim. Accepted as epoch milliseconds, an ISO 8601 date, or an RFC 3339 date-time; every form resolves to the same instant, so `1766966400000` and `2025-12-29` are equivalent. Values outside the years 2000–2100 are rejected. When the same `ORIGINAL_CLAIM_IDENTIFIER` is re-imported, the newest `SOURCE_UPDATED_AT` wins.	`2025-03-01T08:00:00-05:00`
`CLAIM_TYPE`	Required	enum	16	Claim-level. Classifies the claim as an institutional or professional claim. It drives the claim-type coding on the FHIR Claim. Accepted values (case-insensitive): `Institutional` or `Professional`, plus the synonyms `Inpatient`, `Hospice`, `Home Health`, `SNF` (institutional) and `Outpatient` (professional).	`Professional`
`CLAIM_STATUS`	Optional	enum	9	Claim-level. `active` or `cancelled` (case-insensitive). Blank defaults to `active`. `cancelled` marks a reversal — the claim is retracted and produces no line items; send it with the same `ORIGINAL_CLAIM_IDENTIFIER` and a newer `SOURCE_UPDATED_AT`. There is no claim-level denied status: mark payer denials per line with `PAYMENT_DENIAL_CODE`.	`active`
`MEDICARE_CLAIM_TYPE_CODE`	Optional	string	8	The Medicare NCH claim type code, as delivered in Medicare claim files (CCLF `CLM_TYPE_CD`; e.g. `60`/`61` inpatient, `40` outpatient, `71`/`72` professional). May vary by line. Used together with `BILL_TYPE` and `MEDICARE_NON_PAYMENT_REASON` to determine inpatient risk-adjustment eligibility: the claim qualifies when this code is inpatient (`60`/`61`), the bill type's facility digit is a hospital or religious non-medical institution, its classification digit is inpatient, and no Medicare non-payment reason is present.	`60`
`MEDICARE_NON_PAYMENT_REASON`	Optional	string	8	Claim-level. Medicare non-payment reason code, as delivered in Medicare claim files (CCLF `CLM_MDCR_NPMT_RSN_CD`). Any populated value marks the claim as not paid by Medicare, which disqualifies an inpatient claim from risk-adjustment eligibility — leave blank for paid claims.	`A`
`ICD_10_CM_CODES`	Optional	ICD-10 list	256	Semicolon-delimited list of ICD-10-CM diagnosis codes for the claim (up to 25). Repeat the claim's codes on every row. Each code is normalized to dotted form (`E11319` → `E11.319`) and de-duplicated across the claim. The first code is the principal diagnosis.	`I10;E11.319;N18.3`
`PROCEDURE_CODE`	Optional	string	8	Line-level. CPT (numeric), HCPCS (letter-leading) or CDT (dental, `D` + 4 digits) procedure code for the line item. When blank, the line is marked as having an unknown procedure.	`99223`
`MODIFIERS`	Optional	modifier list	32	Line-level. Semicolon-delimited procedure modifier codes for the line item, in order (up to 6, each up to 4 characters). Empty entries are ignored.	`25;59`
`REVENUE_CODE`	Optional	string	4	Line-level. UB-04 revenue center code for the line (institutional claims).	`0450`
`UNITS`	Optional	string	14	Line-level. Service units for the line. What a unit means (days, visits, dose units, 15-minute units) is defined by the line's procedure or revenue code. A non-numeric value is accepted but not recorded.	`2`
`BILLED_AMOUNT`	Optional	decimal	14	Line-level. Billed amount for the line (USD).	`123.45`
`PAID_AMOUNT`	Optional	decimal	14	Line-level. Paid amount for the line (USD).	`100.00`
`PAYMENT_DENIAL_CODE`	Optional	string	8	Line-level. The payer's payment denial code for this line, as delivered. `0` means the line was denied; blank means it was not. For Medicare claims this is the CCLF5 carrier payment denial code (`CLM_CARR_PMT_DNL_CD`), where `0` is a denial and other values are payment dispositions, not denials. A denied line stays on the Claim but never counts as risk-adjustment evidence.	`0`
`BILL_TYPE`	Optional	bill type	4	Claim-level. UB-04 type-of-bill code for institutional claims, as billed, with or without the leading zero (`0111` and `111` are equivalent). The first digit after the leading zero is the facility type and the second is the classification, which drive institutional risk-adjustment eligibility when combined with `MEDICARE_CLAIM_TYPE_CODE` and `MEDICARE_NON_PAYMENT_REASON` for inpatient claims, or a qualifying `PROCEDURE_CODE` for outpatient claims. The frequency digit is ignored. Leave blank for professional claims.	`0111`
`DIAGNOSIS_RELATED_GROUP`	Optional	string	8	Claim-level. MS-DRG assigned to an inpatient claim, recorded against the principal diagnosis. Every row of the claim must carry the same value.	`470`
`DATE_OF_SERVICE_FROM`	Optional	date/time	35	Line-level. Service start date for this line. The claim's billable period starts at the earliest `DATE_OF_SERVICE_FROM` across the claim's rows.	`2025-03-01T08:00:00-05:00`
`DATE_OF_SERVICE_THRU`	Optional	date/time	35	Line-level. Service end date for this line. The claim's billable period ends at the latest `DATE_OF_SERVICE_THRU` across the claim's rows.	`2025-03-05T14:00:00-05:00`

Sample File

A file named acme_raw_claims_v1_20260312.csv containing a two-line inpatient claim and a one-line professional claim whose only line was denied:

PATIENT_IDENTIFIER_VALUE,PATIENT_IDENTIFIER_SYSTEM,CLAIM_IDENTIFIER_SYSTEM,CLAIM_IDENTIFIER,ORIGINAL_CLAIM_IDENTIFIER,CLAIM_LINE_NUMBER,SOURCE_UPDATED_AT,CLAIM_TYPE,CLAIM_STATUS,MEDICARE_CLAIM_TYPE_CODE,MEDICARE_NON_PAYMENT_REASON,ICD_10_CM_CODES,PROCEDURE_CODE,MODIFIERS,REVENUE_CODE,UNITS,BILLED_AMOUNT,PAID_AMOUNT,PAYMENT_DENIAL_CODE,BILL_TYPE,DIAGNOSIS_RELATED_GROUP,DATE_OF_SERVICE_FROM,DATE_OF_SERVICE_THRU
1EG4TE5MK73,http://hl7.org/fhir/sid/us-mbi,https://claims.yourdomain.com/sid/claim,CLM-1001,H1234:CLM-1001,1,2025-03-10T08:00:00-05:00,Institutional,active,60,,I10;E11.319;N18.3,99223,,0120,4,4800.00,4100.00,,0111,470,2025-03-01,2025-03-05
1EG4TE5MK73,http://hl7.org/fhir/sid/us-mbi,https://claims.yourdomain.com/sid/claim,CLM-1001,H1234:CLM-1001,2,2025-03-10T08:00:00-05:00,Institutional,active,60,,I10;E11.319;N18.3,,,0250,2,150.00,120.00,,0111,470,2025-03-02,2025-03-02
1EG4TE5MK73,http://hl7.org/fhir/sid/us-mbi,https://claims.yourdomain.com/sid/claim,CLM-2002,H1234:CLM-2002,1,1741564800000,Professional,,71,,E11.319,99214,25;59,,1,210.00,0.00,0,,,2025-03-12,2025-03-12

Deduplication

During CSV import, we do not create a new Claim for a patient if we have previously received similar data. Claims are deduplicated on ORIGINAL_CLAIM_IDENTIFIER (scoped to the patient), using SOURCE_UPDATED_AT as the version. Re-importing the same ORIGINAL_CLAIM_IDENTIFIER with a newer SOURCE_UPDATED_AT replaces the prior claim — including adjustments that arrive under a new CLAIM_IDENTIFIER; an equal value is idempotent; an older value does not overwrite newer data. All accepted SOURCE_UPDATED_AT forms are compared as the same instant, so you can switch between epoch milliseconds and timestamps without disturbing version ordering. Both columns are therefore required — a claim without them is rejected rather than risk duplicates.

Patient Matching

Before creating or updating a Claim 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.

Recognized MBI systems automatically retry the alternate MBI system (http://hl7.org/fhir/sid/us-mbi ⇄ urn:oid:2.16.840.1.113883.4.927); both identify the same Medicare Beneficiary Identifier. If neither resolves a patient, the claim is skipped and produces nothing.

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-12345" 
  },
  ... other identifiers
  ],
  ... additional Patient Data
}

If there is no Patient in your builder with that identifier, then no FHIR Claim will be created for that row.

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