Python SDK API Reference (2.15)

Install the SDK from PyPI:

python -m pip install ediconvert-sdk

The EdiConverterClient provides grouped clients for EDI conversion, generation, validation, and application information. See the EDI Converter API reference for the underlying HTTP endpoints and schemas.

Python Object Model

The SDK includes the generated edi_model package. Its Pydantic models represent claims, payments, member coverage, validation issues, EDI generation requests, and the supporting objects nested within them. The models are generated from the same OpenAPI schemas used by the API, so this reference does not duplicate every model class and field. See the JSON schema documentation for field definitions, descriptions, examples, and mappings to X12 EDI segments and elements.

Model attributes use Python snake_case names, while aliases map them to the API’s camelCase JSON fields. Use Pydantic’s model_validate() to convert a decoded API object into a typed model. To serialize a model for the API, use model_dump(by_alias=True, exclude_none=True, mode="json").

General Usage Pattern

Conversion streams can contain different business-object types as well as warnings, errors, and validation issues. Inspect objectType before selecting the model class:

import json

from edi_model.all_classes import Payment, ProviderAdjustment
from edi_model.enums import ObjectType
from ediconvert_sdk import EdiConverterClient, handle_warning_error


with EdiConverterClient("http://localhost:5080/api") as client:
    response = client.conversion.to_json_file(
        "835.edi",
        ndjson=True,
        validate=True,
    )

    for line in response.iter_lines():
        data = json.loads(line)

        # Handle ERROR, WARNING, and VALIDATION objects before business objects.
        if handle_warning_error(data):
            continue

        object_type = ObjectType(data["objectType"])
        if object_type is ObjectType.PAYMENT:
            payment = Payment.model_validate(data)
            print(payment.patient_control_number, payment.payment_amount)
        elif object_type is ObjectType.PROVIDER_ADJUSTMENT:
            adjustment = ProviderAdjustment.model_validate(data)
            print(adjustment.fiscal_period_date)

Client interfaces for the Healthcare Data Insight EDI Converter API.

The main entry point is EdiConverterClient. It exposes grouped clients for conversion, generation, validation, and application-information endpoints.

`EdiConverterError`

class EdiConverterError(Exception)

Base class for errors raised by the EDI Converter SDK.

`EdiConverterApiError`

class EdiConverterApiError(EdiConverterError)

Error raised when the API returns an unexpected HTTP status.

Attributes:

response - Original response returned by the API.
status_code - HTTP status code from the response.
body - Response body decoded as text.

`EdiGenerationValidationError`

class EdiGenerationValidationError(EdiConverterApiError)

Error raised when validation prevents EDI generation.

This exception is raised by GenerationClient.generate_835 and GenerationClient.generate_837 when fail_on_validation_errors is enabled and the API returns HTTP 417.

Attributes:

validation_issues - Validation issues returned by the API as typed edi_model.all_classes.ValidationIssue objects.

`EdiConverterClient`

class EdiConverterClient()

Client for the EDI Converter API.

The client groups operations under conversion, generation, validation, and about. It can be used as a context manager so an internally created HTTP session is closed automatically.

Example usage:

with EdiConverterClient("http://localhost:5080/api") as client:
    response = client.conversion.to_json_file(
        "claim.edi",
        ndjson=True,
        validate=True,
    )
    for line in response.iter_lines():
        process(line)

Arguments:

base_url - API root or server root. Both http://localhost:5080/api and http://localhost:5080 are accepted. When omitted, the client uses EDICONVERT_BASE_URL and then DEFAULT_BASE_URL.
api_key - API key sent in the X-API-Key header. Public API calls require a key; local API installations normally do not. When omitted, the client uses EDICONVERT_API_KEY if it is set.
timeout - Request timeout passed to requests. A number applies to both connection and response reads; a (connect, read) tuple configures them separately.
session - Optional preconfigured requests.Session. The caller owns a supplied session and remains responsible for closing it.
headers - Additional headers applied to the session. The API-key header, when configured, is applied after these values.

Attributes:

