REST API

Reviews API

Overview

The Reviews API is designed to make it easy to invite, manage and display customer reviews.

Most of the Reviews API endpoints require a Location ID. This can be found in the Developers section of the Location Settings page inside the Management Panel.

Generally speaking the Reviews API is designed to respond extremely quickly and reliably to requests. It is considered safe for use inside of a request cycle but sites targeting high performance should still cache results to provide the fastest loading times.

Authentication

Most Reviews API endpoints do not require any form of integration as they are designed for public consumption.

A small number of the Reviews API endpoints do require an Authentication Token to use. You can read more about acquiring and using Authentication Tokens in the Authentication reference.

Endpoints

Get Review Summary

This endpoint allows you to get the average review and metadata scores for a given location.

URL

  GET - https://api.opinous.com/v1/l/<LOCATION_ID>/reviews/summary

Request Parameters

N/A

Response Body

{
  "average_score": 4.2,
  "metadata": [
      {
        "id": "5df723f8-7416-46a5-ae83-2fe4d045ffa2",
        "field_name": "Quality of Service",
        "average_score": 3.1
      }
  ]
}

Get Reviews

This endpoint allows you to retrieve the published reviews for a given location.

N.B: This endpoint does not support viewing reviews that are still awaiting verification or that have been disputed. If you wish to access reviews that are not published you must use the Admin API

URL

  GET - https://api.opinous.com/v1/l/<LOCATION_ID>/reviews

Request Parameters

Query Parameters

Parameter Name	Required	Default	Value
`limit`	Optional	25	An integer between 1 and 250
`cursor`	Optional	Current Timestamp	An ISO-8601 timestamp

Response Body

Review without a response

{
  "pagination": {
    "limit": 2,
    "next_page_cursor": "2019-05-01T12:00:00"
  },
  "reviews": [
    {
      "id": "d8487f43-a57c-4981-9ae7-e5350494bfed",
      "reviewer": {
        "name": "Tony Stark",
        "is_verified": true
      },
      "review": {
        "overall_rating": 4,
        "text_body": "I liked the restaurant overall but the service was quite slow.",
        "authored_at": "2019-05-02T07:00:00"
      },
      "response": null
    }
  ]
}

Review with a response

{
  "pagination": {
    "limit": 2,
    "next_page_cursor": "2019-05-01T12:00:00"
  },
  "reviews": [
    {
      "id": "d8487f43-a57c-4981-9ae7-e5350494bfed",
      "reviewer": {
        "name": "Natasha Romanov",
        "is_verified": true
      },
      "review": {
        "overall_rating": 3,
        "text_body": "I really enjoyed my time at the Shalom Grill. I will definitely be coming back soon!",
        "authored_at": "2019-05-02T07:00:00"
      },
      "response": {
        "text_body": "We're so glad you enjoyed your visit Natasha! We look forward to welcoming you back in the near future.",
        "authored_at": "2019-05-02T15:00:00"
      }
    }
  ]
}

Write a Review

This endpoint allows you to submit a review to the Opinous platform using a custom collection method such as a whitelabel form.

Please note that reviews collected using this method are still subject to the same verification requirements meaning the reviewer will be contacted by Opinous. For this reason we recommend that you display the "Verified by Opinous" logo somewhere on the form.

You can read more about our whitelabel implementation guidelines in the Implementing a Custom Review Form guide.

URL

  POST - https://api.opinous.com/v1/l/<LOCATION_ID>/submit-review

Request Parameters

Body Parameters

Parameter Name	Required	Value
`email_address`	Required	The email address of the person writing the review.
`full_name`	Required	The full name of the person writing the review.
`review_body`	Required	The body text of the review that the user has written.
`overall_rating`	Required	An integer between 1 and 5 inclusive representing the user's review score
`metadata`	Required	A Dictionary of UUID field ID's to string values

Example Body

{
  "email_address": "[email protected]",
  "full_name": "Steve Rogers",
  "review_body": "I would highly recommend the Beef Taco to anyone who's hungry!",
  "overall_rating": 5,
  "metadata": {
    "aa836839-96b0-40f6-8b04-862e8f977103": "Darren",
    "5df723f8-7416-46a5-ae83-2fe4d045ffa2": 5
  }
}

Response Body

{
  "id": "f4caecb6-8322-4fa5-905c-9e2948a7de51"
}