> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# X12 EDI Technical Design Document

> Version: 1.0.0 Last Updated: 2026-02-17 Source: CL-PM-SPEC-REVIEW Finding 8.7 Applicable Specs: PM-02, PM-08, PM-09, PM-15

**Version:** 1.0.0
**Last Updated:** 2026-02-17
**Source:** CL-PM-SPEC-REVIEW Finding 8.7
**Applicable Specs:** PM-02, PM-08, PM-09, PM-15

***

## Overview

This document defines the shared X12 EDI technical design for all PM specs that generate, submit, or consume ANSI X12 transactions. It covers segment-level mapping, behavioral health-specific requirements, and the clearinghouse abstraction layer.

***

## Transaction Types

| Transaction | Direction        | Spec  | Purpose                              |
| ----------- | ---------------- | ----- | ------------------------------------ |
| 270/271     | Outbound/Inbound | PM-02 | Eligibility inquiry/response         |
| 837P        | Outbound         | PM-08 | Professional claim submission        |
| 837I        | Outbound         | PM-08 | Institutional claim submission       |
| 835         | Inbound          | PM-09 | Electronic remittance advice (ERA)   |
| 276/277     | Outbound/Inbound | PM-08 | Claim status inquiry/response        |
| 278         | Outbound/Inbound | PM-10 | Prior authorization request/response |

***

## Envelope Structure

All X12 transactions follow ISA/GS/ST envelope structure:

```
ISA*00*          *00*          *ZZ*SENDER_ID      *ZZ*RECEIVER_ID    *YYMMDD*HHMM*^*00501*000000001*0*P*:~
  GS*HC*SENDER_ID*RECEIVER_ID*YYYYMMDD*HHMM*1*X*005010X222A1~
    ST*837*0001*005010X222A1~
      [Transaction-specific segments]
    SE*[segment_count]*0001~
  GE*1*1~
IEA*1*000000001~
```

### Envelope Field Sources

| Field            | Source                                       | Notes                        |
| ---------------- | -------------------------------------------- | ---------------------------- |
| ISA Sender ID    | `pm_clearinghouse_config.sender_id`          | Per-org clearinghouse config |
| ISA Receiver ID  | `pm_clearinghouse_config.receiver_id`        | Clearinghouse-specific       |
| GS Functional ID | Transaction type (HC=837P, HP=837I, HN=835)  | Fixed per transaction        |
| GS Version       | `005010X222A1` (837P), `005010X223A3` (837I) | Fixed per transaction        |

***

## 837P Professional Claim Mapping

### Key Loops and Segments

| Loop   | Segment               | Description                | Encore Health OS Source                           |
| ------ | --------------------- | -------------------------- | ------------------------------------------------- |
| 2000A  | HL (Billing Provider) | Billing provider hierarchy | `pm_claims.billing_provider_npi` + `pf_providers` |
| 2010AA | NM1\*85               | Billing provider name      | `pf_providers`                                    |
| 2010AA | N3/N4                 | Billing provider address   | `pf_providers.address`                            |
| 2010AA | REF\*EI               | Billing provider TIN       | `pf_providers.tax_id`                             |
| 2000B  | HL (Subscriber)       | Subscriber hierarchy       | `pm_patients` + `pm_insurance_policies`           |
| 2010BA | NM1\*IL               | Subscriber name            | `pm_patients.first_name/last_name`                |
| 2010BA | N3/N4                 | Subscriber address         | `pm_patients.address`                             |
| 2010BA | DMG                   | Subscriber demographics    | `pm_patients.date_of_birth, gender`               |
| 2010BB | NM1\*PR               | Payer name                 | `pm_payers.payer_name`                            |
| 2010BB | REF\*G2               | Payer ID                   | `pm_payers.payer_id`                              |
| 2300   | CLM                   | Claim information          | `pm_claims`                                       |
| 2300   | HI\*ABK               | Principal diagnosis        | `pm_claims.primary_diagnosis_code`                |
| 2300   | HI\*ABF               | Other diagnoses            | `pm_claim_lines.diagnosis_codes`                  |
| 2400   | SV1                   | Professional service line  | `pm_claim_lines`                                  |
| 2400   | DTP\*472              | Service date               | `pm_claim_lines.service_date`                     |

### Behavioral Health-Specific Segments

| Segment | BH Usage                 | Notes                                                     |
| ------- | ------------------------ | --------------------------------------------------------- |
| CLM05-1 | Place of Service         | 11 (office), 53 (CMHC), 55 (residential), 02 (telehealth) |
| SV101   | CPT/HCPCS with modifiers | HQ (group), GT/95 (telehealth), H9 (court-ordered)        |
| SV103   | Units                    | AHCCCS timed units from PM-07                             |
| SV107   | Diagnosis pointer        | Links to HI segments                                      |
| REF\*9F | Referral number          | Required for AHCCCS referral-based services               |
| NTE     | Note segment             | Prior authorization number for PM-10                      |

### AHCCCS Timed Unit Calculation

```
Minutes → Units mapping (from PM-07):
  <8 min  = 0 units (not billable)
  8-22    = 1 unit
  23-37   = 2 units
  38-52   = 3 units
  53-67   = 4 units
  68-82   = 5 units
  (pattern: each additional 15 min = +1 unit)
```

***

## 835 ERA Mapping

### Key Segments for Auto-Posting (PM-09)