base_url - Normalized base URL used for requests.
timeout - Configured request timeout.
session - HTTP session used by all grouped clients.
conversion - EDI-to-JSON and EDI-to-CSV operations.
generation - 835 and 837 generation and request-validation operations.
validation - EDI validation operations returning JSON or annotated text.
about - Application version and license information operation.

`EdiConverterClient.close`

def close() -> None

Close the internally created HTTP session.

A session supplied through the constructor is not closed because it is owned by the caller. Calling this method more than once is safe.

`EdiConverterClient.get`

def get(path: str, *, expected_statuses: set[int] | None = None) -> Response

Send a low-level GET request to an API-relative path.

Most users should prefer the grouped endpoint clients. This method is available for API operations that do not yet have a dedicated wrapper.

Arguments:

path - Endpoint path relative to the API root, with or without a leading slash.
expected_statuses - Status codes treated as successful. Defaults to {200}.

Returns:

The original requests.Response.

Raises:

EdiConverterApiError - If the response status is not expected.
requests.RequestException - If the HTTP request cannot be completed.

`EdiConverterClient.post`

def post(path: str,
         *,
         params: dict[str, Any] | None = None,
         data: Any = None,
         json: Any = None,
         files: Any = None,
         headers: dict[str, str] | None = None,
         stream: bool = False,
         expected_statuses: set[int] | None = None) -> Response

Send a low-level POST request to an API-relative path.

Most users should prefer the grouped endpoint clients. Parameters with a value of None are omitted, and boolean query parameters are sent as lowercase true or false strings.

Arguments:

path - Endpoint path relative to the API root, with or without a leading slash.
params - Query parameters.
data - Raw request body accepted by requests.Session.post.
json - JSON-serializable request body.
files - Multipart file data accepted by requests.
headers - Request-specific headers.
stream - Whether response content should be downloaded lazily.
expected_statuses - Status codes treated as successful. Defaults to {200}.

Returns:

The original requests.Response. When stream is true, consume the response body or close the response to release the connection.

Raises:

EdiConverterApiError - If the response status is not expected.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient`

class ConversionClient()

EDI-to-JSON and EDI-to-CSV operations.

Instances are available through EdiConverterClient.conversion. Conversion responses can be streamed and may contain an error after the API has already returned HTTP 200. JSON consumers should inspect objectType; CSV consumers should check for lines beginning with ERROR:.

`ConversionClient.to_json`

def to_json(edi_text: str | bytes,
            *,
            validate: bool | None = None,
            ndjson: bool | None = None,
            descriptions: bool | None = None,
            convert_control_segments: bool | None = None,
            transaction_top_level: bool | None = None,
            convert_to_segments: str | None = None,
            edi_file_name: str | None = None,
            chunk_size: int | None = None,
            warnings_in_response: bool | None = None,
            max_warnings: int | None = None,
            split_tran: bool | None = None,
            stream: bool = True) -> Response

Convert EDI text to JSON or newline-delimited JSON.

Arguments:

edi_text - X12 EDI content as text or bytes.
validate - Run full EDI validation and include VALIDATION objects in the response stream.
ndjson - Return newline-delimited JSON instead of a JSON array. This is recommended for large inputs and streaming workflows.
descriptions - Include descriptions for healthcare and EDI codes.
convert_control_segments - Include INTERCHANGE_CONTROL and FUNCTIONAL_GROUP objects for ISA and GS segments.
transaction_top_level - Emit transactions as separate top-level TRANSACTION objects instead of repeating transaction data in each business object.
convert_to_segments - Convert to an EDI loop and segment tree instead of claims, payments, members, and other business objects.
edi_file_name - Logical source name propagated to response file metadata. This parameter applies only to text-body requests.
chunk_size - Number of transactions or business objects parsed and converted per chunk. Larger values may improve throughput while using more memory.
warnings_in_response - Include parsing warnings in the response. Deprecated since API 2.15; use validate instead.
max_warnings - Maximum parsing warnings allowed before processing stops. Deprecated since API 2.15.
split_tran - Split 835, 837, and 834 transactions by business object. Deprecated because the API now selects this automatically.
stream - Download the response body lazily. Leave enabled for large responses and consume or close the returned response.

Returns:

A requests.Response containing JSON or NDJSON conversion output.

Raises:

EdiConverterApiError - If the API immediately returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient.to_json_file`

