Vision Feedback
POST /v3/vision/feedback. Tell us what the user finally chose after a vision identify.
POST /v3/vision/feedback
Legacy path: POST /api/v3/vision/feedback (same behavior).
After a Vision identify call, tell us what the user finally chose: the prediction_id of that response and the catalog id of the choice, or the prediction_id alone when nothing was chosen. Ids only: no photos, no personal data. Feedback is free and is what improves recognition over time, so send it whether the choice came from the suggestions, from a search, or was none of them.
Try it in the API Explorer: run Vision identify there first, then use Send feedback for this prediction to open this endpoint with its prediction_id filled in.
Request
curl -X POST https://api.pricehero.ai/v3/vision/feedback \
-H "Authorization: Bearer ph_test_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"prediction_id": "0f2d5f4e-8c1a-4a2b-9e5d-1c3b7a9d2e40",
"id": "product_JB5lJPuuSS7w6SZmbXvoxckOXJshColLEhf1"
}'Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
prediction_id | string | yes | The prediction_id of the identify response the choice came from. Must have been issued to your API key. |
id | string | no | The catalog id chosen: a product_… id after the product step, a style_… id after the style step, or a model_… id if the flow stopped at the model. A style (handbags) or dial (watches) id stands for its product, since each has exactly one. Omit it when nothing was chosen. |
unlisted | object | no | The item chosen when it is not in our catalog. See Items not in the catalog. Send either id or unlisted, not both. |
Nothing else is needed. Where the choice sat in the suggestions, and whether it was among them at all, is worked out on our side from what that prediction returned.
Items not in the catalog
When the item your user chose isn't in our catalog, describe it in unlisted instead of sending an id:
| Field | Required | What it is | Example |
|---|---|---|---|
brand | yes | The maker | Hermès, Rolex |
model | at least one of these three | The product line or family | Kelly, Submariner |
name | The full item name, as it would appear on a listing | Kelly 25 Sellier Epsom | |
reference | The maker's reference or style number | 126610LN, M41113 |
Send whatever you have. If you're unsure which field a value belongs in, send it anyway: these details are reviewed by our catalog team, not matched automatically. Other fields are ignored.
{
"prediction_id": "0f2d5f4e-8c1a-4a2b-9e5d-1c3b7a9d2e40",
"unlisted": { "brand": "Rolex", "model": "Submariner", "reference": "126610LN" }
}Send feedback within 72 hours of the identify call, with a key from the same environment (test or live) as the one that made it. If you need a longer window for your workflow, contact us.
If your user changes their mind, send the new choice for the same prediction_id: the latest choice is the one that counts. A prediction's choice can be changed up to 3 times. Sending the same choice again is safe and returns the recorded result.
Each identify call is its own prediction, so the two-step flow gives two: the model step, which ranked models, and the product step, which ranked the styles of the model chosen. Send one feedback per prediction you want to report, each with its own prediction_id and the id chosen at that step: a model_… id for the model step, a product_… (or style_…) id for the product or style step. Reporting only the final step is fine too.
Response
202 Accepted:
{ "success": true, "status": "recorded", "outcome": "suggested", "node": "product", "rank": 1 }What we resolved from that prediction's own results: outcome is suggested (the id was among its suggestions), other (a catalog id it had not suggested, e.g. found through search), unlisted (an item outside the catalog, sent as unlisted) or none (nothing chosen); node is what that prediction ranked, model or product; rank is the 1-based position of the id in that list, present only when it was there.
With a test key, feedback is validated exactly as live feedback, so the same integration works in both, and the response adds a warnings line: sandbox feedback is not used for training and earns no rebate.
| Status | When |
|---|---|
400 | Missing or malformed prediction_id, a prediction_id that was not issued to this key or not from a successful identify call, a key from a different environment than the prediction's, feedback sent after the window, an id that is not a catalog product, model, style or dial, both id and unlisted, an unlisted object without a brand and at least one of model, name or reference, or, for a test key, an id outside the sandbox catalog |
409 | The choice for this prediction_id was already changed 3 times |
503 | Feedback store temporarily unavailable, or another request for the same prediction_id is still being recorded; retry shortly (nothing changed, so the retry is accepted) |
Credits
Free. Feedback calls are logged but never charged. Rebates, where your API Commercial Agreement provides them, are credited after the feedback window closes, usually on your next invoice; see Credits.