Nora
3bf5622010
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').
79 lines
3.5 KiB
Markdown
79 lines
3.5 KiB
Markdown
# 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` (NM1*40 NM109, 1000B receiver) and `CO_TXIX` (NM1*PR 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` |
|