EDI Generation API (New in 2.15)

Overview

The EDI Converter API can generate X12 EDI from JSON objects. In the 2.15 release, generation is supported for:

835 payment transactions
837P professional claim transactions
837I institutional claim transactions

The generation API uses the same business object model as the converter and parser. For example, the Payment, Claim, Provider, Party, Code, Procedure, ServiceLine, and adjustment objects are the same objects returned by the EDI-to-JSON API. See the JSON object model for the model overview.

The API accepts a JSON request and returns generated EDI as text/plain.

Generation Endpoints

Use the 835 endpoint to generate payment EDI:

curl -H "Content-Type: application/json" \
  --data-binary @edi_gen/request/835-minimal.json \
  "$SERVER_URL/api/edi/gen/835"

Use the 837 endpoint to generate professional or institutional claim EDI:

curl -H "Content-Type: application/json" \
  --data-binary @edi_gen/request/837p-minimal.json \
  "$SERVER_URL/api/edi/gen/837"

The 837 endpoint generates either 837P or 837I based on the request object. Use transaction.transactionType: "PROF" and professional claim objects for 837P. Use transaction.transactionType: "INST" and institutional claim objects for 837I.

Both generation endpoints support these query parameters:

failOnValidationErrors: set to true to fail the request when validation errors are found.
fileName: optional file name used in validation warnings and errors.

If failOnValidationErrors=true and validation issues are found, the API returns HTTP 417 with a JSON array of validation issue objects. Otherwise, validation issues are logged, and the generated EDI is returned.

Validating a Generation Request

You can validate a generation request before producing EDI:

curl -H "Content-Type: application/json" \
  --data-binary @edi_gen/request/835-minimal.json \
  "$SERVER_URL/api/edi/gen/835/validate"

curl -H "Content-Type: application/json" \
  --data-binary @edi_gen/request/837p-minimal.json \
  "$SERVER_URL/api/edi/gen/837/validate"

The validation endpoints return a JSON array of validation issues. If no issues are found, the response is an empty array.

Validation issue objects use the same schema described in the EDI Validation API guide.

Public API

You can also use the public API with your EDI Converter license key. Send the license key in the X-Api-Key header:

curl -H "Content-Type: application/json" \
  -H "X-Api-Key: $API_KEY" \
  --data-binary @edi_gen/request/835-minimal.json \
  "https://datainsight.health/clinsight/api/edi/gen/835"

Do not submit PHI (personally identifiable information) to the public API.

Request Object Structure

An 835 generation request contains:

interchangeControl: ISA/IEA envelope information.
functionalGroup: GS/GE group information.
transaction: transaction-level 835 payment information.
payments: payment objects to write as CLP claims and service lines.

An 837 generation request contains:

interchangeControl: ISA/IEA envelope information.
functionalGroup: GS/GE group information.
transaction: transaction-level 837 claim information.
claims: professional or institutional claim objects to write as 837P or 837I.

You can omit some control fields, such as dates, times, control numbers, and IDs, and the API will generate defaults when possible.

835 Request Example

This shortened example shows the shape of a payment generation request:

{
  "interchangeControl": {
    "senderIdQualifier": "ZZ",
    "senderId": "123",
    "receiverIdQualifier": "ZZ",
    "receiverId": "456"
  },
  "functionalGroup": {
    "transactionType": "PAYMENT",
    "senderCode": "1",
    "receiverCode": "2"
  },
  "transaction": {
    "transactionType": "PAYMENT",
    "totalPaymentAmount": 1000.00,
    "paymentMethodType": "CHECK",
    "paymentDate": "2026-06-01",
    "checkOrEftTraceNumber": "CHECK_1",
    "payerIdentifier": "PAYER_ID01",
    "receiverIdentifier": "CLEARINGHOUSE_ID"
  },
  "payments": [
    {
      "patientControlNumber": "5554555444",
      "chargeAmount": 800.00,
      "paymentAmount": 500.00,
      "claimStatusCode": "1",
      "payerControlNumber": "94060555410000",
      "serviceLines": [
        {
          "chargeAmount": 800.00,
          "paidAmount": 500.00,
          "procedure": {
            "subType": "CPT",
            "code": "99211"
          }
        }
      ]
    }
  ]
}

See the complete request examples:

837 Request Example

This shortened example shows the shape of a professional claim generation request:

{
  "interchangeControl": {
    "senderIdQualifier": "ZZ",
    "senderId": "123",
    "receiverIdQualifier": "ZZ",
    "receiverId": "456"
  },
  "functionalGroup": {
    "transactionType": "PROF",
    "senderCode": "1",
    "receiverCode": "2"
  },
  "transaction": {
    "transactionType": "PROF",
    "sender": {
      "identifier": "TGJ23",
      "lastNameOrOrgName": "PREMIER BILLING SERVICE"
    },
    "receiver": {
      "identifier": "66783JJT",
      "lastNameOrOrgName": "KEY INSURANCE COMPANY"
    }
  },
  "claims": [
    {
      "patientControlNumber": "26463774",
      "chargeAmount": 100.00,
      "facilityCode": {
        "code": "11"
      },
      "frequencyCode": {
        "code": "1"
      },
      "subscriber": {
        "payerResponsibilitySequence": "PRIMARY",
        "person": {
          "identifier": "JS00111223333",
          "lastNameOrOrgName": "Smith",
          "firstName": "Jane"
        }
      },
      "billingProvider": {
        "identifier": "9876543210",
        "taxId": "587654321",
        "lastNameOrOrgName": "Ben Kildare Service"
      },
      "diags": [
        {
          "code": "J020"
        }
      ],
      "serviceLines": [
        {
          "chargeAmount": 100.00,
          "serviceDateFrom": "2006-10-03",
          "unitCount": 1,
          "procedure": {
            "code": "99213"
          },
          "diagPointers": [
            1
          ]
        }
      ]
    }
  ]
}

See the complete request examples:

Python Examples

The Python client exposes generation helpers under client.generation.

Generate 835 EDI:

from ediconvert_sdk import EdiConverterClient, EdiGenerationValidationError

request = build_request()
client = EdiConverterClient(base_url=env.api_url)

try:
    edi_text = client.generation.generate_835(
        request,
        fail_on_validation_errors=True,
    )
except EdiGenerationValidationError as exc:
    for issue in exc.validation_issues:
        print(issue)

Generate 837P or 837I EDI:

from ediconvert_sdk import EdiConverterClient, EdiGenerationValidationError

request = build_request()
client = EdiConverterClient(base_url=env.api_url)

try:
    edi_text = client.generation.generate_837(
        request,
        fail_on_validation_errors=True,
    )
except EdiGenerationValidationError as exc:
    for issue in exc.validation_issues:
        print(issue)

Validate a request without generating EDI:

issues = client.generation.validate_837(request)
if issues:
    for issue in issues:
        print(issue)

See the complete Python examples:

API Reference

See the API Reference for the full request and response schemas:

/api/edi/gen/835
/api/edi/gen/835/validate
/api/edi/gen/837
/api/edi/gen/837/validate