def to_json_file(file_path: PathLike, **kwargs: Any) -> Response

Convert one EDI file to JSON or NDJSON.

Arguments:

file_path - Path to the EDI file. Its path is used as edi_file_name unless that argument is provided explicitly.
**kwargs - Options accepted by to_json.

Returns:

A requests.Response containing JSON or NDJSON conversion output.

Raises:

OSError - If the input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient.to_json_files`

def to_json_files(file_paths: Iterable[PathLike], **kwargs: Any) -> Response

Upload and convert multiple EDI files to JSON or NDJSON.

Files are sent as a multipart/form-data request using the files field. Each input file should have a unique name.

Arguments:

file_paths - Paths to EDI files to upload.
**kwargs - Conversion options accepted by to_json, except edi_file_name, which the API ignores for multipart uploads.

Returns:

A requests.Response containing combined conversion output.

Raises:

OSError - If an input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient.to_csv`

def to_csv(edi_text: str | bytes,
           *,
           schema_file_name: str | None = None,
           schema_name: str | None = None,
           edi_file_name: str | None = None,
           chunk_size: int | None = None,
           warnings_in_response: bool | None = None,
           max_warnings: int | None = None,
           stream: bool = True) -> Response

Convert EDI text to CSV.

Arguments:

edi_text - X12 EDI content as text or bytes.
schema_file_name - Name of the API-side CSV schema configuration file. The API default is csv_conversion.yaml.
schema_name - Schema within the CSV configuration file. The API default is lines-with-header-repeat-first-row.
edi_file_name - Logical source name propagated to the fileName CSV column. This parameter applies only to text-body requests.
chunk_size - Number of claims, payments, or members parsed at once. Larger values may improve throughput while using more memory.
warnings_in_response - Write warnings into the first CSV column with a WARNING: prefix. Deprecated; use EDI text validation.
max_warnings - Maximum parsing warnings allowed before processing stops. This API parameter is deprecated.
stream - Download the response body lazily. Leave enabled for large responses and consume or close the returned response.

Returns:

A requests.Response containing streamed CSV text.

Raises:

EdiConverterApiError - If the API immediately returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient.to_csv_file`

def to_csv_file(file_path: PathLike, **kwargs: Any) -> Response

Convert one EDI file to CSV.

Arguments:

file_path - Path to the EDI file. Its path is used as edi_file_name unless that argument is provided explicitly.
**kwargs - Options accepted by to_csv.

Returns:

A requests.Response containing streamed CSV text.

Raises:

OSError - If the input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ConversionClient.to_csv_files`

def to_csv_files(file_paths: Iterable[PathLike], **kwargs: Any) -> Response

Upload and convert multiple EDI files to CSV.

Files are sent as a multipart/form-data request using the files field. Each input file should have a unique name.

Arguments:

file_paths - Paths to EDI files to upload.
**kwargs - Conversion options accepted by to_csv, except edi_file_name, which the API ignores for multipart uploads.

Returns:

A requests.Response containing combined CSV output.

Raises:

OSError - If an input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`GenerationClient`

class GenerationClient()

835 and 837 EDI generation operations.

Instances are available through EdiConverterClient.generation. Request bodies may be SDK Pydantic models or dictionaries that match the corresponding API request schema.

`GenerationClient.generate_837`

def generate_837(request: EdiGenClaimRequest | dict[str, Any],
                 *,
                 fail_on_validation_errors: bool | None = None,
                 file_name: str | None = None) -> str

Generate an X12 837P or 837I document.

Arguments:

request - Claim-generation request as an EdiGenClaimRequest or a dictionary matching that model.
fail_on_validation_errors - Ask the API to return HTTP 417 instead of EDI when validation issues are found.
file_name - Logical file name used in validation issues and errors. The API generates a random name when this is omitted.

Returns:

Generated 837 EDI text.

Raises:

