Reviews API

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
Parameter Validation Type Description
accessToken Required String Used to authenticate the request. Please see this page for more details about authentication.
clientId Required String Used to authenticate the request. Please see this page for more details about authentication.
apiKey Required String Used to authenticate the request. Please see this page for more details about authentication.
zgListingId Required String Id of listing to fetch reviews for.
startReviewId Optional String Optional id of review for paging.
limit Optional Integer The number of records in the response.  Default and Max is 100.

 

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
Parameter Validation Type Description
accessToken Required String Used to authenticate the request. Please see this page for more details about authentication.
clientId Required String Used to authenticate the request. Please see this page for more details about authentication.
apiKey Required String Used to authenticate the request. Please see this page for more details about authentication.
reviewId Required String Zillow Group’s reviewId that was returned in the getReviewsForListing response.
responseMessage Required String Your response to the review.

 

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

Parameter Validation Type Description
apiKey Required String Used to authenticate the request. Please see this page for more details about authentication.
clientId Required String Used to authenticate the request. Please see this page for more details about authentication.
accessToken Required String Used to authenticate the request. Please see this page for more details about authentication.
callbackUrl Required String in the request body Your hosted URL that we will call when a new review is available.
callbackApiKey Optional String in the request body This key we will use when doing the callback.  Used for authentication/security in your system (to confirm it’s Zillow).
zgListingIds Required Array of strings in the request body Ids of listings you want to register.

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
Parameter Validation Type Description
apiKey Optional String The callbackApiKey you supplied in the registerCallback call.
reviews.reviewId Included String Internal Zillow Group review Id.
reviews.reviewDate Included String ISO instant.
reviews.starLevel Included Integer Rating given between 1 and 5.
reviews.reviewMessage Included String The review message left by the prospect.
reviews.brand Included String The brand the review was received on.  options can be Zillow, Trulia or HotPads.
reviews.zgListingId Included String Id of the listing
reviews.reviewType Included String Type of the review: “property” or “propertyManager”

 

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

Parameter Validation Type Description
apiKey Required String Used to authenticate the request. Please see this page for more details about authentication.
clientId Required String Used to authenticate the request. Please see this page for more details about authentication.
accessToken Required String Used to authenticate the request. Please see this page for more details about authentication.
zgListingIds Required Array of strings in the request body Ids of listings you want to unregister.

Sample request body:

["46nyx2rxsy6vq", "47nyc1234y6va"]

Sample response:

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