EDI API User Guide

There are two main endpoints for converting EDI files:

Both endpoints accept text or multipart/form-data uploads. The parameter name for multipart requests has to be files:

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

You can find more examples in our GitHub repo.

See API reference for details about parameters and the response schema.

Streaming Mode

The conversion is always performed in the streaming mode, meaning the following:

  • 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 type of the item depends on the transaction type. For 837 transactions, it’s a claim (CLM segment). For 835 it’s payment (CLP segment). For all other transactions, it’s the entire transaction (ST segment).

The chunk size is set to a sensible default, and you can also change it using the server’s configuration. For 835/837 transactions, the default is to parse 100 claims or payments in one go. For all other transaction types, it’s five transactions at a time (transactions could be quite large).

All this means that the API client will start receiving the response as soon as the first chunk of items is parsed. The API server never waits until the entire file is parsed.

Transaction Splitting

Certain EDI transactions could be quite large. E.g., a single 837P transaction can contain information about many claims and subscribers.

By default, our EDI parser parses one EDI transaction (or a set of transactions) at a time. This may require a lot of memory for large transactions. Another option is to parse by CLM/CLP segments for 837/835 transactions. In this case, the parser parses a certain number of claims or payments (and all the related objects such as subscribers) at a time. This approach works for transactions of any size.

Parsing by CLM/CLP can be enabled by supplying the splitTran=True parameter to the API. We recommend always setting it to “true” when parsing 835/837 files.

JSON vs NDJSON

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

In the case of large files, you have to use a streaming parser as opposed to deserializing the entire JSON array into memory.

We recommend using NDJSON format instead. The NDJSON response is identical to the well-formed JSON except for the enclosing array. Each object is separated by the new 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']

Use ndjson=true parameter for the edi/json endpoint to receive NDJSON response from the API.

Error Handling

You need to check for parsing errors in the streaming response. If a parsing error occurs at the beginning of the file, the API will return the 400 response code. However, for a large file, the error could occur later in the file, when the 200 response code was already sent to the client.

Therefore, you need to include checking for the objectType JSON property for each JSON object in the response. In case of an error, the value will be “ERROR”, otherwise the value is set to “CLAIM” or “PAYMENT”.

Example:

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

For CSV output, the line with the error will have the “ERROR:” prefix.

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