Welcome & X12 envelope refresher

You are reading this because you are an EDI operations person — a clearinghouse coordinator, payer-relationship manager, or EDI analyst — and you need to understand the platform's gateway in enough depth to do the job: onboarding partners, watching daily traffic, debugging the rejection that came in this morning.

This chapter exists to make sure we are speaking the same dialect of X12 before you read the rest of the manual.

The envelope, top-down

Three nesting layers — interchange, functional group, transaction — each with header / trailer pairs and a control number that must match front-to-back. The header / trailer / control number invariant is the single most useful debugging fact about EDI: when something is wrong with the envelope, it is almost always one of these three pairs.

A real envelope

ISA*00*          *00*          *ZZ*ACME           *ZZ*PARTNER        *250131*1234*^*00501*000000123*1*P*:~
GS*HC*ACME*PARTNER*20250131*1234*1*X*005010X222A1~
ST*837*0001*005010X222A1~
BHT*0019*00*REF12345*20250131*1234*CH~
[ ... loops and segments ... ]
SE*128*0001~
GE*1*1~
IEA*1*000000123~

The 16 ISA elements are fixed-width (the only fixed-width segment in X12). Notable elements:

Position	Value	Meaning
ISA01-04	00 / 00	Authorization / security qualifier + info (almost never used).
ISA05-08	ZZ / ACME / ZZ / PARTNER	Sender qualifier + ID + receiver qualifier + ID.
ISA09-10	250131 / 1234	Date YYMMDD + time HHMM.
ISA11	^	Repetition separator.
ISA12	00501	Standards version (5010).
ISA13	000000123	Interchange control number — must match IEA02.
ISA14	1	Acknowledgment requested.
ISA15	P	Usage indicator — P production, T test.
ISA16	:	Component separator.

The ~ is the segment terminator; the * is the element separator; the : is the component separator. Every X12 file declares its own — they are usually *, :, and ~ but a partner can pick differently in ISA11 / ISA16.

Loops, segments, elements

Term	Example
Segment	NM1*85*2*ACME PROVIDER*****XX*9876543210~ (one segment, 9 elements separated by *).
Element	NM103 = ACME PROVIDER (the third element of an NM1, position 03).
Composite element	SV1-01 = HC:99213:HQ — a composite of three sub-elements. Position notation: SV101:1 is the first sub-element.
Loop	Loop 2400 — the service-line loop in 837. Holds LX, SV1, DTP, more. Loops cluster related segments.

The implementation convention reference (005010X222A1, 005010X221A1, …) defines exactly which loops and segments are required, optional, prohibited, and how many times each can repeat.

Acknowledgments at a glance

Three layers, three different questions:

Ack	Question
TA1	Did the envelope itself parse?
999	Did the 837's loops and segments parse?
277CA	Did the payer accept individual claims into adjudication?

A 277CA acceptance is not payment — adjudication can still deny later. We have a separate transaction (the 835) for actual payment.

For the full code lists, see 9.3 — Acknowledgment codes.

What the gateway does

The platform's edi-gateway service:

1. Builds outbound EDI (generate837P(), generate270(), generate278(), generate276()).
2. Parses inbound EDI (parseRemittance835(), parseEligibility271(), parseAcknowledgement999(), etc.).
3. Manages transport (SFTP poll, AS2 push/pull, real-time HTTP).
4. Applies companion guides at generate-time and validates inbound shapes.
5. Allocates control numbers — the strictly-monotonic ISA13 / GS06 / ST02 sequence.
6. Tracks every transaction in billing.edi_transaction so you can find any envelope by ISA13.

The platform's edi-app is the operator's web UI for everything above — /transactions, /partners, /companion-guides, /routing, /batches, /replay, /responses.

Where to go next

Pick the page that matches the work in front of you:

Doing	Start at
Onboarding a new partner	2.1 — Onboard a new trading partner
Authoring a companion guide	7.1 — The companion guide editor
Debugging a stuck claim	3.4 — Acknowledgments and 8.3 — Transactions search & detail
Daily ops triage	8.1 — Daily monitoring
Reading a 277CA / 835 / 271 you've never seen	9.2 — Segment cheat-sheet and 9.3 — Acknowledgment codes

Next

1.2 — Gateway architecture for EDI staff