EdiGenerationValidationError - If validation prevents generation.
EdiConverterApiError - If the API returns another unexpected status.
requests.RequestException - If the HTTP request cannot be completed.

`GenerationClient.generate_837_response`

def generate_837_response(request: EdiGenClaimRequest | dict[str, Any],
                          *,
                          fail_on_validation_errors: bool | None = None,
                          file_name: str | None = None) -> Response

Generate an X12 837 document and return the complete HTTP response.

Unlike generate_837, this method does not raise EdiGenerationValidationError for HTTP 417. Callers can inspect response.status_code and parse validation issues from the response.

Arguments:

request - Claim-generation request as an EdiGenClaimRequest or a dictionary matching that model.
fail_on_validation_errors - Ask the API to return HTTP 417 instead of EDI when validation issues are found.
file_name - Logical file name used in validation issues and errors.

Returns:

A requests.Response with EDI text for HTTP 200 or validation issue JSON for HTTP 417.

Raises:

EdiConverterApiError - If the API returns a status other than 200 or 417.
requests.RequestException - If the HTTP request cannot be completed.

`GenerationClient.validate_837`

def validate_837(request: EdiGenClaimRequest | dict[str, Any],
                 *,
                 file_name: str | None = None) -> list[ValidationIssue]

Validate an 837 generation request without generating EDI.

Arguments:

request - Claim-generation request as an EdiGenClaimRequest or a dictionary matching that model.
file_name - Logical file name used in validation issues and errors.

Returns:

Typed validation issues. The list is empty when no issues are found.

Raises:

EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.
pydantic.ValidationError - If a returned validation issue does not match the SDK model.

`GenerationClient.generate_835`

def generate_835(request: EdiGenPaymentRequest | dict[str, Any],
                 *,
                 fail_on_validation_errors: bool | None = None,
                 file_name: str | None = None) -> str

Generate an X12 835 document.

Arguments:

request - Payment-generation request as an EdiGenPaymentRequest or a dictionary matching that model.
fail_on_validation_errors - Ask the API to return HTTP 417 instead of EDI when validation issues are found.
file_name - Logical file name used in validation issues and errors. The API generates a random name when this is omitted.

Returns:

Generated 835 EDI text.

Raises:

EdiGenerationValidationError - If validation prevents generation.
EdiConverterApiError - If the API returns another unexpected status.
requests.RequestException - If the HTTP request cannot be completed.

`GenerationClient.generate_835_response`

def generate_835_response(request: EdiGenPaymentRequest | dict[str, Any],
                          *,
                          fail_on_validation_errors: bool | None = None,
                          file_name: str | None = None) -> Response

Generate an X12 835 document and return the complete HTTP response.

Unlike generate_835, this method does not raise EdiGenerationValidationError for HTTP 417. Callers can inspect response.status_code and parse validation issues from the response.

Arguments:

request - Payment-generation request as an EdiGenPaymentRequest or a dictionary matching that model.
fail_on_validation_errors - Ask the API to return HTTP 417 instead of EDI when validation issues are found.
file_name - Logical file name used in validation issues and errors.

Returns:

A requests.Response with EDI text for HTTP 200 or validation issue JSON for HTTP 417.

Raises:

EdiConverterApiError - If the API returns a status other than 200 or 417.
requests.RequestException - If the HTTP request cannot be completed.

`GenerationClient.validate_835`

def validate_835(request: EdiGenPaymentRequest | dict[str, Any],
                 *,
                 file_name: str | None = None) -> list[ValidationIssue]

Validate an 835 generation request without generating EDI.

Arguments:

request - Payment-generation request as an EdiGenPaymentRequest or a dictionary matching that model.
file_name - Logical file name used in validation issues and errors.

Returns:

Typed validation issues. The list is empty when no issues are found.

Raises:

EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.
pydantic.ValidationError - If a returned validation issue does not match the SDK model.

`ValidationClient`

class ValidationClient()

EDI validation operations.

Instances are available through EdiConverterClient.validation. Validation can return structured issue objects as JSON/NDJSON or the original EDI text annotated with issue lines.

`ValidationClient.to_json`