| Segment    | Description         | Encore Health OS Target                              |
| ---------- | ------------------- | ---------------------------------------------------- |
| CLP        | Claim payment info  | `pm_claims.paid_amount`, `pm_claims.status`          |
| CLP01      | Claim ID            | Match to `pm_claims.claim_number`                    |
| CLP02      | Status code         | 1=processed primary, 2=processed secondary, 4=denied |
| CLP03      | Total charged       | Verify against `pm_claims.total_charge`              |
| CLP04      | Total paid          | `pm_payments.amount`                                 |
| SVC        | Service line detail | `pm_claim_lines` payment detail                      |
| CAS        | Adjustment reason   | CARC code → `pm_adjustments.adjustment_reason`       |
| CAS (RARC) | Remark code         | RARC → `pm_adjustments.remark_code`                  |
| DTM\*050   | Check date          | `pm_payments.payment_date`                           |
| TRN        | Check/EFT trace     | `pm_payments.reference_number`                       |

### ERA Auto-Posting Algorithm (PM-09)

```
1. Parse 835 file into CLP/SVC/CAS segments
2. For each CLP (claim-level):
   a. Match CLP01 to pm_claims.claim_number
   b. If no match: flag for manual review, continue
   c. Verify CLP03 (charged) matches pm_claims.total_charge
   d. If mismatch > threshold: flag for review
3. For each SVC (service line):
   a. Match to pm_claim_lines by CPT + date + provider
   b. Record paid amount
4. For each CAS (adjustment):
   a. Map CARC to adjustment category (CO/PR/OA/PI/CR)
   b. CO (contractual): auto-post adjustment
   c. PR (patient responsibility): create patient balance
   d. OA/PI: flag for review
   e. Store RARC remark for denial management
5. Create pm_payments record with check/EFT detail
6. Update pm_claims.status based on CLP02
7. If fully paid: status = 'paid'
8. If partial: status = 'partial_payment'
9. If denied: status = 'denied', trigger denial workflow
```

***

## 270/271 Eligibility Mapping (PM-02)

### 270 Request Key Segments

| Segment | Description           | Source                                               |
| ------- | --------------------- | ---------------------------------------------------- |
| NM1\*IL | Subscriber name       | `pm_patients`                                        |
| DMG     | Date of birth, gender | `pm_patients`                                        |
| REF\*6P | Group number          | `pm_insurance_policies.group_number`                 |
| EQ      | Service type          | `SQ` (psychiatric), `MH` (mental health), `A4` (SUD) |

### 271 Response Parsing

| Segment   | Description       | Target                                             |
| --------- | ----------------- | -------------------------------------------------- |
| EB\*1     | Active coverage   | `pm_eligibility_checks.is_eligible`                |
| EB\*6     | Deductible        | `pm_eligibility_checks.benefit_details.deductible` |
| EB\*A/B/C | Copay/Coinsurance | `pm_eligibility_checks.benefit_details.copay`      |
| EB\*F     | Limitation        | Visit/unit limits for BH services                  |
| MSG       | Free-form message | `pm_eligibility_checks.notes`                      |

***

## Clearinghouse Abstraction Layer (PM-15)

For **recommended vendor implementation order** (Waystar first) and **claim-line-level** requirements, see the supplementary spec: [PM-15: Clearinghouse Vendor Selection & Waystar-First Integration](../../../specs/pm/decisions/PM-15-clearinghouse-vendor-selection-waystar-integration.md).

### Adapter Interface

```typescript theme={null}
interface ClearinghouseAdapter {
  // Identity
  readonly providerId: string;
  readonly providerName: string;

  // Submission
  submitClaim(claim: X12Envelope<Claim837P | Claim837I>): Promise<SubmissionResult>;
  checkEligibility(request: X12Envelope<Eligibility270>): Promise<EligibilityResult>;
  submitPriorAuth(request: X12Envelope<Auth278>): Promise<AuthResult>;

  // Retrieval
  fetchRemittance(dateRange: DateRange): Promise<ERA835[]>;
  checkClaimStatus(claimId: string): Promise<ClaimStatus277>;

  // Configuration
  validateCredentials(): Promise<boolean>;
  getSubmissionWindow(): { start: string; end: string };
}

// Implementations
class AvailityAdapter implements ClearinghouseAdapter { ... }
class ChangeHealthcareAdapter implements ClearinghouseAdapter { ... }
class TrizettoAdapter implements ClearinghouseAdapter { ... }
```

### Configuration Table

> **AUTHORITATIVE SOURCE:** The schema for `pm_clearinghouse_config` is defined in `specs/pm/specs/PM-15-clearinghouse-integration.md`. The definition below is superseded by the spec. Implementers MUST use the spec definition which includes `deleted_at`, `site_id`, `custom_fields`, `username_vault_ref`, and `connection_type`.

```sql theme={null}
-- See PM-15 Spec for authoritative DDL
-- specs/pm/specs/PM-15-clearinghouse-integration.md
```

***

## Trading Partner Testing

Each payer/clearinghouse combination requires:

1. **Enrollment:** Register sender ID with clearinghouse
2. **Companion Guide Review:** Payer-specific segment requirements
3. **Test Submission:** Submit test 837P, verify acceptance
4. **ERA Testing:** Verify 835 parsing with payer-specific CARC/RARC codes
5. **Go-Live:** Switch from test to production mode

Store enrollment status in `pm_clearinghouse_config.custom_fields.trading_partner_status`.

***

## References

* **PM-15 Vendor selection:** [PM-15: Clearinghouse Vendor Selection & Waystar-First Integration](../../../specs/pm/decisions/PM-15-clearinghouse-vendor-selection-waystar-integration.md) — Waystar-first order, line-level requirements, Waystar connection details.