API Details

How to Use the Reviews API

You can use the reviews APIs to manage reviews on your Zillow Group listings.  The reviews API allows you to get notified when a new review is created by a prospect, get all prospect reviews in bulk and respond to those reviews.

Get Reviews For Listing

Get all the reviews submitted by prospects at any of your listings.  Include the zgListingId for a given property and we’ll send back any reviews posted to that property.  The response will include the review ID, review date, star rating, message, brand site it was posted on, response date (if you responded) and response message (if you responded).  You can respond to these reviews via the “Post Responses Call” detailed below.

GET reviews/v1/getReviewsForListing

Sample response:

{
  "status": "success",
  "errors": [],
  "payload": [
    {
      "zgListingId": "46nyx2rxsy6vq",
      "reviewId": "8423915803661960",
      "reviewDate": "2018-05-29T19:30:36.101Z",
      "starLevel": 5,
      "reviewMessage": "Extremely helpful agent and leasing company",
      "brand": "zillow",
      "reviewType": "propertyManager"
    },
    {
      "zgListingId": "46nyx2rxsy6vq",
      "reviewId": "79953441578265601",
      "reviewDate": "2018-05-29T19:30:03.377Z",
      "starLevel": 5,
      "reviewMessage": "Nice, smart home, good neighborhood. Excellent agency",
      "brand": "zillow",
      "reviewType": "property"
    }
  ]
} 

Submit Review Response

You can use this API call to respond to reviews you have received from Zillow Group prospects.  Your responses will be noted on our sites.  Simply include the review ID and your response message in the call.  

POST reviews/v1/submitReviewResponse

Sample response:

{
  "status": "success",
  "errors": []
}

Register Callback

Use this call to register your callback URL.  Registering a callback URL (webhook) will allow you to get notified when a new review is submitted on one of your properties.  We include an optional callbackApiKey that can be sent along with the callback to verify that it’s Zillow.

POST  reviews/v1/registerCallback

Sample request body:

{
  "callbackUrl":"https://example.com/zillowReviewCallback",
  "callbackApiKey":"demo",
  "zgListingIds": ["46nyx2rxsy6vq", "47nyc1234y6va"]
}

Sample response:

{
  "status": "success",
  "errors": [],
  "payload": ["46nyx2rxsy6vq", "47nyc1234y6va"]
}

Once you have registered a callbackUrl, we will call that callbackUrl each time a new review is posted for one of your listings on any of the Zillow Group sites.  Here is what that response will look like.

POST callbackUrl?apiKey=callbackApiKey

Sample request body:

[
  {
    "zgListingId": "46nyx2rxsy6vq", 
    "reviewId": "8423915803661960", 
    "reviewDate": "2018-05-29T19:30:36.101Z", 
    "starLevel": 5, 
    "reviewMessage": "Extremely helpful agent and leasing company", 
    "brand": "zillow",
    "reviewType": "propertyManager"
  },
  {
    "zgListingId": "46nyx2rxsy6vq", 
    "reviewId": "79953441578265601", 
    "reviewDate": "2018-05-29T19:30:03.377Z", 
    "starLevel": 5, 
    "reviewMessage": "Nice, smart home, good neighborhood. Excellent agency", 
    "brand": "zillow",
    "reviewType": "property"
  }
]

Unregister Callback

Use this call to unregister a callback. 

POST  reviews/v1/unregisterCallback

Sample request body:

["46nyx2rxsy6vq", "47nyc1234y6va"]

Sample response:

{
  "status": "success",
  "errors": []
}