EDI API quickstart: send your first document in 10 minutes

1. Get your API key

Create a Lab platform key in the developer console and export it as SIGNALEDI_API_KEY. Lab keys use sk_lab_; Certification keys use sk_cert_; Production keys use sk_live_ and require Production authority. Never commit keys to git.

• Platform scope unlocks /api/v1/* endpoints
• A credential can address only its own lane
• Rotate keys on a regular cadence

2. Send a JSON 850 purchase order

POST to the outbound documents endpoint with environment, documentTypeCode, and payload. In Lab, SignalEDI validates the payload and mapping in the customer account without contacting a partner, billing a transport, or creating normal lifecycle webhooks. An optional partnerId may select an account-owned mapping context.

• Required: environment, documentTypeCode, and exactly one of payload, content, or contentBase64; Certification and Production also require an exact account-owned partner binding
• Required header: Idempotency-Key (8–128 chars) — identical key + identical body replays safely; identical key + different body returns 409
• Validation errors return 400 with fieldErrors

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 '{
  "partnerId": "your-partner-id",
  "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
      }
    ]
  }
}'

3. Expected response

A successful Lab validation returns HTTP 202 with status=validated, a documentId, environment=LAB, and partnerContacted=false. Certification and Production receipts separately report admission, processing, routing, transport, acknowledgement, and customer-delivery states.

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

4. Node example

Same request in JavaScript — ideal for serverless or Next.js route handlers.

const res = await fetch("https://api.signaledi.com/v1/documents/outbound", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SIGNALEDI_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    partnerId: "your-partner-id",
    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 }],
    },
  }),
});
const data = await res.json(); // { ok: true, documentId, status, environment }

5. Python example

Same outbound call in Python — works with requests, httpx, or any HTTP library in data pipelines and Django/FastAPI backends.

import os
import uuid
import requests

r = requests.post(
    "https://api.signaledi.com/v1/documents/outbound",
    headers={
        "Authorization": f"Bearer {os.environ['SIGNALEDI_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "partnerId": "your-partner-id",
        "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}],
        },
    },
)
print(r.json())

6. Validation errors

Missing required fields return HTTP 400 with field-level detail. A later terminal transport or processing failure emits document.delivery_failed.v1 with a safe public code; pull the tenant-scoped receipt for detail.

{
  "ok": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "fieldErrors": { "partnerId": "Required string" }
}

7. Receive the real 997 in Certification

Register a Certification HTTPS webhook endpoint and repeat the same request with a sk_cert_ key and environment=CERTIFICATION. When the partner returns a functional acknowledgement, SignalEDI emits document.acknowledgement_received.v1 with normalized outcome and receipt links. Lab can simulate acknowledgements but never contacts the partner or creates a persistent delivery.

• Verify X-SignalEDI-Signature on every delivery
• Use X-SignalEDI-Delivery-ID for idempotent handlers

8. Go-live reality check

Your SignalEDI side can reach partner-ready setup in days, not weeks. Trading partner certification still follows their calendar — plan for weeks on partner timelines.