EDI Converter CLI User Guide

Running the Converter

To run the converter, provide a path to an EDI file and an output directory (folder) or a file name:

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

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 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:

Line Columns

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:

Repeating claim columns

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

Error Handling

If the converter cannot parse an EDI segment, it will produce a parsing warning. Warnings are logged and can optionally be added to the converter’s output (JSON or CSV) as WARNING objects. This behavior is controlled by the --out-parsing-warnings command-line option.

For more details on the format of warning messages, 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.

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.