EDI API User Guide
There are two main endpoints for converting EDI files:
- /api/edi/json. Converts EDI to JSON or NDJSON
- /api/edi/csv. Converts to CSV (835/837 transactions only)
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}')