Developers
Niel Customs REST API
API-first access to AI-powered customs operations: HTS classification, duty estimation, compliance screening, and shipment tracking. Build customs directly into your ERP, TMS, or enterprise systems.
Comprehensive API Capabilities
All major platform capabilities are accessible through secure APIs
AI Classification
HTS classification with explainable AI
Duty Estimation
Complete duty & landed cost calculation
Compliance
PGA screening & risk assessment
Shipments
Real-time tracking & milestone updates
Quick Start
Get your API key
Create an account and generate an API key from Account → API. Keys are shown only once — store it securely.
Make your first API call
Use your key to authenticate requests. Include it in the Authorization header as a Bearer token.
Integrate with your systems
Use the API to build customs directly into your ERP, TMS, or custom applications.
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 & Best Practices
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.
Best Practices
- Cache classification results for identical product descriptions
- Use webhooks for real-time updates instead of polling
- Implement exponential backoff when handling 429 errors
- Always verify AI recommendations with a licensed broker
Integration Use Cases
ERP Integration
Automate HTS classification within SAP, Oracle, NetSuite, or other ERP systems for product master data.
TMS Connectivity
Enable duty estimation and shipment tracking from your transportation management system.
E-commerce Checkout
Display landed cost estimates to international buyers at checkout for duty transparency.
Custom Applications
Build customs workflows directly into your proprietary systems with our REST API.
Endpoints
POST/api/v1/classify
Classify a product description to an HTS code.
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 }POST/api/v1/duty
Estimate duty, federal fees (MPF, HMF) and total landed cost. Rates are percentages.
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
# }GET/api/v1/shipments/{id}/status
Get a shipment's status, latest milestones and last-free-day. Scoped to your account — a shipment that is not yours returns 404.
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", ... }
}Get an API key
Create and manage keys and webhooks from your account.
Go to API settings