API Reference

6. API Reference

Authentication

Secured API requests require a Bearer token. Generate a Lab, Certification, or Production API key from Connections → Business systems → API connections. Lab keys use sk_lab_, Certification keys use sk_cert_, and Production keys use sk_live_. Each key can address only its own lane; historical sk_test_ keys resolve to Certification. The document-type registry is public for capability discovery.

GET /api/v1/transactions
Authorization: Bearer sk_cert_YOUR_CERTIFICATION_KEY
Content-Type: application/json

REST Endpoints

Trading partners are created in the dashboard (Connections → Partners) or the developer console; pass the resulting partnerId to the API.

Example: list recent failed transactions:

curl -X GET "https://api.signaledi.com/v1/transactions?status=FAILED&limit=50" \
  -H "Authorization: Bearer sk_cert_YOUR_CERTIFICATION_KEY" \
  -H "Content-Type: application/json"

Code Samples

Complete request examples in multiple languages. Click the tabs to switch between cURL, Node.js, Python, and PHP.

curl -X GET "https://api.signaledi.com/v1/transactions" \
  -H "Authorization: Bearer sk_cert_YOUR_CERTIFICATION_KEY" \
  -H "Content-Type: application/json"

curl -X POST "https://api.signaledi.com/v1/documents/outbound" \
  -H "Authorization: Bearer sk_cert_YOUR_CERTIFICATION_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: po-1001-attempt-1" \
  -d '{"partnerId":"your-partner-id","environment":"CERTIFICATION","documentTypeCode":"850","payload":{"purchaseOrderNumber":"PO-1001","lines":[{"sku":"SKU-1","quantity":1,"unitPrice":10}]}}'

curl -X GET "https://api.signaledi.com/v1/transactions/txn_abc123" \
  -H "Authorization: Bearer sk_cert_YOUR_CERTIFICATION_KEY"

# SignalEDI signs the string "<X-SignalEDI-Timestamp>.<rawBody>" with HMAC-SHA256.
# The X-SignalEDI-Signature header is "sha256=<hex>". Verify with:
SIGNED="$TIMESTAMP.$BODY"
echo -n "$SIGNED" | openssl dgst -sha256 -hmac "whsec_YOUR_SECRET"

Rate Limits

Numbers above are typical ceilings; the actual cap that applies to your request is the lower of the per-endpoint ceiling and your plan-tier ceiling (see Acceptable Use). Rate-limit response headers (when present): X-RateLimit-Remaining and X-RateLimit-Reset (Unix timestamp). On a 429, retry after the time indicated in the response body or Retry-After header.

Webhook Setup

Configure a webhook URL in Settings → Webhooks to receive lane-matched document lifecycle updates without polling. Create separate Certification and Production endpoints. Lab uses a signed one-shot probe and never creates a persistent delivery.

SignalEDI sends a POST request to your URL with the following JSON payload:

{
  "id": "evt_01HXYZ",
  "type": "document.accepted.v1",
  "version": "1",
  "createdAt": "2026-09-24T14:00:00.000Z",
  "documentId": "doc_out_01HXYZ",
  "direction": "CUSTOMER_TO_PARTNER",
  "environment": "CERTIFICATION",
  "partnerId": "partner_demo",
  "standard": "x12",
  "documentTypeCodes": ["850"],
  "status": "ACCEPTED",
  "links": {
    "self": "/v1/documents/doc_out_01HXYZ",
    "payload": "/v1/documents/doc_out_01HXYZ/payload"
  }
}

Versioned events include document.accepted.v1, document.available.v1, document.transport_delivered.v1, document.delivery_failed.v1, document.acknowledgement_received.v1, and document.held.v1. Default events contain metadata and authorized pull links, not document contents. Deliveries include X-SignalEDI-Timestamp, X-SignalEDI-Event, and X-SignalEDI-Delivery-ID headers. document.acknowledgement_received.v1 fires for a partner 997, 999, or EDIFACT CONTRL linked to a document admitted through the v1 API; TA1 and 277 responses do not produce a webhook.

Legacy events are still emitted and subscribable; they are signed over the raw body only and carry no timestamp header: transaction.completed, transaction.failed, document.partner_ack, document.ack_overdue, file.processed, mapping.draft.ready, onboarding.certification.requested, onboarding.certified, onboarding.live, incident.opened, incident.resolved, pa.sla.escalation, pa.sla.breach, compliance.risk.detected, compliance.check.resolved.

Verify webhook authenticity by checking the X-SignalEDI-Signature header (HMAC-SHA256 over timestamp + "." + rawBody using your webhook signing secret; reject deliveries whose timestamp skew exceeds ~5 minutes). Deduplicate on X-SignalEDI-Delivery-ID and confirm the environment header matches the endpoint lane.