Working with Reviews
Once you’ve become familiar with the capabilities of Yext and our APIs, you may be eager to see what consumers are saying about your business. Fortunately for you, the Reviews API is here to serve that purpose! As with the Listings and Analytics guides, you will need to use a Production account with a Professional or Ultimate package to follow the steps below, but you will need the Ultimate package to test responding to reviews.

See your reviews

The first step is to see what reviews you have for your business. You can do so with the Reviews List API call:

GEThttps://api.yext.com/v2/accounts/me/reviews?api_key=API_KEY&v=YYYYMMDD

This call will return up to the first 100 Reviews for your Locations under your Accounts, the total review count, and the average review rating. An example response is shown below:
{
  "meta": {
    "uuid": "ad7dd47e-ac6a-47a8-812e-7ccfc6ef0d82",
    "errors": [
      
    ]
  },
  "response": {
    "reviews": [
      {
        "id": 505344811,
        "rating": 5,
        "content": "So glad I came here for an emergency repair of my violin. I cracked the body recently, and they had it fixed up by the next day. And somehow it sounds better now than it ever did!",
        "authorName": "",
        "url": "http:\/\/www.showmelocal.com\/test",
        "publisherDate": "2016-10-17T14:52",
        "locationId": "31345354169_2_2",
        "publisherId": "SHOWMELOCAL",
        "lastYextUpdateTime": "2016-10-17T14:52",
        "comments": [
          
        ]
      },
      {
        "id": 505323157,
        "rating": 3.5,
        "content": "Needed an emergency repair the day before a concert and Carl was able to get me fixed up within a couple hours!",
        "authorName": "Patrick",
        "publisherDate": "2016-10-17T12:30",
        "locationId": "3134131243469_2_2",
        "publisherId": "OPENDI",
        "title": "Saved me!",
        "lastYextUpdateTime": "2016-10-17T12:30",
        "comments": [
          
        ]
      },
      {
        "id": 450053491,
        "rating": 5,
        "content": "This was the best experience I've ever had at an instrument store ever, A+",
        "authorName": "Chris",
        "publisherDate": "2016-06-16T14:36",
        "locationId": "18162432476",
        "publisherId": "FACEBOOK",
        "lastYextUpdateTime": "2016-09-13T18:39",
        "comments": [
          {
            "id": 849563,
            "publisherDate": "2016-09-13T18:39",
            "authorName": "Crescendo Music Supplies",
            "authorRole": "BUSINESS_OWNER",
            "message": "Thanks! We hope you’ll visit us again soon.",
            "visibility": "PUBLIC"
          },
          {
            "id": 849564,
            "publisherDate": "2016-09-13T18:39",
            "authorName": "Sarah",
            "authorRole": "CONSUMER",
            "message": "I AGREE -- great store with great service!",
            "visibility": "PUBLIC"
          }
        ]
      }
    ],
    "averageRating": 4.5,
    "count": 3
  }
}
Like many of our API endpoints, this call allows you to filter to a specific set of a Reviews. You can filter to Reviews for only a set of Locations, specific publishers, within certain dates, with a minimum or maximum rating, and many other properties. The endpoint also supports pagination, so if you have more than 100 Reviews for a given filter criteria, then you can paginate through the responses to see all the Reviews.

Take a moment and try making a few filtered API calls. In particular, try filtering by certain publishers, by certain Locations, and by Reviews with a minimum rating.

Retrieve a specific review

Now that you’ve mastered filtering your Reviews, let’s take a deeper look at retrieving a single Review using a Get Review API Request:

GEThttps://api.yext.com/v2/accounts/me/reviews/REVIEW_ID?api_key=API_KEY&v=YYYYMMDD

The response will return a single Review object like the one below:
{
  "meta": {
    "uuid": "0122c856-b3fe-4fd2-b887-61c712297646",
    "errors": []
  },
  "response": {
    "id": Test_Review01,
    "locationId": "TestLocation1",
    "publisherId": "YEXT_TEST_PUB",
    "rating": 4,
    "title": "Great Job",
    "content": "The owner did a great job!",
    "authorName": "Carl Simmons",
    "authorEmail": "carl@example.com",
    "url": "https://www.example.com/TestLocation1/Test_Review01",
    "publisherDate": “2016-10-17”,
    "lastYextUpdateDate": “2016-10-18”,
    “comments”: []
  }
}
The Review object will include the Review ID, the Location ID, the publisher ID, and the specific Review content. For certain publishers, the comments array will be populated with Comment objects. At the time of writing, only Facebook and Google My Business will have Reviews with Comments.

Respond to a review

After looking at a few Reviews, you may want to respond to them in order to create a dialogue with your customers. At the time of writing, only Facebook and Google My Business support responding to a Review, and only Facebook supports responding to a Comment of a Review. To test the following API calls, you will need a Location that is actively subscribed to Facebook or Google My Business through a Ultimate package. You can respond to Facebook or Google My Business with the following Create Comment API request:

POSThttps://api.yext.com/v2/accounts/me/reviews/REVIEW_ID/comments?api_key=API_KEY&v=YYYYMMDD&content=REVIEW_CONTENT

If the attempt is successful, you will receive a 201 response with the Comment you created. If you look at the Comment, you will notice the authorRole is set to BUSINESS_OWNER and the visibility is set to PRIVATE, which are the default values for these fields. If you would like to make the comment publicly viewable, you can do so by adding visibility=PUBLIC parameter to the request URL.

Respond to a comment on a review

Facebook allows users to reply to responses to reviews posted on their site. In doing so, a user creates a new conversation thread tied to the original response. Let’s make a Create Comment API call, specifying the Parent Comment:

POSThttps://api.yext.com/v2/accounts/me/reviews/REVIEW_ID/comments?api_key=API_KEY&v=YYYYMMDD&content=REVIEW_CONTENT&parentId=PARENT_COMMENT_ID

Like the previous Create Comment request, this request will return a 201 response containing the Comment object if it is successful. If you look closely at the Comment object, you will see the parentId field is populated with the ID sent in the API request. You’ve now accomplished getting a group of or a single Reviews and successfully created a Comment with and without a Parent Comment for a Review. Feel free to make a few more API calls and see what else you can do here!