Build a UB-04 (CMS-1450) to 837I Institutional Claim API (2026 Blueprint)
If a client tells you:
"We need to submit UB-04 (CMS-1450) institutional claims electronically via 837I, and we want an API for it. We need it ASAP."
They are really asking for a claims pipeline: capture UB-04-equivalent data, generate a compliant X12 837I, transmit it to a clearinghouse/payer, then track the acknowledgments until the claim is accepted for adjudication.
This post breaks down how we build that system in a way that is practical, testable, and production-ready.
Want us to build this for you?
Tirnav Solutions implements UB-04 to 837I generation, clearinghouse connectivity, and 999/277CA acknowledgment tracking with secure audit logs and operational dashboards.
UB-04 vs 837I (simple explanation)
- UB-04 (CMS-1450) is the institutional claim form (how hospitals and facilities represent services for billing).
- 837I is the HIPAA-mandated electronic equivalent (X12 EDI) used to submit the same information digitally.
An "837I API" typically means: your internal systems send JSON, and the platform produces and submits a correctly structured 837I file (and tracks what happened next).
What "done" looks like (the deliverables)
To satisfy the requirement end-to-end, we build:
- Institutional Claim API (JSON in, claim status out)
- Validation engine (required fields + code sets + structural checks)
- 837I generator (X12 5010 005010X223A3 formatting + envelopes)
- Transport layer (SFTP/AS2/HTTPS depending on clearinghouse/payer)
- Acknowledgment processing
- 999 (syntax/implementation validation)
- 277CA (claim acknowledgment: accepted/rejected with reasons)
- Operational tooling
- idempotent re-submit
- retries with backoff
- audit trail + raw EDI storage
- dashboards and/or webhooks
Reference architecture (how the system is wired)
Key principle: the AI/chatbot is optional in this domain - the real value is correct mapping, validation, and acknowledgment-driven status tracking.
The hard parts (and how we solve them)
1) Capturing UB-04 data as a clean JSON contract
We do not send a "PDF-shaped" payload. We define a normalized claim schema that can be produced by:
- an EHR export
- a billing UI
- an intake workflow
- an integration from a client system
Example (simplified):
1{ 2 "clientClaimId": "CLM-1000123", 3 "billingProvider": { "npi": "1234567893", "name": "ACME HOSPITAL" }, 4 "payer": { "payerId": "01234", "name": "SAMPLE HEALTH PLAN" }, 5 "subscriber": { "memberId": "W123456789", "dob": "1980-01-01" }, 6 "patient": { "relationship": "self", "dob": "1980-01-01" }, 7 "diagnoses": ["J18.9", "R06.02"], 8 "revenueLines": [ 9 { "revenueCode": "0300", "hcpcs": "99223", "units": 1, "chargeAmount": 600.0 } 10 ] 11}
Then we map that schema into the 837I loops/segments required by the implementation guide and the trading partner.
2) 837I mapping (UB-04 form locators to X12 loops/segments)
Institutional claims include facility-specific details that must be represented correctly, such as:
- Type of bill, admission/discharge context
- Patient discharge status
- Attending / operating / rendering providers (as applicable)
- Condition codes, occurrence codes, value codes
- Revenue codes with HCPCS where required (SV2 service lines)
We implement mapping as versioned rules, because requirements differ by:
- clearinghouse vs direct payer submission
- Medicare/Medicaid vs commercial plans
- state-specific or payer-specific companion guides
3) Validation that prevents avoidable rejections
We validate at multiple layers before transmission:
- Schema validation (missing fields, invalid types, date rules)
- Code set validation (ICD-10, revenue codes, HCPCS/modifiers if used)
- X12 structure validation (required loops/segments, element formats)
- Trading partner rules (payer-specific constraints from companion guides)
This reduces the most expensive failure mode: "it transmitted fine, but got rejected."
4) Transport: clearinghouse/payer connectivity
Most 837 traffic moves through a clearinghouse. Connectivity is usually one of:
- SFTP batch submission (common, simple, reliable)
- AS2 (strong non-repudiation, common in EDI)
- HTTPS/API where supported by the trading partner
We design the transport as a pluggable layer so you can switch partners without rewriting the core mapping logic.
5) Acknowledgments (999 and 277CA) as the source of truth
Sending an 837I is not the finish line. The system must ingest and interpret acknowledgments:
- 999 tells you whether the file passed implementation/syntax checks.
- 277CA tells you whether each claim was accepted or rejected (and why).
We store both the raw EDI and the parsed results, then expose statuses like:
- created
- validated
- submitted
- acknowledged_999
- accepted_277ca / rejected_277ca
That makes the API usable by real operations teams.
837I sample snippet (more detailed)
1ISA*00* *00* *ZZ*SUBMITTERSENDER*ZZ*RECEIVERID *260225*1200*^*00501*000000905*1*T*:~ 2GS*HC*SUBMITTERSENDER*RECEIVERID*20260225*1200*1*X*005010X223A3~ 3ST*837*0001*005010X223A3~ 4BHT*0019*00*CLM1000123*20260225*1200*CH~ 5NM1*41*2*SUBMITTER NAME*****46*12345~ 6PER*IC*EDI SUPPORT*TE*5551234567*EM*[email protected]~ 7NM1*40*2*RECEIVER NAME*****46*PAYERID~ 8HL*1**20*1~ 9PRV*BI*PXC*282N00000X~ 10NM1*85*2*ACME HOSPITAL*****XX*1234567893~ 11N3*123 MAIN ST~ 12N4*ANYTOWN*CA*90210~ 13REF*EI*123456789~ 14NM1*87*2*ACME HOSPITAL PAY-TO*****XX*1234567893~ 15N3*PO BOX 100~ 16N4*ANYTOWN*CA*90210~ 17HL*2*1*22*0~ 18SBR*P*18*******CI~ 19NM1*IL*1*DOE*JANE****MI*W123456789~ 20N3*456 OAK AVE~ 21N4*ANYTOWN*CA*90210~ 22DMG*D8*19800101*F~ 23NM1*PR*2*SAMPLE HEALTH PLAN*****PI*01234~ 24CLM*CLM1000123*750.00***21:B:1*Y*A*Y*Y~ 25DTP*434*RD8*20260220-20260221~ 26DTP*435*D8*20260220~ 27DTP*096*D8*20260221~ 28CL1*1*1*01~ 29HI*ABK:J189*ABF:R0602~ 30NM1*71*1*SMITH*JOHN****XX*1234567890~ 31PRV*AT*PXC*207Q00000X~ 32LX*1~ 33SV2*0300*HC:99223*600.00*UN*1***1~ 34DTP*472*D8*20260220~ 35REF*6R*1~ 36LX*2~ 37SV2*0250*HC:93010*150.00*UN*1***1~ 38DTP*472*D8*20260220~ 39REF*6R*2~ 40SE*38*0001~ 41GE*1*1~ 42IEA*1*000000905~
Real production files include additional loops/segments (and payer-specific rules); this example is illustrative and uses dummy identifiers.
Quick reading guide:
- ISA/GS and GE/IEA: interchange + functional envelopes (control numbers must match)
- ST/SE: transaction boundaries (and SE01 segment count)
- NM141 and NM140: submitter and receiver (clearinghouse/payer)
- HL1: billing provider hierarchy; HL2: subscriber hierarchy
- CLM, DTP, CL1, HI: claim header + key dates + institutional codes + diagnoses
- LX, SV2, DTP: revenue/service lines and service dates
Segment cheat sheet (from the sample)
| Segment | Description | Meaning |
|---|---|---|
| ISA | Interchange Control Header | Marks the beginning of the interchange and defines sender/receiver IDs, date/time, separators, and control numbers. |
| GS | Functional Group Header | Groups related transaction sets (health care claims) and provides group control number and version. |
| ST | Transaction Set Header | Indicates the start of the 837I transaction set and assigns a transaction control number. |
| BHT | Beginning of Hierarchical Transaction | Declares the file purpose (original), reference ID, and timestamp for the claim transmission. |
| NM1 | Individual/Organizational Name | Identifies key entities (submitter, receiver, provider, subscriber, payer) with name and an identifier (e.g., NPI/member ID/payer ID). |
| PER | Administrative Contact | Provides contact details for EDI questions (phone/email). |
| HL | Hierarchical Level | Builds the claim hierarchy (billing provider → subscriber → patient as applicable) using parent/child relationships. |
| PRV | Provider Information | Sends provider role/taxonomy information (e.g., billing provider taxonomy). |
| N3 | Address Information | Street address for the entity currently being described. |
| N4 | Geographic Location | City, state, and ZIP/postal code for the entity address. |
| REF | Reference Identification | Additional identifiers such as Tax ID (EI) or service line control numbers (6R). |
| SBR | Subscriber Information | Payer responsibility (primary/secondary), relationship to subscriber, and claim filing indicator (e.g., commercial). |
| DMG | Demographic Information | Demographics such as date of birth and gender. |
| CLM | Claim Information | Claim identifier, total charge amount, and institutional claim/facility/frequency indicators. |
| DTP | Date/Time/Period | Dates with qualifiers (statement period, admission/discharge, and service dates such as 472). |
| CL1 | Institutional Claim Code | Institutional-specific codes like admission type/source and patient status (disposition). |
| HI | Health Care Information Codes | Diagnoses (principal and additional), typically ICD-10-CM in institutional claims. |
| LX | Transaction Set Line Number | Starts a revenue/service line and establishes the line sequence number. |
| SV2 | Institutional Service Line | Revenue code line details: revenue code, procedure (when required), charge amount, units, and related qualifiers. |
| SE | Transaction Set Trailer | Ends the transaction set and includes the segment count plus the same control number as ST. |
| GE | Functional Group Trailer | Ends the functional group and matches the control number from GS. |
| IEA | Interchange Control Trailer | Ends the interchange and matches the control number from ISA. |
Implementation roadmap (ASAP but still safe)
- Week 1: discovery + trading partner setup
- confirm clearinghouse/payer connectivity method
- collect submitter/receiver IDs, test credentials, companion guide rules
- finalize the JSON contract for UB-04-equivalent data
- Weeks 2-3: mapping + 837I generation
- core loops/segments for your claim types
- envelope control numbers + idempotency
- validation rules
- Weeks 3-5: transmission + acknowledgments
- submit to test environment
- ingest 999 and 277CA
- build claim status API / webhooks
- Weeks 6-8: production hardening
- edge cases, retries, reconciliation jobs
- audit logging + monitoring
- security review and rollout playbook
Timeline and cost (ballpark)
Actual numbers depend on scope (number of payers, clearinghouse, claim types, and whether you also need 835/ERA auto-posting). For planning, these are realistic ranges:
| Component | Cost Estimate |
|---|---|
| Discovery + mapping workshop | $2,000 - $5,000 |
| 837I generation + validation | $12,000 - $25,000 |
| Clearinghouse connectivity (SFTP/AS2/HTTPS) | $8,000 - $18,000 |
| 999 + 277CA ingestion and status API | $6,000 - $14,000 |
| Production hardening + monitoring | $5,000 - $12,000 |
| Total (typical) | $33,000 - $74,000+ |
Timeline:
- MVP (3-5 weeks): Generate and submit 837I + basic ack tracking
- Production (6-8+ weeks): Full validation depth, retries, dashboards, and stability
What we need from you to start (fast)
If you want to move ASAP, these inputs remove days of back-and-forth:
- Clearinghouse name (or target payer) and preferred transport method (SFTP/AS2/API)
- Your submitter ID / sender ID and target receiver IDs (if already assigned)
- A few real (de-identified) claim examples you want to support first
- Your expected claim volume (daily/weekly) and SLA expectations
- Whether you also need 835 ERA ingestion in the same project
Final thought
Building "UB-04 via 837I API" is less about generating a text file and more about building a reliable claims workflow that operations teams can trust: validate before you send, and drive status from acknowledgments after you send.
If you want a team to implement this quickly and correctly, we can scope it in a short call and share a fixed timeline and quote based on your trading partner requirements.
