Broker Genius API Documentation

Endpoints for Invoices

POST /api/xclassify-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. There will be three notification pushes

Webhook Payload

https://yourdomain.com/webhook

Initializing - Invoices has been uploaded

{
  "status": "initializing",
  "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8",
  "message": "Invoices recieved.",
  "timestamp": "2025-04-14T15:30:45Z"
}

Processing - The extraction process has begun

{
  "status": "processing",
  "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8",
  "message": "Invoices ready for processing",
  "timestamp": "2025-04-14T15:30:45Z"
}

completed - The extraction has completed

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

POST /api/xgetbatchinvoice

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


{
    "invoice": [
        {
            "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",
            "price": "40.49",
            "page": "1",
            "itemtotal": "40.49",
            "tariff": "48025410",
            "tariff_suffix": "00",
            "invoice_currency": "USD",
            "shortdescription": "Printer Paper",
            "chapter": "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\n48.01 or 48.03; hand-made paper and paperboard.",
            "subheading_description": "Writing paper"
        },
        {
            "quantity": "1",
            "description": "Post-it Super Sticky Notes, 3x3 in, 24 Pads, 2x the Sticking Power, Supernova Neons, Bright Colors, Recyclable",
            "price": "11.00",
            "page": "1",
            "itemtotal": "11",
            "tariff": "48201020",
            "tariff_suffix": "20",
            "invoice_currency": "USD",
            "shortdescription": "Sticky Notes",
            "chapter": "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\nor  for  collections  and  book covers, of paper or paperboard.",
            "subheading_description": "Memorandum pads, letter pads and similar articles"
        },
        {
            "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",
            "price": "19.99",
            "page": "1",
            "itemtotal": "19.99",
            "tariff": "90200060",
            "tariff_suffix": "00",
            "invoice_currency": "USD",
            "shortdescription": "Respirator Mask",
            "chapter": "Other breathing appliances and gas masks, excluding protective masks having neither mechanical parts nor replaceable filters.",
            "subheading_description": "Other breathing appliances and gas masks"
        },
        {
            "quantity": "1",
            "description": "Klein Tools 935DAG Digital Electronic Level and Angle Gauge, Measures 0 - 90 and 0 - 180 Degree Ranges, Measures and Sets Angles",
            "price": "29.97",
            "page": "1",
            "itemtotal": "29.97",
            "tariff": "90318080",
            "tariff_suffix": "60",
            "invoice_currency": "USD",
            "shortdescription": "Digital Level",
            "chapter": "Measuring or checking instruments, appliances and machines, not\nspecified or included elsewhere in this Chapter; profile projectors.",
            "subheading_description": "For testing electrical characteristics"
         }

Response Field Descriptions

The response is an array of invoice items, each containing the following fields:

quantity: Quantity of the item.
description: Full description of the item.
shortdescription: Concise or summarized name of the item.
price: Unit price of the item.
page: Page number where the item appears in the original document.
itemtotal: Total amount for this line item.
tariff: Harmonized Tariff Schedule (HTS) code assigned to the item.
tariff_suffix: Tariff suffix or precision indicator, representing the tariff's sub-classification level.
invoice_currency: Currency code used in the invoice (e.g., USD, EUR).
chapter: HTS chapter description corresponding to the item's tariff code.
subheading_description: Detailed subheading or verse-level description within the HTS chapter.

Checking Batch Processing Status

curl -X POST https://api.brokergenius.ai/api/xbatchstatus \
-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:

Feature	Description
Processing Model	Managed concurrency with automatic queueing and fair allocation across users
Throughput	Optimized for efficient processing with variable performance based on load
Limit Approach	Concurrent processing focus rather than fixed time-based limits
Request Handling	Asynchronous processing with automatic retries and rate limit compliance

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.

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

For additional support, contact api-support@brokergenius.com.

Try our Customs Automation
Tool for FREE!

No Credit Card Required

Enjoy a Free Trial First

Book a Customs Automation Demo
With Our Team

Experience Broker Genius in action by scheduling a personalized demo. Our experts will walk you through the platform's powerful features, answering any questions and demonstrating how easily it integrates with your existing workflows.

Made under the in Anguilla, home of .ai

"; ?>

Broker Genius API Documentation

Endpoints for Invoices

POST /api/xclassify-invoice

Request Format

Required Fields:

Response Format

Notes on Image Requirements

Webhook Notifications

Webhook Payload

https://yourdomain.com/webhook

Initializing - Invoices has been uploaded

`{ "status": "initializing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices recieved.", "timestamp": "2025-04-14T15:30:45Z" }`

Processing - The extraction process has begun

`{ "status": "processing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices ready for processing", "timestamp": "2025-04-14T15:30:45Z" }`

completed - The extraction has completed

`{ "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/xgetbatchinvoice` endpoint with the provided batch ID.

POST /api/xgetbatchinvoice

Authentication

Request Format

Response Format

Response Field Descriptions

Checking Batch Processing Status

Example Response

Rate Limits

Error Codes and Troubleshooting

Try our Customs Automation
Tool for FREE!

No Credit Card Required

Book a Customs Automation Demo
With Our Team

Endpoints for Invoices

POST /api/xclassify-invoice

Request Format

Required Fields:

Response Format

Notes on Image Requirements

Webhook Notifications

Webhook Payload

https://yourdomain.com/webhook

Initializing - Invoices has been uploaded

{ "status": "initializing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices recieved.", "timestamp": "2025-04-14T15:30:45Z" }

Processing - The extraction process has begun

{ "status": "processing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices ready for processing", "timestamp": "2025-04-14T15:30:45Z" }

completed - The extraction has completed

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

POST /api/xgetbatchinvoice

Authentication

Request Format

Response Format

Response Field Descriptions

Checking Batch Processing Status

Example Response

Rate Limits

Error Codes and Troubleshooting

Try our Customs Automation Tool for FREE!

No Credit Card Required

Book a Customs Automation Demo With Our Team

`{ "status": "initializing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices recieved.", "timestamp": "2025-04-14T15:30:45Z" }`

`{ "status": "processing", "batch_id": "b2e51fae2c5011e06ff23e5a41be3da8", "message": "Invoices ready for processing", "timestamp": "2025-04-14T15:30:45Z" }`

`{ "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/xgetbatchinvoice` endpoint with the provided batch ID.

Try our Customs Automation
Tool for FREE!

Book a Customs Automation Demo
With Our Team