EDI API: parse, validate and exchange EDI over REST

What is an EDI API?

An EDI API is a web interface to EDI. Instead of building X12 files by hand and managing connections to each partner, your application sends and receives JSON over HTTPS. The API parses incoming EDI into structured data, validates documents against the standard, and hands outbound documents to the route a trading partner requires.

An API does not remove the partner's requirements. Many retailers and payers still mandate EDI documents and specific connections such as AS2 or SFTP. The API is how your systems talk to EDI; for the concept, see the EDI API guide. To compare EDI with direct partner APIs, read EDI vs API.

Quick facts

Authentication

Every secured request carries your key as a Bearer token. Create a key through the developer sign-up (free tier, no card) and keep it in an environment variable such as SIGNALEDI_API_KEY. Never put a key in client-side code or a public repository.

Lab keys validate in your own account without contacting a partner. Certification keys run the same request against the real partner route. Production keys require the connection to be promoted first. Because each key addresses a single lane, a test key cannot send live documents by mistake.

Your first call: parse an X12 file

This sends an X12 850 purchase order interchange (shortened here) to /v1/parse and gets structured JSON back.

curl https://api.signaledi.com/v1/parse \
  -H "Authorization: Bearer $SIGNALEDI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"ISA*...complete X12 interchange...~IEA*...~"}'

The response (abridged) has this shape:

{
  "ok": true,
  "validation": { "sourceFormat": "X12", "transactionSet": "850", "valid": true, "issues": [] },
  "json": { "...": "structured parser output" },
  "envelope": { "...": "interchange details" }
}

/v1/validate takes the same {"content": "..."} body and returns diagnostics only. A missing or empty content returns HTTP 400 with fieldErrors; a body over the size cap returns 413; going over the rate limit returns 429 with a Retry-After header.

Send a document

To send a document, post typed JSON (or exact raw EDI) to /v1/documents/outbound. An Idempotency-Key header (8 to 128 characters) makes retries safe: the same key with the same body replays, the same key with a different body returns 409.

curl -X POST https://api.signaledi.com/v1/documents/outbound \
  -H "Authorization: Bearer $SIGNALEDI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "environment": "LAB",
    "documentTypeCode": "850",
    "payload": {
      "purchaseOrderNumber": "PO-1042",
      "shipTo": { "id": "DC-01", "name": "RetailMart DC 01" },
      "lines": [{ "lineNumber": 1, "sku": "SKU-100", "quantity": 24, "unitPrice": 12.5 }]
    }
  }'

In Lab, a successful call returns HTTP 202:

{
  "ok": true,
  "documentId": "doc_01HXYZ…",
  "status": "validated",
  "environment": "LAB",
  "partnerContacted": false
}

Certification and Production calls also name the trading partner (partnerId) and report admission, routing, transport and acknowledgement states on the document receipt.

Endpoint reference

The documented endpoints (see the full API reference):

Typical ceilings per API key: 120 requests a minute on parse, validate, outbound, inbound and document reads, and 60 a minute on batch. The document-types registry allows 300 a minute per client IP.

Webhooks and acknowledgements

When a trading partner returns a functional acknowledgement (997, 999 or TA1), SignalEDI delivers a signed webhook. In Certification and Production that is document.acknowledgement_received.v1; a terminal failure sends document.delivery_failed.v1. Verify the X-SignalEDI-Signature header (an HMAC-SHA256 over the timestamp and raw body) and use X-SignalEDI-Delivery-ID to make your handler idempotent. The signed webhooks guide has Node and Python code, and the 997/999 guide covers reading the result.

Pricing

Developer API usage is metered separately from the core EDI plans.

A billable call is one parse or one validate request. For example, 20,000 parse and validate calls in a month is 15,000 billable calls at $0.0015, or $22.50. Full terms are on developer API pricing. Business EDI subscriptions for trading partners (Seasonal, Starter, Growth, Enterprise) are on the pricing page.

SDKs, playground and MCP

Try calls without writing code in the API playground. The SDKs page lists language samples, and SignalEDI publishes an MCP server (@signaledi/mcp-server) for compatible agent tools. The public MCP release is for synthetic evaluation only. The developer hub links all of it.

From first call to a live partner

1. Create a free key and run /v1/parse with the sample above.
2. Send a Lab outbound document and read the receipt.
3. Move to Certification with a sk_cert_ key and your partner binding, and watch for the partner's acknowledgement webhook.
4. Promote to Production when the partner approves.

The quickstart and go-live checklist walk through each step. Partners control their own testing and approval calendars, so plan around them.