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), 835 (ERA), and 834 EDI files.
The output is easy to understand and requires no EDI knowledge.
To familiarize yourself with the output formats, review our introduction to JSON format and the CSV format.
Output examples:
- 835: CSV, Excel, JSON
- 837P: CSV, Excel, JSON
- 837I: CSV, Excel, JSON
- 837D: JSON
- 277CA: JSON
- 834: CSV, Excel, JSON
For more examples, go to our list of sample EDI files, select any sample, and click Export.
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 JSON schema and CSV data dictionary documentation for the details about CSV columns and JSON fields.
The converter efficiently handles large X12 EDI files, with special support for 837/835/834 files. See this section for 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.14.8. What’s new: Support for PLB (provider-level adjustments) in 835, CRC and CR segments, MIA/MOA segments, 834 JSON and CSV, 277CA JSON.
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 (Java 25). You can also install Java using sdkman or a package manager on Linux or macOS. Once you install Java, verify the version by running
java -versionin a terminal. - If Java is already installed on your system, verify that you have the correct version by running
java -version; it must be version 17 or higher. - If you have
JAVA_HOMEenvironment variable defined, make sure that it points to Java 17 or higher. Alternatively, you can delete theJAVA_HOMEvariable. 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. - (Optional) Install autocompletion (bash and zsh). Download the completion script, save it to a location of your choice, and source it from your shell configuration file (e.g.,
~/.bashrcor~/.zshrc). If you havebash_completioninstalled, place it in the appropriate location, such as/etc/bash_completion.d. You can find more details here.
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 set the EDI_LICENSE_FILE environment variable to point 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”, open the “Advanced” tab, click “Environment Variables…”, select “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) 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.
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 50 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.
Command-line Options
Usage: ediconvert [-hqrV] [--format-json] [--out-parsing-warnings]
[--out-segments] [--single-csv] [--[no-]split-tran]
[--chunk-size=<chunkSize>]
[--csv-config=<csvConversionSchemaFileName>]
[--csv-schema-name=<csvConversionSchemaName>]
[-m=<outputFormat>] [--max-warnings=<maxWarnings>]
[-o=outputFileOrDirectory] [-p=<filePatterns>]
[--progress-chunk-size=<loggingChunkSize>]
[--tran-type=<transactionTypeFilter>] ediFilesOrDirectories...
Converts X12 EDI files to JSON or CSV
ediFilesOrDirectories...
X12 EDI files or directories (folders) containing X12
EDI files. You can supply multiple space-delimited
files or directories. You can also use '*' and '?'
wildcards to convert all matching files. In case of
a directory, all files in this directory will be
converted.
-p, --patterns=<filePatterns>
File name patterns to match in the root directory, e.
g., '*837P.edi'. You can specify multiple
comma-delimited patterns, e.g., '*837*.edi, *837*.
txt'. Defaults to '*' (all files) if
'ediFilesOrDirectories' is a directory. Enclose in
single quotes on Windows or '"' on Linux. Patterns
match only file names, not directory/folder names.
-r, --recurse Recursively search for matching files in all
subdirectories.
-o, --out=outputFileOrDirectory
Output file or directory where to save output files.
The file will be created if it doesn't exist; all
input files will be converted into it. For a
directory (must be an existing directory or end
with a slash), the output file name will be the EDI
file name plus the extension, depending on the
output format. If omitted, the converter will
output to the console (standard out), which can be
piped to another program.
-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-handlin
g for more details.
--max-warnings=<maxWarnings>
The maximum number of parsing warnings per file
before stopping and raising an error. Defaults to
3000. Set to -1 to suppress raising the 'too many
warnings' error; the converter will process the
entire file.
--chunk-size=<chunkSize>
The number of EDI transactions or
claims/payments/members for 837/835/834 that will
be parsed and converted at once. This option
determines the memory footprint and can be used for
fine-tuning. Defaults to 50. Higher value improves
performance but consumes more memory.
--[no-]split-tran Do not parse the entire transaction. Instead, parse
by claims (CLM or CLP segments, 837/835) or members
(INS segment, 834). This is the default for 835,
837, and 834 transactions. Ignored for all other
transaction types. Defaults to 'true'.
--progress-chunk-size=<loggingChunkSize>
How often to log progress. By default, the conversion
progress is logged every 1000 items (claims,
members, transactions)
-q, --quiet, --suppress-progress
Suppress logging file names and conversion progress
to the console; use this option when converting to
standard out
--out-segments Convert to the X12 EDI loop and segment tree format
rather than a list of claims, payments, and other
objects. JSON or JSONL only. It can be slow for
large transactions.
-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, 834.
--single-csv Convert all EDI files into a single CSV file
containing the claim-level and the service
line-level fields (837/835). If not provided, the
converter will convert claim-level and line-level
data into separate files. Same as providing
'--csv-schema-name=single-file'. A single file is
the default for 834.
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.
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 writing output to standard output.
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