Broker Genius API Documentation

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_KEY

Request 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 resets

Best 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 id for each item to easily match results to your original products
- Use alphanumeric identifiers that are meaningful in your system
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.

Made under the in Anguilla, home of .ai

"; ?>

Endpoints for product names

POST /api/classify

Request Format

Required Fields:

Response Format

Webhook Notifications

Webhook Payload

https://yourdomain.com/webhook

POST /api/getbatch

Authentication

Request Format

Response Format

Checking Batch Processing Status

Example Response

Rate Limits

Rate Limit Headers

Best Practices for Optimal Results

Provide Detailed Product Descriptions

Include Unique IDs for Each Item

Use Webhooks for Large Batch Processing

Handle Rate Limits

Error Codes and Troubleshooting

Rate Limit Errors

Schedule a Demo