Command-Line X12 EDI File Converter
Overview
Our command-line EDI conversion tool converts X12 EDI files to JSON or CSV/Excel. Conversion to CSV/Excel is supported for 837 (healthcare claim) and 835 (ERA) EDI files.
The output is easy to understand and requires no EDI knowledge.
To familiarize yourself with the output formats, review our intro to the JSON format and the intro to the CSV format. To see examples, navigate to any 837 or 835 examples on the site, click “Export,” select “JSON” or “CSV (All Fields).”
You can also use our free EDI Viewer to convert small files (up to three claims). Upload your file and export your data as CSV or JSON from the UI.
The CLI tool produces the exact same output as our API server, except for code descriptions.
See our data dictionary for the details about CSV columns and JSON fields. To view formal schemas of JSON output, navigate to our API Reference Guide and expand the “200” response.
The converter can efficiently handle large X12 EDI files with special support for 837/835 files. See this section for more details.
The conversion is performed locally on your machine; your data never leaves your network.
The converter’s only dependency is Java. Windows, Linux, and macOS are all supported.
Current release: 2.12.1.
Installation Steps
- Download and install Java from the Oracle website. You can also use OpenJDK. Java 17 or higher is required. We recommend installing the latest long-term support (LTS) release of Java. You can also install Java using sdkman or a package manager on Linux or macOS. Once you install Java verify the Java’s version by running
java -version
command from the command line window/terminal. - If Java is already installed on your system, verify that you have the correct version by running
java -version
command; it must be version 17 or higher. - If you have
JAVA_HOME
environment variable defined, make sure that it points to Java 17 or higher. Alternatively, you can delete theJAVA_HOME
variable. To view environment variables on Windows, go to “Settings/Advanced system settings”, “Advanced” tab, click “Environment Variables…”. - Download the zip file with the converter from this link.
- Unzip the converter’s zip file; the root folder/directory of the installation will be
ediconvert
.
Many Windows systems have Java 8 pre-installed. The converter requires Java 17 or later; it will fail when Java 8 is used. Follow the steps above to ensure that you have the correct version of Java.
You need a license key to run the converter. Request your trial license key here.
Once you receive your edi-license.txt
license file, save it into the installation folder, i.e., into ediconvert
. Alternatively, you can save the license file in a different location; then, you need to create the EDI_LICENSE_FILE
environment variable that points to it. You can also copy the license key to the EDI_LICENSE_KEY
environment variable.
You can run the converter by providing the full path, e.g., ediconvert\bin\ediconvert
on Windows or ediconvert/bin/ediconvert
on Linux/macOS.
We recommend adding the bin
directory of the converter to the “Path” so you can run it from anywhere. On Windows, go to “Settings/Advanced system settings”, “Advanced” tab, click “Environment Variables…”, click a variable called “Path” and click “Edit…”. Create a new entry with the absolute path to the bin
folder. On Linux/macOS, append it to the PATH
variable in your shell configuration file, e.g., for .bashrc
: export PATH=$PATH:ediconvert/bin
.
All examples in this document assume that you’ve added the converter to the path, so we omit the full path to bin/ediconvert
.
Run ediconvert -V
to view the license and version information.
Running the Converter
To run the converter, provide a path to an EDI file and an output directory (folder). The output directory must exist. Otherwise, the converter assumes that the value of the -o
option is the 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.
All examples on this page use linux-style forward slashes; use backslash on Windows.
You can use wildcards to convert multiple files in one go (make sure to enclose the first parameter into quotes):
ediconvert "edi/837/*.edi" -o converted-files
Due to automatic wildcard expansion by command-line shells and the Java platform, always enclose a parameter with wildcards into double quotes on Linux/macOS or single quotes on Windows.
If you provide an existing directory/folder as the output, the converter will convert each file from the input into this directory. The converter will create output file names based on the input file names with the appropriate file extension depending on the output format.
If the output is not an existing directory, the converter will assume the file as the output, and it will convert all input files into one file:
# Convert all files from 835 folder into converted-files/combined-835.csv file
ediconvert "edi/835/*" -o converted-files/combined-835 -m csv
Convertion to CSV
By default, the converter creates two output files in CSV format, 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 containing several pre-defined 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 your custom conversion schemas or select one of the built-in schemas by providing --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
Please follow this document for more details.
Convertion 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
However, instead of generating separate files for claim and line level data, the converter creates a single Excel file with different sheets.
The converter sets column types based on the type of the EDI field. For example, the “ChargeAmount” column is defined as numeric in the generated Excel file. This saves you time—instead of manually importing CSV and setting column types, you can generate the Excel file that can be immediately used for analysis.
Note that Excel files have limitations in terms of 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”) format with line-separated JSON objects. This provides an alternative to well-formed JSON with enclosing arrays, which are inefficient with large files.
Use the -m jsonl
option to produce NDJSON files instead of well-formed JSON.
By default, the converter reads an entire EDI transaction, or a batch of transactions, as defined by the --chunk-size
option. This may not work if a single transaction contains many claims or payments or other items.
The --spit-tran
option forces the converter to read a batch of claims (CLM
segment for 837) or payments (CLP
segment for 835) instead of a batch of transactions. We recommend always using this option with 837/835 transactions. This option is set by default when converting to CSV/Excel but must be set explicitly when converting to JSON or NDJSON.
Example:
ediconvert edi/837/edi_file_large_transaction.edi -m jsonl --split-tran
Command-line Options
Usage: ediconvert [-hqrV] [--format-json] [--out-parsing-warnings]
[--single-csv] [--split-tran] [--chunk-size=<chunkSize>]
[--csv-config=<csvConversionSchemaFileName>]
[--csv-schema-name=<csvConversionSchemaName>]
[-m=<outputFormat>] [--max-warnings=<maxWarnings>]
[-o=<outFile>] [-p=<filePatterns>]
[--tran-type=<transactionTypeFilter>] EDI File or Directory
Converts X12 EDI files to JSON or CSV
EDI File or Directory
X12 EDI file or a directory (folder) containing X12 EDI
files. It can contain '*' and '?' wildcards to match
multiple files. Enclose in single quotes on Windows
or '"' on Linux if using wildcards.
-p, --patterns=<filePatterns>
File name patterns to match in the directory, e.g., '*.
edi'. You can specify multiple comma-delimited
patterns, e.g., '*837*.edi, *837*.txt'. Defaults to
'*' (all files) if 'EDI File or Directory' is a
directory. Enclose in single quotes on Windows or '"'
on Linux.
-r, --recurse Recursively search for matching files in all
subdirectories
-o, --out=<outFile> Output file or existing directory where to save output
files. The file will be created if it doesn't exist.
In the case of a directory, the output file name will
be the name of the EDI file + the extension,
depending on the output format. If omitted, the
converted will output to the console (standard out),
which can be used for piping/streaming the output.
-m, --mode=<outputFormat>
Output format. Acceptable values: CSV, EXCEL, JSON,
JSONL. Defaults to 'json'.
--format-json Format JSON with indentation and new lines. Ignored for
CSV and JSONL.
--out-parsing-warnings
Write EDI parsing warnings to the output file as
'warning' objects. If not set, parsing warnings are
written to the log and standard output. See https:
//datainsight.
health/docs/ediconvert-api/user-guide/#error-handling
for more details.
--max-warnings=<maxWarnings>
Maximum number of parsing warnings per file before
aborting. Defaults to 50. Set to -1 to suppress
raising an error when this number is reached.
--chunk-size=<chunkSize>
The number of EDI transactions or claims/payments for
837/835 that will be parsed and converted at once.
This option determines the memory footprint and can
be used for fine-tuning. Defaults to 200 when
--split-tran is set; otherwise, it defaults to 5
transactions. Higher value improves performance but
consumes more memory.
--split-tran Split large transactions. By default, the converter
parses an entire transaction at once. For large
transactions, this can be slow. When this option is
set, the converter will break up transactions into
individual items, such as a claim or a payment.
Currently supported for 835 and 837 transactions.
This option is set by default for CSV output but not
for JSON.
-q, --quiet, --suppress-progress
Suppress logging file names and conversion progress to
the console; use this option when converting to
standard out
-h, --help Show this help message and exit.
-V, --version Print version information and exit.
Options for CSV conversion:
--csv-schema-name=<csvConversionSchemaName>
Name of the 'schema' (configuration) in the CSV config
file, such as 'key-fields'. The schema determines the
layout of the CSV file. See https://datainsight.
health/docs/csv/schemas for the list of schemas.
--csv-config, --csv-schema-file=<csvConversionSchemaFileName>
Name of the file containing CSV conversion schemas in
the 'conf' directory. Defaults to
'conf/csv_conversion.yaml'.
--tran-type=<transactionTypeFilter>
Convert only the files that contain transactions of
this type. All other files will be ignored.
Acceptable values: 835, 837P, 837I, 837D.
--single-csv Convert all EDI files into a single CSV file containing
the claim-level and the service line-level fields. If
not provided, the converter will convert claim-level
and line-level data into separate files. Same as
providing
'--csv-schema-name=lines-with-header-repeat-first-row'
Converting to the Console (Standard Output Stream)
You can run the converter in the JSON Lines or in the 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 -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, however, obtain descriptions using our free code lookup. You can download all the descriptions for a specific code set in the CSV format or use the API call to get only the ones that you need.
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_FACILIY
.
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.
License File and License Key Configuration
The default location of the license file is the converter’s installation folder, e.g., ediconvert
.
Alternatively, you can save the license file anywhere and define the environment variable EDI_LICENSE_FILE
with the path to the license file:
For Linux/macOS, add the variable to your profile:
export EDI_LICENSE_FILE=<absolute path to the file>
For Windows, create a new environment variable EDI_LICENSE_FILE
from “Settings/Advanced system settings.”
You can also set your license key using the environment variable EDI_LICENSE_KEY
. Copy the entire content of edi-license.txt
into that variable. In this case, you don’t need to save the license key file anywhere.
Run ediconvert -V
to view the license information and the location of the license file.
Logging
The converter creates logs with information and diagnostic messages in the “logs” directory. These logs are useful when routing the output to standard out.
The converter always logs to the file, even when the --quiet
option was set.
The default location of the logs folder is the directory where the converter is executed. It can be changed by defining the ediconvert_logs_dir
environment variable, e.g.,
export ediconvert_logs_dir=ediconverter_logs