Files

T

Nora 3bf5622010 docs(sp33): update reference docs to CO_TXIX (per HCPF 837P Companion Guide)

docs/reference/837p.md line 48: the CO Medicaid trading-partner line
was still saying 'SKCO0 (sender) <-> COHCPF (receiver)'. The HCPF
837P Companion Guide (June 2025 - Version 2.5) requires
NM1*PR NM109 = CO_TXIX; SKCO0 causes Gainwell to reject the SET
('2010BB NM109 must equal CO_TXIX or CO_BHA').

docs/reference/co-medicaid.md line 118 + the Trading Partner table at
the top: same fix, with a pointer to the SP33 spec for the
root-cause story.

No code changes. Pure doc fix to match what the source now emits
(PayerConfig.co_medicaid().payer_id = 'CO_TXIX').

2026-07-02 21:07:12 -06:00

3.5 KiB

Raw Blame History

837P — Professional Claims (005010X222A1)

The 837P transaction set carries professional (outpatient) healthcare claims from a billing provider to a payer. Cyclone parses the segments it needs to produce a structured ClaimOutput and validates against CO Medicaid rules.

File format

Extension: .txt
Encoding: ASCII (UTF-8 also accepted)
Delimiters (declared in ISA): * element, : component, ~ segment, ^ repetition

Envelope

Segment	Purpose
`ISA` / `IEA`	Interchange envelope (sender ↔ receiver)
`GS` / `GE`	Functional group envelope
`ST` / `SE`	Transaction set envelope (837)

Loops

Loop	Contents
2000A	Billing provider hierarchy (NM1*85)
2000B	Subscriber hierarchy (NM1*IL)
2300	Claim (CLM, HI, NM1, DTP, REF…)
2400	Service line (LX, SV1, DTP)

Segments Cyclone parses

NM1, N3, N4 — names and addresses
REF — prior auth (REF*G1), provider taxonomy, etc.
CLM — claim header; CLM01 = patient control number, CLM02 = total claim charge
HI — diagnoses (qualifier ABK = ICD-10 principal)
LX, SV1 — service line + procedure code
DTP — service date (DTP*472)
BHT — beginning of hierarchical transaction

Segments preserved but not modeled

All other segments are kept in raw_segments for audit but are not extracted into the structured ClaimOutput. See cyclone/parsers/parse_837.py for the full walker.

CO Medicaid specifics

Trading partners: COMEDASSISTPROG (NM140 NM109, 1000B receiver) and CO_TXIX (NM1PR NM109, 2010BB payer). See docs/goodclaim.x12 for a canonical example and the HCPF 837P Companion Guide for the full segment table.
CLM05 is a composite of three components: place of service, facility code qualifier, and frequency code (in that order)
- CLM05-1 = place of service (any valid CMS POS code)
- CLM05-2 = facility code qualifier (B for CMS POS)
- CLM05-3 = frequency code; must be one of {1, 7, 8} (1 = original, 7 = replacement, 8 = void)
REF*G1 carries prior-authorization number when applicable
No 2010BA/2010CA patient loop — subscriber is the patient
CLM06 (provider signature on file) and CLM07 (assignment of benefits) are typically Y

Validation rules Cyclone enforces

Rules are defined in cyclone/parsers/validator.py and registered on the PayerConfig for the active payer. The default co_medicaid() factory uses allowed_claim_frequencies={1, 7, 8} and the full CMS POS set.

Rule	Severity	Description
`R010_clm01_present`	error	`CLM01` (patient control number) is empty
`R011_total_charge_positive`	error	`CLM02` (total charge) must be `> 0`
`R020_npi_format`	error	Billing provider NPI must be 10 digits
`R030_frequency_allowed`	error	`CLM05-3` ∈ `allowed_claim_frequencies`
`R031_ref_g1_optional`	—	`REF*G1` is informational in v1; no issues yielded
`R032_clm05_2_facility_qualifier`	error	`CLM05-2` ∈ `allowed_facility_qualifiers` (e.g. `B`)
`R033_clm05_1_place_of_service_code`	error	`CLM05-1` ∈ `allowed_place_of_service_codes` (CMS POS)
`R050_diagnosis_present`	error	At least one diagnosis on the `HI` segment
`R060_service_dates_present`	error	Every service line has a `DTP*472` service date
`R070_charges_sum`	warning	Sum of service-line charges matches `CLM02` (±$0.01)
`R100_payer_id_matches`	warning	`NM1*PR N104` matches the configured `payer_id`

3.5 KiB Raw Blame History