SignalEDI

Integration guide

API EDI integration: connect your systems to trading partners

API EDI integration connects your own software to trading partners through an API, while the partner keeps receiving the standard EDI documents (such as X12 850 purchase orders) over the connection it requires. Your application sends and receives JSON over REST. A platform in the middle validates each document, translates it to EDI, delivers it, and returns the partner's acknowledgement to you as a signed webhook. You build against one API instead of one custom integration per partner.
JSON and REST inStandard EDI outSigned acknowledgement webhooks
Start free trialEDI API reference

Verify before you start

HIPAA safeguards, BAA availableAudit trailsSOC 2

What is API EDI integration?

API EDI integration is the practice of using web APIs to drive EDI. It sits between two worlds. Your systems (an ERP, a warehouse system, an online store, a billing tool) already speak JSON over HTTPS. Your trading partners (retailers, payers, distributors) speak EDI: standardized documents sent over AS2, SFTP or, increasingly, an API.

The integration layer does the translation in both directions, so neither side changes how it works. This is the hybrid model discussed in EDI vs API: APIs for your stack, EDI where the partner mandates it.

If you only want the API reference, go to the EDI API page. If you want the concept in one page, read the EDI API guide. This page is about how the pieces fit together and how to build it.

How API EDI integration works: the 6-step flow

This is an outbound document, for example an advance ship notice.

  1. Your application creates the document as JSON. The fields come from your own system: order number, ship-to, items, quantities.
  2. It calls the API. A POST to /v1/documents/outbound with your API key and an Idempotency-Key header, so a retry never sends a duplicate.
  3. The platform validates and maps. SignalEDI checks the payload, applies the document and partner mapping, and returns field-level errors immediately if something is wrong.
  4. The document is delivered. It goes to the partner over the connection the partner requires (AS2, SFTP or API).
  5. The partner acknowledges. The partner's system returns a functional acknowledgement (997, 999 or TA1), which SignalEDI records.
  6. You get the result. A signed webhook (document.acknowledgement_received.v1) reaches your endpoint, and the receipt at GET /v1/documents/{documentId} shows each stage. A terminal failure sends document.delivery_failed.v1.

Inbound works in reverse. A partner's EDI document is admitted, parsed into structured data, and your application reads it through the API (GET /v1/documents/{documentId}/payload offers raw, structured, typed or mapped views).

Four API EDI integration patterns

Pattern How it works Best for Watch for
1. JSON to EDI through a platform Your app sends JSON; the platform emits X12 and delivers it; acknowledgements return as webhooks Teams with developers who want one API for many partners Still validate against each partner's own rules
2. Direct partner API The partner exposes its own REST API and you call it Digital-native partners, real-time inventory or status Each partner API is a separate build and version to maintain
3. File bridge (SFTP) Drop X12 or EDIFACT files in a per-tenant inbox and collect results and acknowledgements from an outbox ERPs and systems that only emit files Polling and retries; status is per batch
4. Event-driven webhooks Your system reacts to signed lifecycle events instead of polling Anything that must act on acknowledgements or failures Verify signatures and make handlers idempotent

Most real programs mix them: pattern 1 for the mandated documents, pattern 4 for status, and pattern 2 where a partner offers an API for inventory or order status. The partner's vendor guide decides which pattern each document uses.

A 5-step implementation

  1. Get a key and check the document types. Create a free API key through the developer sign-up. GET /v1/document-types (a public registry) lists the document types and what raw, typed and mapped support each has.
  2. Map your data. Build the typed JSON payload from your system's fields. The JSON to X12 mapping guide and the 850 purchase order guide show the shape.
  3. Send in Lab. POST /v1/documents/outbound with "environment": "LAB". A good result is HTTP 202 with status: validated and partnerContacted: false. Fix any fieldErrors before moving on.
  4. Handle acknowledgements. Register an HTTPS webhook endpoint, verify the X-SignalEDI-Signature header, and use X-SignalEDI-Delivery-ID to process each event once. See signed webhooks and 997/999 acknowledgements.
  5. Certify, then go live. Switch to a Certification key with the partner binding and test the real route; when the partner approves, promote to Production. The go-live checklist covers it. Each key addresses one lane only, so test traffic cannot reach production.

The developer quickstart puts steps 1 to 3 into runnable code.

Common mistakes

  • Treating a 202 as delivered. A 202 means the document was admitted. Delivery and the partner's acknowledgement come later; read the receipt or wait for the webhook.
  • No idempotency. Network retries without an Idempotency-Key can create duplicates. Always send one.
  • Ignoring the acknowledgement. A rejected 997 or 999 means the partner did not accept the file. Read the reason and fix the source data.
  • Testing only against the standard. Most rejections come from the partner's own rules. Build test cases from the partner's vendor guide, not just the X12 spec. The EDI validator and test lab help with the first passes.
  • Expecting an API to end the partner process. Partners control their own testing and approval calendars. Your side moves fast; their sign-off sets the date.

When to choose which route

If the partner says Use
"We only accept EDI" Pattern 1, with webhooks (pattern 4) for status
"We have a REST API" Pattern 2 for that data, plus pattern 1 for any mandated EDI documents
"Send us files" and your system only exports files Pattern 3
Nothing yet Ask for the written requirement first; the trading partner library lists many

What it costs

Two meters apply and they are independent. Business EDI plans (Seasonal $99, Starter $199, Growth $999, Enterprise $1999 per month) are on the pricing page. Developer API usage is separate: 5,000 free calls a month, then $0.0015 per call, where a call is one parse or one validate request; see developer API pricing. A 30-day free trial with no credit card lets you evaluate both.

Where to go next

Evaluate without a sales call

Most buyers are not ready to buy on the first visit. Start with a free tool or requirement check — then trial when you are ready.

API EDI integration FAQ

What is API EDI integration?

API EDI integration connects your software to trading partners through a web API while the partner keeps receiving standard EDI documents. Your application sends and receives JSON, and a platform validates, translates and delivers the documents and returns acknowledgements.

Do I still need EDI if I use an API?

Often yes. Many retailers and payers mandate EDI documents such as the 850, 856 and 810 over AS2 or SFTP, and an API alone does not meet that mandate. An integration layer lets your side stay API-first while the partner receives EDI.

How does an API integration handle EDI acknowledgements?

When the partner returns a functional acknowledgement (997, 999 or TA1), the platform records it and sends a signed webhook to your endpoint. You can also read the document receipt through the API to see each stage.

What is the difference between an EDI API and API EDI integration?

An EDI API is the interface itself: the endpoints, authentication and pricing. API EDI integration is the wider practice of connecting your systems and partners through it, including patterns, testing and go-live. Use the EDI API page for reference and this page for design.

Can I test an API EDI integration without a trading partner?

Yes. A Lab key validates your payload and mapping in your own account without contacting a partner. Move to Certification when you are ready to test the real partner route, and to Production after the partner approves.

How long does an API EDI integration take?

Your side can be built and tested in Lab as fast as your data mapping is ready. The partner's testing and approval calendar sets the rest, and nobody can promise a universal go-live date.

Build it in Lab before you touch a partner

Start a free trial or a free developer key, send a Lab document and read the receipt. Partner testing and approval come after.

Start free trialGet a free API key

© 2026 SignalEDI Inc. All rights reserved.