EDI-to-CSV Conversion Guide

Overview

You can convert X12 EDI files to CSV or Excel with the EDI Converter command-line interface (CLI), API server, or Java library. These tools use the same schema-driven conversion engine and produce the same layout when given the same options.

CSV and Excel conversion supports 835, 837P, 837I, 837D, and 834 transactions. See the converted-file examples for sample output.

The csv_conversion.yaml configuration file controls the output layout. It defines:

• Which fields to include or exclude
• How many columns to create for repeating lists
• Which lists to write as rows
• Whether to create one output or multiple outputs
• Which parent fields to repeat in child rows
• Output file or worksheet suffixes

You can review or download the default csv_conversion.yaml file.

The file contains named conversion schemas for the supported transaction types. For example, this block begins the default schema for 835 transactions:

- transactionTypes: [ "835" ]
  name: claim-line-separate-files
  aliases:
    - default
    - two-files

A schema name must be unique for each transaction type, but the same name can be used for different transaction types. Aliases provide additional names for selecting a schema.

You can customize a built-in schema or add a new one. Select a schema with the API’s schemaName parameter or the CLI’s --csv-schema-name option. If you do not select one, the CLI uses the default alias. The API uses lines-with-header-repeat-first-row for 835 and 837 transactions. For 834 transactions, both defaults resolve to member-coverages-single-file.

All CSV-specific CLI options also apply to Excel output (-m excel). For Excel output, each CSV file described below becomes a worksheet.

Converting Repeating Lists to Columns

EDI files contain repeating child structures, commonly called loops. For example, one claim can contain several service lines and diagnosis codes.

By default, a child list is flattened into three groups of columns. A diagnosis list might therefore produce Diag1Code, Diag2Code, and Diag3Code. Set numberOfColumnRepeats on a list schema to change that limit. The following custom 837P schema inherits the default layout and expands the diagnosis list to five groups of columns:

- transactionTypes: [ "837P" ]
  name: five-diagnoses
  baseName: default
  listSchemas:
    - names: [ Diags ]
      numberOfColumnRepeats: 5

Use baseName to inherit a built-in schema, give the custom schema a unique name, and then define only the settings you want to change.

The converter always creates the configured number of columns, even when the input contains fewer list items. For example, two diagnosis codes in a five-column layout produce the values J0300,Z1159,,, under Diag1Code,Diag2Code,Diag3Code,Diag4Code,Diag5Code.

This approach produces a fixed CSV or Excel layout: the number and order of columns do not depend on the input file. If a list contains more items than the configured limit, only the configured number can be represented as repeated columns. To preserve every item, configure the list as rows instead.

Converting Repeating Lists to Rows or Files

Set a list’s strategy to ROWS to write one row for each item. When writing files, the converter can send different lists to separate CSV files. When writing Excel, it sends those lists to separate worksheets.

For example, the default 837 schema creates one claim-level output and one service-line-level output. Each line row includes the converter-generated claim Id, which you can use to correlate the line with its parent claim.

The number and names of the outputs are defined in csv_conversion.yaml. The main header-level list is named Main. A list schema can also define a suffix for the corresponding file or worksheet:

listSchemas:
  # Schema for the main header-level list, such as claims or payments
  - names: [ Main ]
    # Add these parent fields to the first child row
    repeatFields: [ Id, PatientControlNumber ]
    # Repeat all fields selected by repeatFields on every child row
    repeatEachRow: [ "*" ]
    # Override the default suffix for the main output
    fileSuffix: Claims

You can also combine parent and child data in one output. Set output: false on Main to suppress the separate header-level output, then use repeatFields and repeatEachRow to control which parent values appear on child rows.

In this example, all claim-level fields appear on the first service-line row. Only Id, PatientControlNumber, and PayerControlNumber appear on subsequent rows:

listSchemas:
  - names: [ Main ]
    output: false
    repeatFields: [ "*" ]
    repeatEachRow: [ Id, PatientControlNumber, PayerControlNumber ]

To repeat every claim-level field on every service-line row, use repeatEachRow: [ "*" ].

Including or Excluding Columns

The built-in default schemas create columns for most available EDI data elements, except fields excluded by the configuration. Because many EDI elements are optional, this can produce sparsely populated columns.

Use glob patterns under excludedFields to remove matching fields. For example, this configuration excludes service-provider fields from an 835 output:

excludedFields:
  - "ServiceProvider*"

Alternatively, use includedFields to specify only the fields you need:

includedFields:
  - Id
  - FileName
  - PatientControlNumber
  - ClaimStatus
  - ChargeAmount
  - PaymentAmount
  - PatientResponsibilityAmount
  - DrgCode
  - PaymentDate
  - CheckOrEftTraceNumber
  - TotalAdjAmount

Field names and glob patterns are matched against the converter’s CSV field names. Consult the CSV data dictionaries for available fields.

Customizing Schemas for the CLI

The CLI includes a default csv_conversion.yaml file. To override it, copy the file to ~/.ediconvert/csv_conversion.yaml on Linux or macOS, or C:\Users\<username>\.ediconvert\csv_conversion.yaml on Windows, and then edit the copy.

You can also select another file with --csv-config (also available as --csv-schema-file) or set the CSV_SCHEMA_FILE environment variable to the file’s path.

