Quick Start
Get started with the classification.tools API in minutes. Follow these steps to make your first classification request.
1. Get Your API Key
Sign up for an account and retrieve your API key from the dashboard. You'll need this for authentication.
Request API Key2. Make Your First Request
Here's a simple example using cURL to classify a product by HS code:
curl -X POST https://api.classification.tools/v1/classify/hs-code \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product_description": "Stainless steel bolts, 10mm diameter",
"origin_country": "US",
"destination_country": "NL"
}'
3. Handle the Response
The API returns a JSON response with the classification results:
{
"status": "success",
"data": {
"hs_code": "731815",
"description": "Threaded articles - Screws and bolts, whether or not with their nuts or washers",
"confidence": 0.98,
"country_specific_code": "7318150000",
"duty_rate": "2.5%",
"processing_time_ms": 142
}
}
Authentication
All API requests require authentication using Bearer token authentication.
Bearer Token
Include your API key in the Authorization header of every request:
Authorization: Bearer YOUR_API_KEY
Security: Never expose your API key in client-side code or public repositories. Always use environment variables and secure server-side requests.
API Endpoints
Base URL: https://api.classification.tools/v1
HS Code Classification
POSTClassify products using the Harmonized System (HS) for customs and tariff purposes.
Endpoint:
/classify/hs-code
Request Body:
{
"product_description": "string (required)",
"origin_country": "string (ISO 3166-1 alpha-2)",
"destination_country": "string (ISO 3166-1 alpha-2)",
"language": "string (default: 'en')",
"include_duty_rates": boolean (default: true)
}
Response:
{
"status": "success",
"data": {
"hs_code": "string (6-digit)",
"hs_code_full": "string (10-digit country-specific)",
"description": "string",
"confidence": number (0-1),
"duty_rate": "string",
"restrictions": ["string"],
"alternative_codes": [
{
"hs_code": "string",
"confidence": number,
"description": "string"
}
],
"processing_time_ms": number
}
}
ECCN Classification
POSTDetermine Export Control Classification Number (ECCN) for U.S. export compliance.
Endpoint:
/classify/eccn
Request Body:
{
"product_description": "string (required)",
"technical_specifications": "string",
"intended_use": "string",
"destination_country": "string (ISO 3166-1 alpha-2)"
}
Response:
{
"status": "success",
"data": {
"eccn": "string",
"classification_category": "string",
"license_required": boolean,
"license_exceptions": ["string"],
"reason_for_control": ["string"],
"confidence": number,
"ear99": boolean,
"processing_time_ms": number
}
}
CAS Number Lookup
POSTIdentify chemicals using Chemical Abstracts Service (CAS) registry numbers.
Endpoint:
/classify/cas
Request Body:
{
"chemical_name": "string",
"formula": "string (optional)",
"synonyms": ["string"]
}
Response:
{
"status": "success",
"data": {
"cas_number": "string",
"iupac_name": "string",
"molecular_formula": "string",
"molecular_weight": number,
"synonyms": ["string"],
"hazard_classifications": ["string"],
"confidence": number,
"processing_time_ms": number
}
}
Dangerous Goods Classification
POSTClassify dangerous goods for air (IATA), sea (IMDG), and road (ADR) transport.
Endpoint:
/classify/dangerous-goods
Request Body:
{
"product_description": "string (required)",
"transport_mode": "string (air|sea|road|rail)",
"cas_number": "string (optional)",
"include_labels": boolean (default: true)
}
Response:
{
"status": "success",
"data": {
"un_number": "string",
"proper_shipping_name": "string",
"hazard_class": "string",
"packing_group": "string",
"special_provisions": ["string"],
"limited_quantity": "string",
"labels_required": ["string"],
"emergency_response_guide": "string",
"confidence": number,
"processing_time_ms": number
}
}
Error Handling
The API uses standard HTTP status codes and returns detailed error messages.
HTTP Status Codes
OK
Request successful
Bad Request
Invalid request parameters
Unauthorized
Invalid or missing API key
Too Many Requests
Rate limit exceeded
Internal Server Error
Server-side error occurred
Error Response Format
{
"status": "error",
"error": {
"code": "INVALID_REQUEST",
"message": "Product description is required",
"details": {
"field": "product_description",
"reason": "missing_required_field"
}
}
}
Rate Limits
API rate limits vary by plan to ensure fair usage and optimal performance.
| Plan | Rate Limit | Monthly Requests |
|---|---|---|
| Starter | 10 requests/second | 5,000 |
| Enterprise | 100 requests/second | Unlimited |
Tip: Rate limit information is included in response headers: X-RateLimit-Limit,
X-RateLimit-Remaining, and X-RateLimit-Reset.
Code Examples
Integration examples in popular programming languages.
JavaScript (Node.js)
const axios = require('axios');
async function classifyProduct(description) {
try {
const response = await axios.post(
'https://api.classification.tools/v1/classify/hs-code',
{
product_description: description,
origin_country: 'US',
destination_country: 'NL'
},
{
headers: {
'Authorization': `Bearer ${process.env.API_KEY}`,
'Content-Type': 'application/json'
}
}
);
console.log('HS Code:', response.data.data.hs_code);
console.log('Confidence:', response.data.data.confidence);
return response.data;
} catch (error) {
console.error('Classification error:', error.response.data);
throw error;
}
}
classifyProduct('Stainless steel bolts, 10mm diameter');
Python
import requests
import os
def classify_product(description):
url = 'https://api.classification.tools/v1/classify/hs-code'
headers = {
'Authorization': f'Bearer {os.environ["API_KEY"]}',
'Content-Type': 'application/json'
}
data = {
'product_description': description,
'origin_country': 'US',
'destination_country': 'NL'
}
try:
response = requests.post(url, json=data, headers=headers)
response.raise_for_status()
result = response.json()
print(f"HS Code: {result['data']['hs_code']}")
print(f"Confidence: {result['data']['confidence']}")
return result
except requests.exceptions.RequestException as e:
print(f"Classification error: {e}")
raise
classify_product('Stainless steel bolts, 10mm diameter')
PHP
$apiKey = getenv('API_KEY');
$url = 'https://api.classification.tools/v1/classify/hs-code';
$data = [
'product_description' => 'Stainless steel bolts, 10mm diameter',
'origin_country' => 'US',
'destination_country' => 'NL'
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($httpCode === 200) {
$result = json_decode($response, true);
echo "HS Code: " . $result['data']['hs_code'] . "\n";
echo "Confidence: " . $result['data']['confidence'] . "\n";
} else {
echo "Error: " . $response . "\n";
}
Webhooks
Receive real-time notifications about classification events and updates.
Setting Up Webhooks
Configure webhook URLs in your dashboard to receive POST requests when events occur:
classification.completed- Async classification finishedbatch.completed- Batch processing completedrate_limit.approaching- 80% of rate limit reachedregulatory.update- Regulatory changes affecting your classifications
Webhook Payload Example
{
"event": "classification.completed",
"timestamp": "2025-01-15T10:30:00Z",
"data": {
"classification_id": "cls_abc123",
"status": "completed",
"hs_code": "731815",
"confidence": 0.98
}
}