Raw Claims CSV Import

Zus provides customers with the ability to upload CSV files as a bulk upload mechanism. The data provided in these files will appear as Claim FHIR Resources within Zus. The patients referenced in any Claim CSV must be enrolled with a valid patient identifier in place at the time of upload.

Raw Claims 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 Raw Claims CSV File in that folder will create corresponding Claim FHIR Resources.

CSV File Format

All uploaded CSVs are expected to include the following columns. Rows sharing the same CLAIM_NUMBER are grouped into a single Claim, with one line item per row; a row with a blank CLAIM_NUMBER becomes its own single-line Claim. Diagnosis codes span the numbered DIAG_1 … DIAG_25 columns and procedure modifiers span MODIFIER_1 … MODIFIER_6; empty trailing slots are ignored. Each Claim passes through our deduplication process to either create or update a Claim.

Columns

Raw Claims Deduplication Process

During CSV import, we do not create a new Claim for a patient if we have previously received similar data. Claims deduplication relies on the following information:

1. The Patient ID associated with the Claim (Determined through Patient Matching).
2. Your Builder ID associated with the file (implicitly provided during file upload).
3. The UNIQUE_CLAIM_ID field: Must be a unique string.
4. The SEQUENCE_VALUE field: Must be a valid integer.

If a previous Claim for a patient was created with these same values, the existing Claim will be updated with the remaining data (e.g. PRIOR_CLAIM_IDENTIFIER). Similarly, a new Claim will be created if we do NOT have an existing Claim with these same values associated with the matched patient.

SEQUENCE_VALUE

We use a numeric SEQUENCE_VALUE as the version. Re-importing the same UNIQUE_CLAIM_ID with a higher SEQUENCE_VALUE replaces the prior claim; an equal value is idempotent; a lower value does not overwrite newer data. UNIQUE_CLAIM_ID and a valid integer SEQUENCE_VALUE are therefore required — a claim without them is rejected rather than risk duplicates.

Patient Matching at Import Time

Before creating or updating a Claim in our CSV pipeline, we require that a Patient record exists in the current builder that matches the PERSON_ID_SYSTEM and PERSON_ID.

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

• https://fhir.athena.io/sid/ah-patient for PERSON_ID_SYSTEM
• a-12345.E-12345 and PERSON_ID

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.