Broker Genius API Documentation

Endpoints for Invoices

POST /api/classify-invoice

Classify items within an invoice and retrieve the appropriate HTS codes. 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
      "invoice_url": "https://yourdomain.com/invoices/invoice1.pdf"  // Required: URL to product image
    },
    {
      "id": "a24",
      "invoice_url": "https://yourdomain.com/invoices/invoice2.png"
    } ,
    {
      "id": "a25",
      "invoice_url": "https://yourdomain.com/invoices/invoice3.jpg"
    }
    // 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.
- invoice_url (string, required): A publicly accessible URL to your invoice.
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 invoices accepted for processing.",
  "results": [
    {
      "id": "a23",
      "status": "accepted",
      "message": "Invoice accepted for processing."
    },
    {
      "id": "a24",
      "status": "accepted",
      "message": "Invoice accepted for processing."
    },
    {
      "id": "a25",
      "status": "accepted",
      "message": "Invoice accepted for processing."
    },
    {
      "id": "a28",
      "status": "accepted",
      "message": "Invoice accepted for processing."
    },
    {
      "id": "a29",
      "status": "accepted",
      "message": "Invoice 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": "Invoice too large or not accessible. Max 5MB."
    },
    {
      "id": "a28",
      "status": "error",
      "message": "Filetype not allowed."
    },
    {
      "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

Invoice should be clear with items written clearly
Supported formats: PDF,PNG, JPG, JPEG
Maximum file size: 5MB per image
The URL must be publicly accessible and not require authentication

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/getbatchinvoice endpoint with the provided batch ID.

POST /api/getbatchinvoice

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

[
  {
    "invoicegroup": "348c155869dc7ea94796c0c12632d7ee",
    "shipping_handling": "0",
    "discounts": "0",
    "tax_collected": "0",
    "grant_total": "",
    "shipper_country": "",
    "shipper_countrycode": "",
    "items": [
      {
        "quantity": "1",
        "description": "BAOMAO Respirator Mask,Half Facepiece Gas Mask with Safety Glasses Reusable Professional Breathing Protection Against Dust,Chemicals,pesticide and Organic Vapors, Perfect for Painters and DIY Project",
        "short_description": "respirator mask",
        "price": "19.99",
        "item_total": "19.99",
        "htscode": "9020006000",
        "chapterdesc": "Other breathing appliances and gas masks, excluding protective masks having neither mechanical parts nor replaceable filters.",
        "versedesc": "Other breathing appliances and gas masks",
        "weight": "0.500",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "Klein Tools 935DAG Digital Electronic Level and Angle Gauge, Measures 0 - 90 and 0 - 180 Degree Ranges, Measures and Sets Angles",
        "short_description": "angle gauge",
        "price": "29.97",
        "item_total": "29.97",
        "htscode": "9031808085",
        "chapterdesc": "Measuring or checking instruments, appliances and machines, not specified or included elsewhere in this Chapter; profile projectors.",
        "versedesc": "Other",
        "weight": "0.300",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "3M H8A Ratchet Headgear and Visor Combination with 3M WP96 Clear Polycarbonate Faceshield, Complete Headgear and Face Shield Safety System, ANSI Z87, Adjustable, Thermoplastic",
        "short_description": "headgear visor",
        "price": "35.67",
        "item_total": "35.67",
        "htscode": "6506996000",
        "chapterdesc": "Other headgear, whether or not lined or trimmed.",
        "versedesc": "Other",
        "weight": "0.400",
        "subcategory": ""
      }
    ]
  },
  {
    "invoicegroup": "654e763515f2242b7ba83c30f5183c2f",
    "shipping_handling": "39.99",
    "discounts": "0",
    "tax_collected": "19.43",
    "grant_total": "337.07",
    "shipper_country": "United States",
    "shipper_countrycode": "US",
    "items": [
      {
        "quantity": "1",
        "description": "Hammermill Printer Paper, 20 Lb Copy Paper, 8.5 x 14 - 500 Sheets (Pack of 3) - 92 Bright, Made in the USA",
        "short_description": "printer paper",
        "price": "40.49",
        "item_total": "40.49",
        "htscode": "4802552000",
        "chapterdesc": "Uncoated paper and paperboard, of a kind used for writing, printing or other graphic purposes, and non perforated punch-cards and punch tape paper, in rolls or rectangular (including square) sheets, of any size, other than paper of heading 48.01 or 48.03; hand-made paper and paperboard.",
        "versedesc": "Drawing paper",
        "weight": "7.500",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "Post-it Super Sticky Notes, 3x3 in, 24 Pads, 2x the Sticking Power, Supernova Neons, Bright Colors, Recyclable",
        "short_description": "sticky notes",
        "price": "11.00",
        "item_total": "11.00",
        "htscode": "4820102020",
        "chapterdesc": "Registers, account books, note books, order books, receipt books, letter pads, memorandum pads, diaries and similar articles, exercise books, blotting-pads, binders (loose-leaf or other), folders, file covers, manifold business forms, interleaved carbon sets and other articles of stationery, of paper or paperboard; albums for samples or for collections and book covers, of paper or paperboard.",
        "versedesc": "Memorandum pads, letter pads and similar articles",
        "weight": "0.500",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "Raynesys Big and Tall Office Chair for Heavy People, 450LBS Capacity with Wide Seat,Heavy Duty Material, Adjustable Armrests, Ergonomic Executive Chair for Home Office with Strong Lumbar Support,Black",
        "short_description": "office chair",
        "price": "189.99",
        "item_total": "189.99",
        "htscode": "9401999081",
        "chapterdesc": "Seats (other than those of heading 94.02), whether or not convertible into beds, and parts thereof.",
        "versedesc": "Other",
        "weight": "25.000",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "InTheOffice Stackable Letter Tray, Matte Black Wire Mesh Front-Load Letter Tray",
        "short_description": "letter tray",
        "price": "17.28",
        "item_total": "17.28",
        "htscode": "8304000000",
        "chapterdesc": "Filing cabinets, card-index cabinets, paper trays, paper rests, pen trays, office-stamp stands and similar office or desk equipment, of base metal, other than office furniture of heading 94.03.",
        "versedesc": "Desk-top filing or card-index cabinets, paper trays, paper rests, pen trays, office-stamp stands and similar office or desk equipment and parts thereof, of base metal, other than office furniture of heading 9403",
        "weight": "1.000",
        "subcategory": ""
      },
      {
        "quantity": "1",
        "description": "Sharpie Pocket Highlighters, Narrow Chisel Tip Highlighter Marker Set, Pack Of 36 In 6 Assorted Fluorescent And Pastel Highlighters, Ideal For Office Supplies, Teacher Supplies, And School Supplies",
        "short_description": "highlighters",
        "price": "18.89",
        "item_total": "18.89",
        "htscode": "9608200000",
        "chapterdesc": "Ball point pens; felt tipped and other porous-tipped pens and markers; fountain pens, stylograph pens and other pens; duplicating stylos; propelling or sliding pencils; pen-holders, pencil-holders and similar holders; parts (including caps and clips) of the foregoing articles, other than those of heading 96.09.",
        "versedesc": "Felt tipped and other porous-tipped pens and markers",
        "weight": "0.800",
        "subcategory": ""
      }
    ]
  }
]

Response Field Descriptions

The response is an array of invoice groups, each containing:

invoicegroup: Unique identifier for the invoice group
shipping_handling: Shipping and handling charges
discounts: Discounts applied to the invoice
tax_collected: Tax amount collected
grant_total: Grand total of the invoice
shipper_country: Country of the shipper
shipper_countrycode: Two-letter country code of the shipper
items: Array of invoice items, each containing:
- quantity: Quantity of the item
- description: Full description of the item
- short_description: Shortened description
- price: Unit price
- item_total: Total price for this line item
- htscode: Harmonized Tariff Schedule code
- chapterdesc: HTS chapter description
- versedesc: Specific tariff subheading description
- weight: Weight of the item (in kg)
- subcategory: Product subcategory (if available)

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"
Use Webhooks for all invoice 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 Invoices

POST /api/classify-invoice

Request Format

Request Format

Required Fields:

Response Format

Notes on Image Requirements

Webhook Notifications

Webhook Payload

https://yourdomain.com/webhook

POST /api/getbatchinvoice

Authentication

Request Format

Response Format

Response Field Descriptions

Checking Batch Processing Status

Example Response

Rate Limits

Rate Limit Headers

Best Practices for Optimal Results

Provide Detailed Product Descriptions

Use Webhooks for all invoice Processing

Handle Rate Limits

Error Codes and Troubleshooting

Rate Limit Errors

Schedule a Demo