EDI Integration: How X12 Documents Move Between Trading Partners, and When to Use EDI vs API

EDI Integration: How X12 Documents Move Between Trading Partners, and When to Use EDI vs API

14 Nov, 2026
13 min read

A large retailer, a freight broker or a health plan has told your team to "connect by EDI." They don't want a portal upload or a PDF in an email. They want your orders, load updates or claims to arrive as standard documents their systems can read without anyone retyping them, and they want their own documents to land in your systems the same way. EDI integration is the software in between: it turns records in your TMS, WMS, ERP or billing system into those documents, sends them to each partner, and turns what comes back into records again.

None of this is new technology, and that's partly why it gets underestimated. Every partner uses the standard a little differently, and a document that fails quietly can hold up a load or a payment until someone notices. This guide covers the X12 documents you're likely to meet in logistics and healthcare, how they travel, what a project involves, and where an API is the better fit.

What is EDI integration?

EDI integration connects your own systems, such as a TMS, WMS, ERP or practice management system, to your trading partners so that business documents move as standard electronic messages. In the US those messages are usually X12. Your data is mapped into each partner's format, sent over an agreed channel such as AS2, and acknowledged by the receiver.

What is X12, and what is a transaction set?

X12 is the standards body whose specifications define the documents most US companies exchange by EDI, and each document type in its catalog is a numbered transaction set: 204 for a load tender, 837 for a health care claim, and so on. X12 calls itself "an ANSI-accredited, consensus-based, non-profit organization" and says its standards cover ordering, shipping, invoicing and payment, with "more than 320 transaction standards available for use." No single company uses more than a fraction of them. When people say "X12 EDI," they mean this family of documents in the format X12 defines.

Transaction sets rarely travel one at a time. X12's description of its 997 acknowledgement notes that transaction sets "are grouped in functional groups," which is why EDI traffic often arrives in batches and why one acknowledgement can report on several documents at once.

The standard is broad on purpose. Each partner picks the version it supports, uses a subset of the segments and codes, and writes its own rules down in an implementation guide. That guide is what your developers will work from day to day. X12 is the American standard; partners abroad often use UN/EDIFACT instead (the FAQ covers the difference).

Which X12 documents will you see?

That depends on your industry, and in practice a team works with the few transaction sets its partners actually send and expect. The table covers the ones you're likely to meet in transport, warehousing, retail supply chains and US healthcare, plus the two acknowledgements that apply to all of them. The descriptions are shortened from X12's own transaction set summaries.

Code X12 name Industry What it carries (per X12, shortened)
204 Motor Carrier Load Tender Transport A shipper offers a full truckload to a carrier, with schedule, equipment and shipping instructions
990 Response to a Load Tender Transport The carrier's response to a 204
214 Transportation Carrier Shipment Status Message Transport Shipment status: dates, times, locations, route and identifying numbers
210 Motor Carrier Freight Details and Invoice Transport Charges for the carrier's services; used as the freight invoice
940 Warehouse Shipping Order Warehousing The depositor tells the warehouse to ship, confirm, change or cancel an order
945 Warehouse Shipping Advice Warehousing The warehouse confirms the shipment was made; ordered and shipped quantities are reconciled
850 Purchase Order Retail, distribution Placing a purchase order (not changes or acknowledgements)
856 Ship Notice/Manifest Retail, distribution Contents and configuration of a shipment
837 Health Care Claim Healthcare Claim billing and encounter information from providers to payers, directly or via clearinghouses
835 Health Care Claim Payment/Advice Healthcare Payment and/or remittance advice (EOB) from insurer to provider
270/271 Eligibility, Coverage or Benefit Inquiry / Information Healthcare An eligibility, coverage or benefit question and its answer
276/277 Health Care Claim Status Request / Information Status Notification Healthcare A claim status question and its answer
997 Functional Acknowledgment All The result of the syntax check on received documents
999 Implementation Acknowledgment All A syntax and relational check against the implemented subset

Two limits in X12's wording matter before you scope anything. The 204 is for full truckload: X12 says it isn't meant for a less-than-truckload bill of lading, pickup notification or manifest, so an LTL partner may expect other documents. And the 850 only places an order. X12 says it "should not be used to convey purchase order changes or purchase order acknowledgment information," so a retail partner that changes or confirms orders will need more than one transaction set from you.

How does a load move by EDI?

A truckload moves through four business documents, from the tender to the invoice, and an acknowledgement should come back for each one.

  1. The shipper sends an EDI 204 load tender with the schedule, equipment and shipping instructions for the load.
  2. The carrier's system returns a 997. That means the 204 arrived and passed the syntax check, and nothing more: the carrier hasn't said yet whether it wants the load.
  3. The carrier accepts or declines with a 990, the response to the load tender.
  4. While the truck is on the road, the carrier sends EDI 214 status messages with dates, times and locations, and the shipper's system matches each one to the load by its reference numbers.
  5. After delivery the carrier bills for the move with a 210 freight invoice.