def to_json(edi_text: str | bytes,
            *,
            file_name: str | None = None,
            ndjson: bool | None = None,
            chunk_size: int | None = None,
            stream: bool = False) -> Response

Validate EDI text and return validation issues as JSON or NDJSON.

Arguments:

edi_text - X12 EDI content as text or bytes.
file_name - Logical file name used in validation issues and errors. The API generates a random name when this is omitted.
ndjson - Return one JSON issue per line instead of a JSON array. This is recommended for large inputs and streaming workflows.
chunk_size - Number of transactions or business objects validated per chunk. Larger values may improve throughput while using more memory.
stream - Download the response body lazily. Consume or close a streamed response to release the connection.

Returns:

A requests.Response containing a JSON array or NDJSON stream of validation issues. A valid document produces an empty result.

Raises:

EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ValidationClient.to_json_file`

def to_json_file(file_path: PathLike, **kwargs: Any) -> Response

Validate one EDI file and return issues as JSON or NDJSON.

Arguments:

file_path - Path to the EDI file. Its path is used as file_name unless that argument is provided explicitly.
**kwargs - Options accepted by to_json.

Returns:

A requests.Response containing validation issues.

Raises:

OSError - If the input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ValidationClient.to_json_files`

def to_json_files(file_paths: Iterable[PathLike], **kwargs: Any) -> Response

Upload and validate multiple EDI files as JSON or NDJSON.

Files are sent as a multipart/form-data request using the files field. Each input file should have a unique name.

Arguments:

file_paths - Paths to EDI files to upload.
**kwargs - Validation options accepted by to_json, except file_name, which is not used for multipart uploads.

Returns:

A requests.Response containing combined validation issues.

Raises:

OSError - If an input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ValidationClient.to_text`

def to_text(edi_text: str | bytes,
            *,
            issue_string_prefix: str | None = None,
            stream: bool = True) -> Response

Validate EDI text and return an annotated EDI document.

The response contains the submitted EDI with validation messages placed below the affected segments.

Arguments:

edi_text - X12 EDI content as text or bytes.
issue_string_prefix - Prefix for validation-message lines. The API default is !!.
stream - Download the response body lazily. Consume or close a streamed response to release the connection.

Returns:

A requests.Response containing annotated EDI text.

Raises:

EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ValidationClient.to_text_file`

def to_text_file(file_path: PathLike, **kwargs: Any) -> Response

Validate one EDI file and return annotated EDI text.

Arguments:

file_path - Path to the EDI file.
**kwargs - Options accepted by to_text.

Returns:

A requests.Response containing annotated EDI text.

Raises:

OSError - If the input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`ValidationClient.to_text_files`

def to_text_files(file_paths: Iterable[PathLike], **kwargs: Any) -> Response

Upload and validate multiple EDI files as annotated text.

Files are sent as a multipart/form-data request using the files field. Each input file should have a unique name.

Arguments:

file_paths - Paths to EDI files to upload.
**kwargs - Options accepted by to_text.

Returns:

A requests.Response containing combined annotated EDI text.

Raises:

OSError - If an input file cannot be opened.
EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.

`AboutClient`

class AboutClient()

Application version and license-information operation.

Instances are available through EdiConverterClient.about.

`AboutClient.get`

def get() -> AppInfo

Return information about the API server and its license.

Returns:

Application information parsed into an AppInfo model.

Raises:

EdiConverterApiError - If the API returns an unexpected HTTP status.
requests.RequestException - If the HTTP request cannot be completed.
pydantic.ValidationError - If the response does not match AppInfo.

`handle_warning_error`

def handle_warning_error(obj: dict[str, Any]) -> bool | None

Handle a warning, validation issue, or parsing error response object.

This helper is intended for objects read from JSON or NDJSON conversion streams. Warnings and validation issues are printed and marked as handled; parsing errors raise an SDK exception. Business objects are left untouched.

Arguments:

obj - Decoded conversion object containing an objectType field.

Returns:

True when a warning or validation issue was handled, otherwise None for a normal business object.

Raises:

EdiConverterError - If objectType is ERROR.
KeyError - If a required response field is missing.
ValueError - If objectType is not recognized by the SDK enum.