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": []
}