Broker Genius API Documentation

Endpoints for product images

POST /api/classify-image

Classify products based on their pictures 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
      "image_url": "https://yourdomain.com/images/product1.png"  // Required: URL to product image
    },
    {
      "id": "a24",
      "image_url": "https://yourdomain.com/images/product2.png"
    } ,
    {
      "id": "a25",
      "image_url": "https://yourdomain.com/images/product3.png"
    }
    // 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.
- image_url (string, required): A publicly accessible URL to the product image.
webhook (string, optional): A URL that will receive a POST notification when processing is complete.

Response Format

{
  "webhook": "https://yourdomain.com/webhook",
  "count": 5,
  "status": "success",
  "batchid": "0daad463c65abadcf3c6a1f03230b4f5",
  "message": "All images accepted for processing.",
  "results": [
    {
      "id": "a23",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a24",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a25",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a28",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a29",
      "status": "accepted",
      "message": "Image accepted for processing."
    }
  ]
}

If some images have issues, you might receive a partial success response:

{
  "webhook": "https://yourdomain.com/webhook",
  "count": 5,
  "status": "partial_success",
  "batchid": "0daad463c65abadcf3c6a1f03230b4f5",
  "message": "Image batch processed. Some items may have errors.",
  "results": [
    {
      "id": "a23",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a24",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a25",
      "status": "accepted",
      "message": "Image accepted for processing."
    },
    {
      "id": "a28",
      "status": "error",
      "message": "Invalid image URL or image could not be accessed"
    },
    {
      "id": "a29",
      "status": "accepted",
      "message": "Image accepted for processing."
    }
  ]
}

The response includes:

webhook: The webhook URL you provided (if any)
count: Number of images in the batch
status: Status of the request ("success" or "partial_success")
batchid: The unique identifier for the batch
message: A message indicating the status of the submission
results: Any immediate results or error messages for specific items

Notes on Image Requirements

Images should be clear and well-lit, showing the product against a neutral background
Supported formats: PNG, JPG, JPEG
Maximum file size: 5MB per image
Recommended resolution: At least 800x800 pixels
The URL must be publicly accessible and not require authentication
Images should show the entire product, preferably from multiple angles if possible
Include close-up images of any tags, labels, or markings on the product

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/get-batch 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.

{
  "batchid": "b2e51fae2c5011e06ff23e5a41be3da8",
  "total": 5,
  "count": 5,
  "status": "completed"
}

This response indicates that 5 out of 5 items in the batch have been processed, and the batch is completed

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 images

POST /api/classify-image

Request Format

Request Format

Required Fields:

Response Format

Notes on Image Requirements

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