Match an order for review

List the dishes of an order your backend sent that the diner can rate, with any stars they already gave.

POST/api/v1/reviews/matchClient API

Before showing a "How was your order?" sheet: the order's dishes the diner can rate, by Tamr's ids or yours, with your titles and any stars already given. The order must be one your backend sent for this user, placed or completed, in the last 30 days.

The order must be one your backend sent (POST /api/v1/sdk/orders) for this user, placed or completed, in the last 30 days.

Authentication

Client API. Send your publishable key in x-tamr-key and the diner's session in x-tamr-session, from Start a session. For a guest's session, also send its device id in x-tamr-device. A browser may call it only from an origin listed on the key.

Headers

NameTypeRequiredDescription
x-tamr-devicestringNoGuest sessions only: the device id the session was exchanged with. Matches ^[A-Za-z0-9_-]{8,128}$.
x-tamr-appstringNoNative apps only: the app's iOS bundle id or Android package name. A key used from an app it doesn't list is logged, never refused. Matches ^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z0-9_-]+)+$.

Request body

FieldTypeRequiredDescription
orderIdstringYes1 to 200 characters.
dishesarray of objectYes1 to 30 items.
dishes[].dishIdstringNo1 to 200 characters.
dishes[].externalIdstringNo1 to 200 characters.
dishes[].titlestringYes1 to 200 characters.

Response

FieldTypeDescription
dishesarray of object1 to 30 items.
dishes[].dishIdstring1 to 200 characters.
dishes[].externalIdstring or null1 to 200 characters.
dishes[].titlestring1 to 200 characters.
dishes[].imageUrlstring or nullMatches ^https:\/\/[^\s]+$.
dishes[].ratinginteger or null1 to 5.
unmappedarray of objectAt most 30 items.
unmapped[].externalIdstring1 to 200 characters.

Example

curl https://tamr.link/api/v1/reviews/match \
  -H "x-tamr-key: $TAMR_APP_KEY" \
  -H "x-tamr-session: $TAMR_SESSION" \
  -H "content-type: application/json" \
  -d '{
  "orderId": "A-99812",
  "dishes": [
    {
      "externalId": "SKU-1042",
      "title": "Kafta plate"
    },
    {
      "dishId": "dish_fattoush",
      "title": "Fattoush"
    },
    {
      "externalId": "DRINK-7",
      "title": "Lemonade"
    }
  ]
}'

Example response

{
  "dishes": [
    {
      "dishId": "dish_kafta",
      "externalId": "SKU-1042",
      "title": "Kafta plate",
      "imageUrl": "https://tamr.link/image-proxy/tamr/dishes/kafta.webp",
      "rating": null
    },
    {
      "dishId": "dish_fattoush",
      "externalId": null,
      "title": "Fattoush",
      "imageUrl": null,
      "rating": 4
    }
  ],
  "unmapped": [
    {
      "externalId": "DRINK-7"
    }
  ]
}

Errors

Every error has the same body; switch on data.code. See Errors and rate limits.

data.codeStatusWhat to do
app_key_invalid401The key is wrong, revoked or of another kind. Check it in the dashboard.
sdk_disabled403The SDK isn't switched on for this restaurant. Ask Tamr.
origin_not_allowed403A browser called from an origin the key doesn't list. Add the origin to the key.
session_expired401Start a new session with a fresh token or code, then send the call again once.
invalid_request400A field doesn't match the spec. The message says which.
rate_limited429Wait retryAfter seconds (also in the Retry-After header), then try again.
review_refused409An order's dishes can't be rated. reviewRefusal says why: order_not_found, order_closed, too_old or nothing_to_review.
guest_not_allowed401The key has no guest mode: sign the diner in with a token or a code.