Developers
API documentation
Read shipments and documents, receive events, and exchange EDI — over HTTPS, with scoped keys.
Authentication
Every /api/v1 request carries an API key.
Keys look like niel_sk_… and are issued in your workspace under Integrations → API keys. The raw key is shown once — only its SHA-256 hash is stored, and it can never be recovered later.
Send it as an Authorization: Bearer header on every request.
Scopes are read and write. The public read endpoints below require the read scope. Write endpoints are coming soon.
Create and revoke keys anytime in App → Integrations. Revoked keys stop working immediately.
curl https://www.nielcos.ai/api/v1/shipments \
-H "Authorization: Bearer niel_sk_..."REST endpoints
Base URL: https://www.nielcos.ai
GET/api/v1/shipments
List the key owner's shipments, most recently updated first.
GET/api/v1/shipments/{id}
One shipment by GTTID, master B/L number, or container number. Returns 404 when nothing matches.
GET/api/v1/documents
Document metadata for the key owner's company (latest 100), including parse status. File downloads stay inside the workspace.
curl https://www.nielcos.ai/api/v1/shipments/NIEL-2026-000123 \
-H "Authorization: Bearer niel_sk_..."
# { "shipment": { "gttid": "NIEL-2026-000123", ... } }
# 404 -> { "error": "not_found" }Responses are JSON. Shipment objects include gttid, mbl_no, container_number, status, origin, destination, current_location, eta, and updated_at. Errors use { error, detail? } with HTTP status codes.
Webhooks
Subscribe a URL per event in App → Integrations → Webhooks. Deliveries POST JSON within seconds, and every delivery is logged per endpoint.
document.parsedA document finished AI parsing.
drayage_move.createdA drayage move was created.
drayage_move.status_changedA drayage move changed status.
Verifying signatures
Every delivery carries X-Niel-Event (the event name) and X-Niel-Signature: sha256=<hex>. The signature is HMAC-SHA256 of the raw request body, keyed with your endpoint secret (whsec_…).
Compare in constant time and only accept bodies whose signature matches — then process the JSON { event, delivered_at, data }.
import { createHmac, timingSafeEqual } from "crypto";
const sig = req.headers["x-niel-signature"]; // "sha256=<hex>"
const expected =
"sha256=" +
createHmac("sha256", process.env.NIEL_WEBHOOK_SECRET)
.update(rawBody)
.digest("hex");
const ok =
sig.length === expected.length &&
timingSafeEqual(Buffer.from(sig), Buffer.from(expected));EDI inbox
Trade EDI the way your partners already send it.
Paste or upload ANSI X12 in App → Integrations → EDI. The inbox auto-identifies 850 (purchase order), 856 (ship notice / ASN), and 810 (invoice), and parses each into structured data with header, lines, and totals.
Uploads are capped at 2 MB per document. Anything else lands as “unknown” with the raw text preserved for review.
Rate limits
No published per-minute limits — fair use applies. Planning sustained high volume? Talk to us first so we can provision for it.