Endpoints for product names
POST /api/classify
Classify products based on their text descriptions and retrieve the appropriate HTS codes and PGA requirements. This endpoint processes requests asynchronously and returns a batch ID that can be used to retrieve results.
Request Format
{
"item": [
{
"id": "a23", // Required: Your item identifier
"product": "iPhone case", // Required: Product description
"suggested_hts": "6110201020" // Optional: suggested HTS code
},
{
"id": "a24",
"product": "Brown school bag"
},
{
"id": "a25",
"description": "jogging shoes", // Alternative description field
"product": "6404110000"
}
// More items...
],
"webhook": "https://yourdomain.com/webhook" // Optional: URL to receive completion notification
}Required Fields:
item(array): An array of products to classify, each containing:id(string, required): A unique identifier for your item that will be returned in the response.product(string, required): A detailed description of the product.suggested_hts(string, optional): If you have a suggested HTS code you want evaluated.description(string, optional): Alternative field for product description.
webhook(string, optional): A URL that will receive a POST notification when processing is complete.
Response Format
{
"batchid": "b2e51fae2c5011e06ff23e5a41be3da8",
"webhook": "https://yourdomain.com/webhook"
}Webhook Notifications
When processing is complete, a POST request will be sent to the webhook URL you provided in your original request. This allows your application to receive a notification rather than polling for results.
Webhook Payload
https://yourdomain.com/webhook
{
"status": "completed",
"batch_id": "b2e51fae2c5011e06ff23e5a41be3da8",
"message": "Your batch is ready.",
"timestamp": "2025-04-14T15:30:45Z"
}Upon receiving this notification, you can then retrieve the full results using the /api/getbatch endpoint with the provided batch ID.
POST /api/getbatch
Retrieve the results of a previously submitted classification batch using the batch ID. Authentication via API key is required.
Authentication
Include your API key in the Authorization header:
Authorization: Bearer YOUR_API_KEYRequest Format
{
"batchid": "b2e51fae2c5011e06ff23e5a41be3da8"
}Response Format
{
"batchid": "ac8c63e8d04a15cbc8930545fa088be5",
"count": 5,
"items": [
{
"pid": "a23",
"product": "ipone case",
"suggested_hts": "6110201020",
"ctarrif": "42029215",
"ctarrifxt": "00",
"shortdesc": "phone case",
"schap": "Trunks, suit-cases, vanity-cases, executive-cases, brief-cases, school satchels, spectacle cases, binocular cases, camera cases, musical instrument cases, gun cases, holsters and similar containers; traveling- bags, insulated food or beverages bags, toilet bags, rucksacks, handbags, shopping-bags, wallets, purses, map-cases, cigarette-cases, tobacco-pouches, tool bags, sports bags, bottle- cases, jewellery boxes, powder-boxes, cutlery cases and similar containers, of leather or of composition leather, of sheeting of plastics, of textile materials, of vulcanized fibre or of paperboard, or wholly or mainly covered with such materials or with paper.",
"sverse": "Of cotton (369)",
"unit": "[\"No.\",\"kg\"]",
"general": "6.3%",
"specail": "Free (A,AU,BH,CL,CO,D,IL,JO,KR, MA,NP,OM,P,PA,PE,S,SG) 4.9% (E)",
"other": "40%",
"pga": [
{
"hts_chapter_range": "4202",
"products": "Trunks, suitcases, briefcases, school bags",
"requirements": "Tracking labels for children's products",
"pga_code": "CPSC",
"filing_codes": "CPC CPT",
"exemptions": "Adult-only products",
"thresholds": "Commercial: All quantities"
}
]
},
{
"pid": "a24",
"product": "Brown school bag",
"suggested_hts": "Not provided",
"ctarrif": "42029245",
"ctarrifxt": "00",
"shortdesc": "school bag",
"schap": "Trunks, suit-cases, vanity-cases, executive-cases, brief-cases, school satchels, spectacle cases, binocular cases, camera cases, musical instrument cases, gun cases, holsters and similar containers; traveling- bags, insulated food or beverages bags, toilet bags, rucksacks, handbags, shopping-bags, wallets, purses, map-cases, cigarette-cases, tobacco-pouches, tool bags, sports bags, bottle- cases, jewellery boxes, powder-boxes, cutlery cases and similar containers, of leather or of composition leather, of sheeting of plastics, of textile materials, of vulcanized fibre or of paperboard, or wholly or mainly covered with such materials or with paper.",
"sverse": "Other",
"unit": "[\"No.\",\"kg\"]",
"general": "20%",
"specail": "Free (A,AU,BH,CL,CO,D,IL, JO,KR,MA,NP,OM,P,PA,PE,R,S, SG) 17.5% (E)",
"other": "45%",
"pga": [
{
"hts_chapter_range": "4202",
"products": "Trunks, suitcases, briefcases, school bags",
"requirements": "Tracking labels for children's products",
"pga_code": "CPSC",
"filing_codes": "CPC CPT",
"exemptions": "Adult-only products",
"thresholds": "Commercial: All quantities"
}
]
}
// Additional items...
]
}Checking Batch Processing Status
curl -X POST https://api.brokergenius.ai/api/batchstatus \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"batchid": "b2e51fae2c5011e06ff23e5a41be3da8"
}'Example Response
{
"batchid": "b2e51fae2c5011e06ff23e5a41be3da8",
"total": 5,
"count": 3,
"status": "processing"
}This response indicates that 3 out of 5 items in the batch have been processed, and the batch is still being processed.
Rate Limits
To ensure optimal service performance, the following rate limits apply:
| Limit Type | Value |
|---|---|
| Requests per second | 5 |
| Requests per minute | 60 |
| Maximum descriptions per request | 5,000 |
| Recommended batch size | 100-150 descriptions |
These limits are designed to ensure the API remains responsive for all users. If you need higher limits for bulk processing, please contact our support team.
Rate Limit Headers
Rate limit information is included in all API responses via these headers:
X-RateLimit-Limit: 60 // Requests per minute allowed
X-RateLimit-Remaining: 58 // Remaining requests in the current window
X-RateLimit-Reset: 1649843402 // Timestamp when the rate limit window resetsBest Practices for Optimal Results
-
Provide Detailed Product Descriptions
- Include materials, composition, dimensions, and intended use
- For example: "Women's closed-toe leather pumps with 3-inch heel, rubber sole, no laces or straps" is better than just "Women's shoes"
-
Include Unique IDs for Each Item
- Always provide a unique
idfor each item to easily match results to your original products - Use alphanumeric identifiers that are meaningful in your system
- Always provide a unique
-
Use Webhooks for Large Batch Processing
- When processing large batches, provide a webhook URL to receive notifications when processing completes
- This allows for asynchronous processing of large product sets
-
Handle Rate Limits
- For large volumes, space out your requests to stay within rate limits
- Consider implementing a queuing system for high-volume operations
Error Codes and Troubleshooting
| Status Code | Description | Solution |
|---|---|---|
| 400 | Bad Request | Check your request format and parameters |
| 401 | Unauthorized | Verify your API key is valid and included correctly |
| 429 | Too Many Requests | You've exceeded your rate limit; wait and try again |
| 500 | Internal Server Error | Contact support |
Rate Limit Errors
If you exceed rate limits, you'll receive a 429 Too Many Requests response:
{
"error": "Rate limit exceeded",
"message": "You have exceeded the API rate limit. Please slow down your requests.",
"retry_after": 12
}The retry_after field indicates the number of seconds to wait before retrying.
For additional support, contact api-support@brokergenius.com.