Most trouble in this flow is quiet. A 997 that never comes back usually means the partner didn't receive the document or couldn't parse it, and unless your system expects that acknowledgement and raises an alert when it's overdue, the first sign may be a load nobody covered. A 214 can also arrive for a shipment your system doesn't recognize, often because the reference the carrier sent back doesn't match the one you sent out. It should wait in a queue where someone can match it by hand. And a partner may send the same 204 or 214 twice after a timeout, so the integration has to recognize a document it has already processed and skip it.

In the logistics software with EDI built in that we build, we monitor each partner connection and track the 997 or 999 that should come back for every document. A document that bounces or comes in garbled waits in a queue where your team can fix it and send it again.

What about healthcare: 837, 835 and HIPAA?

For the transactions HIPAA covers, X12 isn't optional. HIPAA required HHS to set national standards for electronic transactions, and CMS states that "ASC X12 Version 5010 is the adopted standard format for transactions, except those with retail pharmacies," which use NCPDP standards instead. CMS is also clear about who this reaches: "Any provider who accepts payment from any health plan or other insurance company must comply with HIPAA if they conduct the adopted transactions electronically."

The claim itself is the EDI 837. X12 describes it as carrying claim billing and encounter information "from providers of health care services to payers, either directly or via intermediary billers and claims clearinghouses," and the CMS table lists it for institutional, professional and dental claims. Payment comes back as an 835, which carries the payment, the Explanation of Benefits remittance advice, or both, from the insurer to the provider. Around those two sit the 270/271 pair for eligibility and benefit questions and the 276/277 pair for claim status.

Most of the engineering sits between those documents. A billing or practice management system has to keep the identifiers it sent in each 837, because that's how each 835 gets matched to the claims it pays, and a denied or partly paid line needs to reach a person instead of being posted without anyone looking at it. We build revenue cycle apps and integrations for healthcare, and much of that work is X12 traffic with clearinghouses and payers.

Clinical data is a separate track. HL7 International is the standards body behind HL7 v2, FHIR and CDA, so a health platform often runs HL7 or FHIR for patient records and X12 for billing. Our guide to how HL7 and X12 divide the work covers that comparison.

How do EDI files travel? AS2, SFTP and VANs

The X12 document is the content, and how it travels is agreed separately with each partner. You'll usually settle on one of three channels.

AS2 sends EDI over HTTP. RFC 4130, the IETF specification, covers exchanging structured business data securely over HTTP, names both ANSI X12 and UN/EDIFACT as the formats it carries, and lists "data confidentiality, data integrity/authenticity, non-repudiation of origin, and non-repudiation of receipt over HTTP" as its security services. The sender can ask the receiver to return a Message Disposition Notification, or MDN, and to sign it, which is how AS2 gives you an authenticated receipt. The RFC is plain about what an MDN is: "A MDN is a receipt."

SFTP is simpler. Each side drops files into an agreed folder on a server and collects the files waiting for it. The transfer has no receipt of its own, so the 997 is the first confirmation you'll get.

A VAN (value-added network) is a third party that routes EDI documents between partners' electronic mailboxes.

Whichever channel you use, keep three kinds of confirmation apart, because a connection can pass one and fail the next. An AS2 MDN tells you the message was received. A 997 tells you the transaction sets passed X12's syntax check, and X12 says outright that the standard "does not cover the semantic meaning of the information encoded in the transaction sets." Business acceptance comes later and in business terms: a 990 that accepts the load, or a 277 that reports where a claim stands. A dashboard that only watches the first two can look healthy while a partner is turning documents down.

What does an EDI integration project involve?

Mostly mapping and testing, one partner at a time. Setting up the connection is the smaller job. Most of the hours go into making each partner's version of a document line up with your data model, then proving it does before real traffic starts.

  1. List each partner, the transaction sets you'll exchange with them in each direction, and the implementation guide for each.
  2. Map each partner's segments to your data model. Keep one map per partner, versioned and covered by tests, because partners revise their guides and a change for one partner shouldn't break the others.
  3. Agree on the transport with each partner (AS2, SFTP or a VAN) and set up the certificates or credentials it needs.
  4. Exchange test documents with the partner and get their sign-off before production traffic starts.
  5. Track the acknowledgement for every document you send, and alert when one is late or reports an error.
  6. Give operations staff a queue where failed or unmatched documents wait with the reason attached, so they can fix the data and resend without calling a developer.
  7. Add the next partner. The transport setup and the queue carry over, but the map usually doesn't, so treat each new partner as a small project of its own.

