BOSS Unknown Items API
Accepts requests to classify items that don't appear in the retailer catalog (ingest API), or haven't yet been registered by the supplier.
Use as follows:
- Submit the request with product images (required) and a GTIN (preferred, but not required)
- SmarterX provides a classification (10 minutes to 10 hours)
- Use polling or webhooks to determine when the recommendations are ready (request state COMPLETE)
SmarterX may require updated information if unclear images were provided, in which case the request state will move to UPDATES_NEEDED and messages will be shown indicating requested changes.
In rare instances, items may prove impossible to classify, due to lack of available product info, or product labeling being too damaged to make a determination. In these cases products will move to WASTE_HAULER state, indicating that the contracted waste hauler should make a determination upon pickup.
https://boss-test.smarterx.comAuthentication
Get all unknown item requests for a location
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Query Parameters
start_date
Start of time range for requests to return. Defaults to 24 hours ago.
end_date
End of time range for requests to return. Defaults to right now.
page
1-indexed page number (defaults to 1)
page_size
page size (defaults to 10)
Path Parameters
location_id
Location name
1
Create a new unknown item request
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Path Parameters
location_id
Location name
Request Body
Submit this body to initiate an unknown item classification request
sku
SKU
external_id
Custom retailer identifier
gtin
callback_url
Provide this to receive results via webhook (POST to this URL)
images
1
{
"sku": "12345",
"external_id": "customer_identifier",
"gtin": "893094008075",
"callback_url": "https://example.com/api/unknown_items",
"images": [
{
"name": "front of product",
"filename": "image-front.jpg",
"content_type": "image/jpeg",
"url": "https://example.com/path/to/product/assets/image-front.jpg"
},
{
"name": "back of product",
"filename": "image-back.png",
"content_type": "image/png",
"data": "iVBORw0KGgoAAAANSUhEUgAAAJMAAA <rest of base64 example trimmed>"
}
]
}Get the status and results for a submitted request
This endpoint may be polled to get the status of the request.
Please refrain from polling at a frequency greater than six times per minute.
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Path Parameters
request_id
Request ID (UUID)
1
Update a request, e.g. to submit new images
Use this endpoint to update an existing request. The request state will change back to SUBMITTED.
Modifying a request in one of the following states is not allowed:
- COMPLETE
- WASTE_HAULER
- REGISTERED
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Path Parameters
request_id
Request ID (UUID)
1
Cancel a pending unknown items request
Cancels an in-progress request.
Cancelling a request in one of the following states is not allowed:
- COMPLETE
- WASTE_HAULER
- REGISTERED
Headers
Authorization
The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Path Parameters
request_id
Request ID (UUID)
1