EDI Converter API User Guide

The EDI Converter API provides two main endpoints for converting EDI files:

Both endpoints accept plain text request bodies and multipart/form-data uploads. For multipart requests, the parameter name must be files:

curl -F files=@"837-1.dat" -F files=@"837-2.dat" $API_URL/edi/json

You can find more examples in our GitHub repo.

See the API reference for endpoint parameters and response schemas. Expand the “200” response to view the schema for a successful response.

See the JSON schema and CSV data dictionary documentation for details about JSON fields and CSV columns.

Streaming Mode

Conversion always runs in streaming mode:

  • The API server parses a chunk of EDI items from the input.
  • For each item in the chunk, the API server converts it to the target format and writes the result to the output.

The item type depends on the transaction type. For 837 transactions, each item is a claim (CLM segment). For 835 transactions, each item is a payment (CLP segment). For 834 transactions, each item is a member coverage record (INS segment). For all other transaction types, each item is the full transaction (ST segment).

The API uses a sensible default chunk size, and you can override it with the chunkSize parameter. For 835, 837, and 834 transactions, the default is 50 items per chunk. For all other transaction types, the default is 20 transactions per chunk because individual transactions can be large.

This means the API client starts receiving output as soon as the first chunk is parsed. The API server does not wait for the entire file to be parsed before sending the response.

JSON vs NDJSON

The API server can produce well-formed JSON for input files of any size. The JSON response is an array of objects, where each object is a claim, a payment, member coverage record, or EDI transaction.

For large files, use a streaming parser instead of deserializing the entire JSON array into memory.

For most large-file workflows, we recommend NDJSON. The NDJSON response contains the same objects as the JSON response, but without the enclosing array. Each object is written on a separate line.

Here is a Python example:

for claim_str in response.iter_lines():
    # each line is a claim object
    claim = json.loads(claim_str)
    pcn = claim['patientControlNumber']
    charge = claim['chargeAmount']
    billing_npi = claim['billingProvider']['identifier']

Set the ndjson=true parameter on the edi/json endpoint to receive an NDJSON response.

Error Handling

Always check for parsing errors in the streaming response. If a parsing error occurs at the beginning of the file, the API returns a 400 response code. For large files, an error can occur later in the stream after the API has already sent a 200 response code to the client.

Errors are serialized as objects with objectType set to ERROR. Normally, successfully converted objects have objectType set to values such as CLAIM or PAYMENT.

Example error object:

{
  "objectType": "ERROR",
  "message": "Unable to parse EDI segment",
  "fileName": "unexpected_segments.dat"
}

Your client code should branch on objectType before processing a converted object.

For example:

if claim['objectType'] == 'ERROR':
    raise Exception(f'Error parsing EDI; Error: {claim}')
else:
    # Your claim processing logic

See this Python example for more details.

For CSV output, an error line starts with the ERROR: prefix.

if line.startswith("ERROR:"):
    raise Exception(f'Error parsing EDI; Error: {line}')

See this Python example for more details.

Parsing warnings are deprecated as of release 2.15. Do not rely on WARNING objects, the warningsInResponse parameter, or warning lines in CSV output for EDI quality checks. Use the EDI Validation API instead. Validation returns structured validation issue objects that include the EDI loop, segment, element, source location, failing value, and a human-readable message.

You can run validation while converting by setting validate=true on the api/edi/json endpoint, or you can call api/edi/validate to return only validation issues.

Code Descriptions

The API server can provide descriptions for all codes (CPT, HCPCS, ICD, etc.) directly in the JSON response. The latest API server version always comes with the latest code descriptions files.

Descriptions can increase the size of the response. You can disable this feature by setting the descriptions=false request parameter.

You can also disable descriptions globally by setting the codeset_enrichcodes environment variable to false. In that case, the descriptions parameter is ignored. Disabling descriptions globally also improves server startup time.

As an alternative to returning descriptions directly in the conversion response, you can use our code search API. This public API requires an API key. Your EDI Converter license can be used as the API key.

X12 EDI Codes and Qualifiers Translation

The converter translates X12 EDI codes into mnemonic constants. For example, entity identifier code 77 is translated to SERVICE_FACILITY.

These mnemonic constants are stable and can be used as enums or constants in client code.

You can find the complete list of constants with our code lookup. Enter the name of any constant to see its description and the EDI code it corresponds to, for example, SERVICE_FACILITY.