Our EDI and API integration work covers the SOAP, EDI and file-based links that older systems still depend on, and we treat them as first-class integration work because they still carry a lot of critical business workflows.

EDI vs API: which should you use?

Usually both. Your partners decide where EDI is required, and for HIPAA-covered healthcare transactions the rules decide it for them. Between your own systems, or with a partner that offers an API and doesn't ask for EDI, the choice is yours, and an API is usually easier to build and to change.

The rows below are our own analysis, built on the standards cited earlier.

EDI (X12) API
Format Standard documents defined by X12, narrowed by each partner's implementation guide A schema set by whoever owns the API
Who sets it The standards body, then the partner The API provider
Timing Documents sent one at a time or in batches; replies come back as separate documents Request and response, often in real time
Confirmation With AS2, an MDN receipt; then a 997 or 999 An HTTP status code in the response
Adding a partner A new map and a test cycle for each partner One integration per API, which every caller shares
Typical use Load tenders, purchase orders, ship notices, HIPAA claims App-to-app data, carrier rates and labels, live lookups

The pattern we'd recommend in most cases is EDI at the edge and APIs inside. The EDI layer translates partner documents into internal API calls or events, so the rest of your systems never parse X12, and if a partner later moves to an API, only the edge changes.

An API wins outright when you need an answer inside the same request. A rate quote or a shipping label can't wait for a separate reply document, which is why carriers that take EDI tenders often offer carrier APIs for rates and labels as well. If you want the API side explained from the ground up, start with our guide to what API integration means.

FAQ

What is the difference between a 997 and a 999?

In X12's words, the 997 reports "the results of the syntactical analysis" of the documents received, while the 999 reports "syntactical and relational analysis" based on "a full or implemented subset" of the transaction sets. So a 999 can also reject a well-formed document that breaks the subset's rules. Your partner's guide names the one they send.

Is EDI being replaced by APIs?

Not in a way you can plan around. X12 also publishes XML schemas, so the standard isn't tied to one file format, but that doesn't change what your partners send. As long as a payer or a large retailer sends X12, you'll need to receive it and reply in X12, whatever your own systems use internally.

What is an EDI implementation guide?

It's a partner's rulebook on top of the X12 standard: which version they use, which transaction sets and segments they send, which fields they require, which code values they accept and how testing works. Ask for every guide before you scope the work, because the guides, more than the transaction set names, decide how much mapping there will be.

Do we need a VAN?

Only if a partner requires one, or if the number of connections makes it worth paying for. AS2 and SFTP connect you to a partner directly. A VAN puts a third party in the middle, so you keep one connection instead of one per partner, in exchange for its fees and one more place where a document can stall.

Is X12 the same as EDIFACT?

No. They cover many of the same business documents, but UN/EDIFACT is the United Nations standard, with its own message names, structure and code lists, so an X12 map can't read an EDIFACT file. If some of your partners are overseas, plan for both. We can also work in EDIFACT for partners overseas who use it.

Planning an EDI connection

If a partner has asked you to connect by EDI, or an existing connection keeps failing without anyone noticing, a discovery call is a sensible first step. We'll go through your partners, the documents and guides involved, and how your systems should send, receive and track them.

Buttons: "Book a Technical Discovery Call" → /contact · "Get a Project Estimate" → /project-estimate

Tags:

Share:

Saqib Tasneem
Founder & CEO, Vortex Web Innovate

Saqib Tasneem

Saqib Tasneem is the founder and CEO of Vortex Web Innovate, a software and web development company in Easthampton, Massachusetts. He has more than 10 years of experience across technology, taxation, accounting, retail operations and business development, and leads the delivery of custom software, ERP and enterprise systems, web and mobile apps, cloud and DevOps, and AI solutions. He holds an MBA from Government College University, Lahore.

Working on this yourself?

Tell us what you're trying to build or fix. If it isn't a fit, we'll say so on the first call.

Book a Technical Discovery Call

Related work

FHIR Integration for Clinical Data: Access Policies and a Local Message Queue

A FHIR-based application backend with record access policies, version history and links to existing clinical systems.

Read the case study

Long-Running Workflow Automation and API Integration

A visual workflow platform that saves execution progress, waits for external input and resumes work from its recorded state.

Read the case study

Payment Orchestration: Provider Routing with Recoverable Follow-Up Work

A shared payment interface with provider selection, status tracking and scheduled recovery work.

Read the case study
Industries

Industries we serve

Healthcare & Life Sciences

EHR integration, HL7/FHIR, telehealth, clinical workflow, PHI handling

Explore this industry

Financial Services & FinTech

Payments, reconciliation, risk models, audit trails

Explore this industry

Something on your own site not working?

Tell us what you're trying to build or fix. We'll put someone on the call who can actually assess it - and if it's not a fit, we'll tell you on the first call rather than the third.