Niel Customs API

Authentication

Every request must include an API key as a Bearer token. Keys look likeniel_<prefix>_<secret>and are created in your portal under Account → API. The full key is shown only once at creation — store it securely; we keep only a hash.

Authorization: Bearer niel_ab12cd34ef56_0123...

A missing or invalid key returns 401. All errors use the shape { "error": "message" }.

Rate limits

Requests are rate-limited per API key to 60 requests per minute. Exceeding the limit returns 429 Rate limit exceeded. Contact us if you need a higher limit.

Endpoints

curl -X POST https://www.nielcustoms.ai/api/v1/classify \
  -H "Authorization: Bearer niel_ab12cd34ef56_0123..." \
  -H "Content-Type: application/json" \
  -d '{"description":"Cotton knit t-shirt","origin":"China"}'

# → { "hts": "6109.10.0012", "confidence": 0.87 }

curl -X POST https://www.nielcustoms.ai/api/v1/duty \
  -H "Authorization: Bearer niel_ab12cd34ef56_0123..." \
  -H "Content-Type: application/json" \
  -d '{"customsValue":10000,"dutyRate":3.5,"freight":800,"ocean":true,"sec301":25}'

# → {
#     "currency": "USD",
#     "customsValue": 10000,
#     "duty": 350,
#     "sec301": 2500,
#     "mpf": 34.64,
#     "hmf": 12.5,
#     "landedCost": 13697.14
#   }

curl https://www.nielcustoms.ai/api/v1/shipments/SHIPMENT_ID/status \
  -H "Authorization: Bearer niel_ab12cd34ef56_0123..."

# → {
#     "id": "...",
#     "status": "customs_hold",
#     "eta": "2026-07-10T00:00:00.000Z",
#     "lastFreeDay": "2026-07-14T00:00:00.000Z",
#     "milestones": [ { "type": "exam", "occurredAt": "..." } ],
#     "containers": [ ... ]
#   }

Machine-readable spec: GET /api/v1/openapi.json (OpenAPI 3).

Webhooks

Register a webhook in Account → API to receive a POST when a shipment milestone is added (shipment.event, shipment.released, …) or a case status changes (case.status_changed). Each delivery is signed with aX-Niel-Signatureheader — an HMAC-SHA256 of the raw request body using your webhook signing secret.

X-Niel-Signature: sha256=<hmac_sha256(rawBody, webhookSecret)>

{
  "event": "shipment.released",
  "createdAt": "2026-07-05T12:00:00.000Z",
  "data": { "shipmentId": "...", "type": "released", ... }
}