EDI Converter CLI User Guide

Running the Converter

All examples assume that the converter is installed and available in your PATH as documented here.

To run the converter, provide a path to an EDI file and an output directory (folder) or a file name. You can use backslash on Windows.

mkdir json
ediconvert edi/837/my_837_file.edi -o converted-files/ -m json

All examples in this document follow the Linux path convention with forward slash. You can use forward slash or backslash on Windows.

The -m (--mode) option defines the output format: JSON, line-delimited JSON/NDJSON (jsonl), CSV, or Excel. JSON is the default.

You can use wildcards to convert multiple files in one go:

ediconvert edi/837/*.edi -o ./converted-files/

You can also specify multiple space-delimited file names or directories; each file name or directory can contain wildcards:

ediconvert edi/837/*.edi edi/835/*.edi -o ./converted-files/

If you provide an existing directory as the output, the converter will place each input file in that directory and create an output file for each input file.

You can also add a trailing slash to the output value; in this case, the converter will treat the output as a directory. The converter will create the directory if it doesn’t exist:

ediconvert edi/837/*.edi -o ./converted-files/

The converter generates an output file name from the input file names. It removes the input file extension (e.g., “.edi”) and appends the output format extension (e.g., “.json”, “.csv”, or “.jsonl”).

When converting files from multiple directories, the converter will not re-create the directory structure in the output directory. All files will be placed directly into the output directory. Ensure that all file names are unique across all input directories.

If the output is not a directory, the converter will assume it’s a file, and it will convert all input files into a single file:

# Convert all files from the 835 folder into the converted-files/combined-835.csv file
ediconvert edi/835/* -o converted-files/combined-835 -m csv

To summarize, if you want to convert each input file into a separate output file, provide the location of an existing folder or provide the directory name with a trailing slash.

If you want to convert all input files into a single file, provide the name of the output file.

See the option reference for every command-line argument.

Conversion to JSON

See this page for the overview of the JSON object model.

If you use Python, install our Python SDK that contains all classes for the object model:

pip install ediconvert-sdk

Conversion to CSV

When converting 835/837 files, the converter generates two CSV output files: one for claim-level data and one for line-level data. The line-level file has the “-Lines” suffix.

For example, ediconvert edi/837/my_837_file.edi -o converted-files -m csv creates my_837_file.csv and my_837_file-Lines.csv in the converted-files folder.

The internally generated ID, the patient control number, and the payer control number (for 835) fields are repeated for each line in the line-level file:

You can also ask the converter to produce a single file using the --single-csv option. In this case, the output file will contain both claim and line-level columns. The claim-level data will be listed once, and ID and patient control number fields will be repeated for each line of the same claim:

All CSV columns and their mappings to X12 EDI are documented in our data dictionary.

The CSV output format is governed by a configuration file that contains several predefined configurations (conversion schemas).

The conversion schemas define what columns to include in the CSV file and how many times to repeat columns for repeating groups, such as adjustments or diagnosis codes.

You can create custom conversion schemas or select a built-in schema by providing the --csv-schema-name option.

For example, if you want to repeat all claim-level fields for all lines (as opposed to just the first one), you can use the schema lines-with-header-repeat-each-row:

ediconvert edi/837/my_837_file.edi -o converted-files -m csv --csv-schema-name lines-with-header-repeat-each-row

See this document for details on available schemas and how to create your own.

Conversion to Excel

The converter can generate Excel instead of CSV. The CSV-related command-line options, such as --csv-schema-name and --single-csv, apply to Excel:

ediconvert edi/837/my_837_file.edi -o converted-files -m excel --single-csv

Instead of generating separate files for claim- and line-level data, the converter creates a single Excel file with different sheets; here is an example.

The converter sets column types based on the EDI field type. For example, the “ChargeAmount” column is defined as numeric in the generated Excel file. This saves you time—instead of manually importing CSV files and setting column types, you can generate an Excel file that can be used for analysis immediately.

Note that Excel files have limitations on the number of rows, so converting to Excel is suitable only for relatively small datasets.

Converting Large Files and Large EDI Transactions

For JSON conversion, the converter supports NDJSON (a.k.a. “JSON Lines”), a line-separated JSON format. This provides an alternative to well-formed JSON with enclosing arrays, which can be inefficient for large files.

Use the -m jsonl option to produce NDJSON files instead of well-formed JSON.

The converter automatically splits large 837/835/834 transactions. It does this by reading a batch of claims (CLM segment for 837), payments (CLP segment for 835), or members (INS segment for 834) instead of a batch of transactions.

The batch size is controlled by the --chunk-size option. The default value is 50 claims/payments/members for 837/835/834 transactions or 20 transactions for all other transaction types.

Increasing the chunk size can improve performance, but it can also increase memory usage.

Example:

ediconvert edi/837/edi_file_large_transaction.edi -m jsonl --chunk-size 100

EDI Validation

By default, the converter only checks for serious errors that result in data loss, such as an invalid segment or a conversion error. Warnings are logged and can optionally be added to the converter’s output (JSON or CSV) as WARNING objects or records. This behavior is controlled by the --out-parsing-warnings command-line option.

You can enable full validation of EDI by providing --validate option or by setting the EDI_VALIDATE environment variable to True.

When validation is enabled, the converter will write validation issue JSON objects alongside all other top-level objects. Each validation issue will have the objectType set to VALIDATION.

All validation issues are logged, unless the -q option is provided. You can also suppress logging by setting the EDI_LOG_VALIDATION_ISSUES environment variable to False.

It is often useful to see validation issues next to the original EDI segment. Use the --validate-out-edi option to validate each EDI file and create a corresponding text file with the copy of the EDI content and validation issues’ messages. The issues are marked with !! under each EDI segment that failed validation.

Example output:

CLM*26463774*100***111:B:1*V*A*Y*I~
!!Loop:2300, Element:CLM05-1, Field: facility_type_code | Place of Service 111 is not a valid code
!!Loop:2300, Element:CLM05-1, Field: facility_type_code | Length of '111' is greater than the maximum length 2
!!Loop:2300, Element:CLM06, Field: Claim.providerSignatureIndicator | Value 'V' is not in the allowed values list. Allowed values: [Y, N]
!!Loop:2300, Segment:CLM, Field: Claim.chargeAmount | Claim 26463774: The sum of line charge amounts 99.00 does not match the claim charge amount 100.00
DTP*314*RD8*20051208-20051309~
!!Loop:2300, Segment:DTP, Field: disability_date_to | Invalid date or time value '20051309'
DTP*471*D8*20051301~
!!Loop:2300, Segment:DTP, Field: prescription_date | Invalid date or time value '20051301'

For more details on EDI validation, see this page.

Converting to the Console (Standard Output Stream)

You can run the converter in JSON Lines or CSV mode and pipe its output to another process, e.g.:

ediconvert edi/837/my_edi_file.edi -m jsonl -q | grep '"zipCode":"37232"'

Make sure to use the -q option when converting to the console.

When converting to JSON, you can use the jq command-line tool used to slice, filter, map, and transform JSON data.

To format JSON with color:

ediconvert edi/837/my_edi_file.edi -q | jq .

To print each procedure code and the charge amount for all service lines:

ediconvert edi/837/my_edi_file.edi -q | jq '.[].serviceLines[] | {chargeAmount, procedureCode: .procedure.code}'

Healthcare and X12 EDI Codes

The CLI tool does not provide descriptions for healthcare codes, such as ICD-10 and CPT. Use our API server product if you’re interested in getting descriptions along with the codes.

You can also use our code lookup API to programmatically obtain descriptions for healthcare codes. Request your API key here.

The CLI converter converts some of the EDI codes, such as an “Entity Identifier code”, to mnemonic constants, e.g., the code 77 is translated to SERVICE_FACILITY.

You can always find the code for the constant using the code lookup tool. Enter a name of any constant to see its description and the EDI code it corresponds to, e.g., SERVICE_FACILITY.