Customizing Schemas for the API Server

Download the latest schema file, modify it, and save it in the Docker volume’s etc/csv directory.

To store the file elsewhere, create a bind mount whose destination is under the container’s /app directory, then set the CSV_SCHEMA_FILE environment variable to that destination path.

Select a schema for a conversion request with the schemaName parameter described in the EDI-to-CSV API reference.

Built-in Conversion Schemas

Separate Header and Line Outputs

The claim-line-separate-files schema writes header-level and service-line-level data to separate outputs. It is the CLI default for 835 and 837 transactions and is intended for file or Excel output; the API returns a single CSV response instead.

For 837 transactions, the schema creates a claim-level output and a service-line-level output. The claim Id and PatientControlNumber repeat in the line-level output.

For 835 transactions, it creates payment-level and service-line-level outputs, plus outputs for provider-level adjustments and transaction-level data. The payment Id, PatientControlNumber, and PayerControlNumber repeat in the line-level output.

The line, provider-adjustment, and transaction outputs use the suffixes -Lines, -ProviderAdjustments, and -Transactions, respectively. Use fileSuffix in csv_conversion.yaml to change a suffix.

Output examples:

• 835 payment-level file
• 835 line-level file
• 835 provider-level adjustments file
• 835 transaction-level file
• 837 claim-level file
• 837 line-level file

Single Output

The lines-with-header-repeat-first-row schema creates one output containing header-level and service-line-level fields. All claim or payment fields appear on the first service-line row. Subsequent rows contain only Id, PatientControlNumber, and, for 835 transactions, PayerControlNumber from the parent record.

This schema is the default for the API’s EDI-to-CSV endpoint for 835 and 837 transactions. In the CLI, select it with --single-csv, --csv-schema-name=single-file, or --csv-schema-name=lines-with-header-repeat-first-row.

Output examples:

• 835 file
• 837 file

For more examples, open an EDI example on this site and select Export > All Fields; Claim on the First Line.

The lines-with-header-repeat-each-row variation repeats all header-level fields on every service-line row. Select it with --csv-schema-name=lines-with-header-repeat-each-row in the CLI or schemaName=lines-with-header-repeat-each-row in the API.

Output examples:

• 835 file with payment fields repeated
• 837 file with claim fields repeated

For 834 transactions, member-coverages-single-file is the default schema for both the CLI and API. It creates one row per health coverage and repeats the member-level fields on every row.

• 834 file

Key Fields

The key-fields schema creates one output containing selected fields for 835, 837P, or 837I transactions. Select it with --csv-schema-name=key-fields in the CLI or schemaName=key-fields in the API.

To see an example, open an EDI example on this site and select Export > Key Fields.

835

Payment-level fields:

• Id
• FileName
• PatientControlNumber
• ClaimStatus
• ChargeAmount
• PaymentAmount
• PatientResponsibilityAmount
• DrgCode
• PaymentDate
• CheckOrEftTraceNumber
• TotalAdjAmount
• Adj*ReasonCode
• Adj*Amount
• PayerIdentifier
• PayerName
• CoverageAmount
• PatientIdentifier
• PatientLastName
• PatientFirstName
• ServiceDateFrom
• ServiceDateTo

Line-level fields:

• LineControlNumber
• LineProcedureCode
• LineRevenueCode
• LineChargeAmount
• LinePaidAmount
• LineUnitCount
• LineServiceDateFrom
• LineServiceDateTo
• LineTotalAdjAmount
• LineAdj*ReasonCode
• LineAdj*Amount
• LineAllowedAmount
• LineRemarkCode*

837P

Claim-level fields:

• Id
• FileName
• PatientControlNumber
• ChargeAmount
• FacilityCode
• FrequencyTypeCode
• TransactionCreationDateTime
• ServiceDateFrom
• ServiceDateTo
• SubscriberIdentifier
• SubscriberLastName
• SubscriberFirstName
• SubscriberPayerIdentifier
• SubscriberPayerName
• PatientPaidAmount
• OtherSubscriberPayerPaidAmount
• Diag*

Line-level fields:

• LineControlNumber
• LineProcedureCode
• LineProcedureModifier*
• LineChargeAmount
• LineUnitCount
• LineServiceDateFrom
• LineServiceDateTo

837I

Claim-level fields:

• Id
• FileName
• PatientControlNumber
• ChargeAmount
• FacilityCode
• FrequencyTypeCode
• TransactionCreationDateTime
• StatementDateFrom
• StatementDateTo
• AdmissionDateAndHour
• SubscriberIdentifier
• SubscriberLastName
• SubscriberFirstName
• SubscriberPayerIdentifier
• SubscriberPayerName
• PriorAuthorizationNumber
• PayerClaimControlNum
• DrgCode
• PrincipalDiag
• AdmittingDiag
• OtherDiag*
• PrincipalProcedure
• OtherProcedure*

Line-level fields:

• LineControlNumber
• LineRevenueCode
• LineProcedureCode
• LineChargeAmount
• LineUnitCount
• LineServiceDateFrom
• LineServiceDateTo

Conversion Schema Reference

The table lists every canonical schema in the default csv_conversion.yaml file. Names shown in parentheses are aliases.