Categorize a product

Find the SureBright category of a product from its page URL or from the product details you already have.

A plan is priced by category, so before you can quote a product that is not in a store catalog SureBright has indexed, you need its SureBright category (sbCategoryId). These endpoints read a product page or take the details you send, classify the product, and return the category together with what was read. Use the v2 endpoints; the older ones remain for existing integrations.

No authentication header is needed for these endpoints.

EndpointInputUse
GET /quote/api/v2/productCategory/getProductDetailsProduct page URLRead and classify a page
POST /quote/api/v2/productCategory/getProductCategoryProduct details in the bodyClassify without fetching the page
GET /quote/api/productCategory/getProductDetailsProduct page URLPrevious reader; same shape with a legacy mapping block
GET /quote/api/productCategoryProduct page URLOriginal classifier; kept for existing callers

Classify a product page#

GET https://{HOST_NAME}/quote/api/v2/productCategory/getProductDetails

stringrequired

The product page URL, Base64-encoded (UTF-8).

string

Your own reference for this product; echoed back. One is generated when omitted.

string

0 or false to re-read the page instead of returning the cached result for this URL.

bash
URL=$(printf '%s' 'https://www.example-store.com/products/aero-2-electric-scooter' | base64)
curl "https://{HOST_NAME}/quote/api/v2/productCategory/getProductDetails?base64ProductURL=${URL}"

Response#

isErrorboolean

false when the page was read.

urlstring

The decoded URL.

vectorIdstring

Your reference, or the generated one.

productDataobject

What was read and decided about the product.

statusstring

COMPLETED.

Results are cached per URL. The same URL returns the cached result until you pass useCache=0.

Classify from product details#

POST https://{HOST_NAME}/quote/api/v2/productCategory/getProductCategory

Use this when you already have the product fields, for example from your own catalog feed, and do not want SureBright to fetch the page.

stringrequired
Product title.
stringrequired
Product description.
stringrequired
Price, for example "899.00".
stringrequired
Main image URL.
string
Product page URL. Used as the cache key, so send it when you have it.
string
Your own reference; echoed back.
string
Comma-separated category names from your store, to help the classifier.
bash
curl -X POST 'https://{HOST_NAME}/quote/api/v2/productCategory/getProductCategory' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://www.example-store.com/products/aero-2-electric-scooter",
    "title": "Aero 2 Electric Scooter",
    "description": "Foldable commuter e-scooter, 350 W motor, 25 km range.",
    "price": "899.00",
    "imageURL": "https://www.example-store.com/cdn/aero-2.jpg",
    "categories": "Mobility, Electric scooters"
  }'

Response#

The same envelope as above (isError, url, vectorId, productData, status), plus:

categorizationStatusstring

SUCCESS when a category was assigned, otherwise FAILED.

categorystring

The narrowest category label assigned.

insurerCategoryobject

Legacy mapping block: classifiedCategory and isCoverageAvailable (false when the product fell into an uncovered bucket such as OTHERS). The other ids in it are internal.

Older endpoints#

GET /quote/api/productCategory/getProductDetails?base64ProductURL=&vectorId=&useCache= returns the page reading with the same legacy insurerCategory block and status: "COMPLETED".

GET /quote/api/productCategory?base64ProductURL= (or ?vectorId= to re-read an earlier result) returns productData with a specifications map that includes Classified Category, the legacy insurerCategory block, status and vectorId. It is slower and should not be used for new work.

Errors#

All four endpoints use the same codes.

CodeBodyMeaning
400{"isError": true, "message": "Insufficient params"}base64ProductURL (or vectorId on the original endpoint) missing
400{"isError": true, "message": "Insufficient data"}Empty body on the details endpoint
400{"isError": true, "message": "Error in getting product details"} or "Error in getting product category"The page could not be read, or title, description, price or imageURL is missing
400{"isError": true, "message": "Unable to scrape page"}, "No Product Data found", "No Matching vectors found"Original endpoint only
500Internal Server ErrorUnexpected failure

SureBright logs every request and response on these endpoints for quality review.