⚙️

Batch Classification

ActiveCoreMUSTFREE

What it does

Classify hundreds of products at once via the batch API. Upload a JSON array of products and receive HS codes for all of them in a single request. The batch endpoint processes items in parallel (10 concurrent) with built-in deduplication — if the same product name appears multiple times, it's classified once and the result is reused.

Required Fields for 100% Accuracy

2 required / 9 total

Field	Type	Required	Description	Example
`items[].id`	string	!	Unique ID for result mappingUse your internal SKU or product ID for easy mapping.	`SKU-001`
`items[].productName`	string	!	Product name	`Cotton t-shirt`
`items[].material`	string	opt	Material (WCO group)	`cotton`
`items[].category`	string	opt	Product category	`apparel`
`items[].processing`	string	opt	Processing method	`knitted`
`items[].composition`	string	opt	Material composition	`100% cotton`
`items[].weight_spec`	string	opt	Weight specification	`180 g/m2`
`items[].price`	number	opt	Unit price	`14.99`
`items[].origin_country`	string	opt	Origin country (ISO code)	`CN`

Tips for Best Accuracy

✓Each item requires id + productName at minimum
✓More fields per item = higher confidence scores
✓Duplicate productNames are auto-deduplicated — classified once, result copied to all matching IDs
✓Max items per request: 500 (Forever Free plan)

Common Mistakes

✗Missing id field — results cannot be mapped back without unique IDs
✗Exceeding batch limit — check your plan limit (500 for Forever Free)
✗Inconsistent field naming — use snake_case for batch items (origin_country not originCountry)

How to use it

Prepare your product list

Create a JSON array with each item having a unique id and productName at minimum.

Send the batch request

POST /api/v1/classify/batch with your items array. Max items: 500 (Free plan).

Map results by ID

Each result includes the original id you provided for easy mapping back to your catalog.

Handle failures

Items that fail classification will have an error field. Retry these individually with more detail.

API Reference

POST/api/v1/classify/batch

Request

{
  "items": [
    {
      "id": "SKU-001",
      "productName": "Cotton t-shirt"
    },
    {
      "id": "SKU-002",
      "productName": "Ceramic mug"
    },
    {
      "id": "SKU-003",
      "productName": "Leather wallet"
    }
  ]
}

Response

{
  "success": true,
  "results": [
    {
      "id": "SKU-001",
      "hsCode": "6109.10",
      "confidence": 0.94,
      "description": "T-shirts, of cotton"
    },
    {
      "id": "SKU-002",
      "hsCode": "6912.00",
      "confidence": 0.91,
      "description": "Ceramic tableware"
    },
    {
      "id": "SKU-003",
      "hsCode": "4202.31",
      "confidence": 0.89,
      "description": "Wallets, of leather"
    }
  ],
  "batchSize": 3,
  "processedAt": "2026-03-29T12:00:00Z"
}

cURL

curl -X POST https://potal.app/api/v1/classify/batch \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"SKU-001","productName":"Cotton t-shirt"},{"id":"SKU-002","productName":"Ceramic mug"}]}'

Related Features

⚙️HS Code Classification

Classify products into 5,000+ HS codes using the v3.3 GRI pipeline

🛠️Batch Import/Export

Bulk import products via CSV and export results in any format

🛠️CSV Export

Export classification and calculation results as CSV files

⚙️Confidence Score

Multi-dimensional confidence scoring for every classification result

🛠️High Throughput

117K pre-computed results for sub-50ms response times

Having issues?

🐛 Report a Bug ❓ Ask a Question 💡 Suggest Improvement