Quickstart
Get up and running with TariffLens API. Classify your first product in under 5 minutes.
Before you begin, you'll need a TariffLens account and API key. Contact [email protected] to request access.
Get your API key
Navigate to Settings → API in your TariffLens dashboard and create a new API key. Your key will look like:
tlk_live_xxxxxxxxxxxxxxxxxxxxxNever commit your API key to version control or expose it in client-side code.
Create a product and classify it
The fastest path is POST /api/v1/products/classify — it creates a product row and queues classification runs against one or more tariff schedules in a single call.
curl -X POST https://api.tarifflens.ai/api/v1/products/classify \
-H "Authorization: Bearer tlk_live_xxxxx" \
-H "Content-Type: application/json" \
-d '{
"product": {
"name": "Industrial Servo Motor",
"description": "Brushless AC servo motor, 2.5kW"
},
"schedules": ["US-HTS"]
}'The API returns immediately with the product ID and one classification stub per requested schedule:
{
"product_id": "product_abc123xyz",
"product": {
"id": "product_abc123xyz",
"name": "Industrial Servo Motor",
"country_of_origin": null,
"created_at": "2026-01-08T10:30:00Z"
},
"classifications": [
{
"id": "clf_def456",
"status": "pending",
"schedule": "US-HTS",
"poll_url": "/api/v1/classifications/clf_def456"
}
],
"estimated_completion_seconds": 45
}Pass more entries in schedules: ["US-HTS", "EU-CN"]. You'll get one classification back per schedule, each polled and billed independently. Currently supported values: US-HTS and EU-CN. Other schedules (UK Global Tariff, EU TARIC, Schedule B, ECCN, EU Dual-Use) aren't available yet.
Poll for the result
Classifications take approximately 60 seconds on average. Poll the classification's poll_url until status is completed or failed:
curl https://api.tarifflens.ai/api/v1/classifications/clf_def456 \
-H "Authorization: Bearer tlk_live_xxxxx"When complete, you'll receive the full classification result:
{
"id": "clf_def456",
"status": "completed",
"schedule": "US-HTS",
"product": {
"name": "Industrial Servo Motor",
"description": "Brushless AC servo motor, 2.5kW"
},
"result": {
"hts_code": "8501524000",
"hts_description": "AC motors, multi-phase: Of an output exceeding 750 W but not exceeding 75 kW",
"supporting_rulings": ["NY N123456", "HQ H987654"],
"reasoning": "Classified as AC servo motor exceeding 750W based on product specifications and CBP ruling precedent."
}
}Tip: GET /api/v1/products/{product_id} returns the product plus every classification under it in one round-trip — handy when you classified against several schedules at once.
You can split the flow: POST /api/v1/products creates a product without classifying it (no credits consumed), then POST /api/v1/classifications with { product_id, schedules } queues the runs later. Useful when you import a catalog up front and classify on demand.
For production use, see our Async & Webhooks guide for recommended polling strategies, webhook setup, and best practices.
You've classified your first product
You're now ready to integrate TariffLens into your application. Explore the full API reference for advanced features like batch classification and webhook notifications.