An application programming interface (API) is a computing interface which defines interactions between multiple software intermediaries. It defines the kinds of calls or requests that can be made, how to make them, the data formats that should be used, the conventions to follow, etc.
The Featured Properties (weekly) API enables you to programmatically activate Featured Properties directly within your internal CRM.
Use the Featured Properties (weekly) API to:
- Activate the Featured Properties product, subject to available credits
- Check if a property listing has a Featured Properties product activated
- Pick the property listings of your choice and activate the Featured Properties (weekly) add-on
- Get a history of your Featured Properties product activations
Note
The API work is still in progress and details provided in this documentation are subject to change
This article includes:
- Prerequisites
- Authentication
- Working with the API
- How to check if a property listing is 'Featured Properties (weekly)' activated
- Errors
- Postman collection
- Questions
Prerequisites
This article assumes you have a general knowledge of command line interfaces and software development.
Authentication
The first step of working with the Featured Properties (weekly) API is to set up authentication for your client. Please follow the steps in Authentication - Tech Documentation.
Working with the API
The API is asynchronous. What does this mean? When you make a request to activate a property listing for Featured Properties (weekly), we validate the request and place it in a queue for further processing, returning a status of PENDING
Once processed, there are two possible statuses:
- ACTIVATED which means the Featured Properties (weekly) property you specified is now live on the Zoopla website
- ERROR which suggests an issue occurred during the operation. More details are provided in the response
The sequence diagram below provides an overview of how the API works:
Available endpoints
Below you will find details about the requested payload and responses as shown in the sequence diagram above.
Request Featured Properties (weekly) property activation - request [004]
Method: POST
Path: /products/weekly-featured-properties
Payload:
}
"listingId":123
}
To activate the Featured Properties (weekly) product, a unique request must be made for each listing and include the relevant listingId.
Validation rules:
You cannot request to activate the Featured Properties (weekly) product in the event:
- The listingId doesn't exist or is invalid
- The client doesn't have access to the listing
- A listingId has an activation status of PENDING
- The Featured Properties (weekly) product is already active for that specific listing
The listingId is required in all circumstances.
Example cURL request:
curl --location --request POST 'https://services.zoopla.co.uk/products/weekly-featured-properties' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJraWQiOiJMU0VyUkowYk5ubkg0UGorUUZObXdnd08wNk1UdXBoNVJJOERlRGp3ZXg4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiIzNG9iYXJlbGNkN3BuanJxZmYwNjZqdWljdiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXBpXC9hcGlfYWNjZXNzIiwiYXV0aF90aW1lIjoxNTk1MjQ0MjMwLCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAuZXUtd2VzdC0xLmFtYXpvbmF3cy5jb21cL2V1LXdlc3QtMV9nMHFlWlJuYlQiLCJleHAiOjE1OTUyNDc4MzAsImlhdCI6MTU5NTI0NDIzMCwidmVyc2lvbiI6MiwianRpIjoiNjAyYmYzMjItYWI4ZC00MDBlLWJiODEtZjE2NTc4ZjM1MDAyIiwiY2xpZW50X2lkIjoiMzRvYmFyZWxjZDdwbmpycWZmMDY2anVpY3YifQ.puj4abAiORSAS0zuXCFAbhwai9Nf29RcVV4XkOsLd_Xl8oAwswzKARg3hKLMsRadoIc8qk7OFASg594j0aoutqcceyhsg6zBn6kt-INfwiNJ0pIjUAxVDKglZQk3dLJWQffLTFCzXNsxhB5lAWP4IHHSBgkDh8_EQ5d5UyDI5urn1zOT8bbH3aXpF6YUWfZDVPSqobB5y_Tky1lLvxtqkQQwFPppRW8r-PGrI__zljtFATCeJOw9GrnM9UNBtk76s0G43ox4PmlzD9Viu7Y15vWjy2kHbkxaCHoCXVOaM1nT2GsRp_1E_DKiF7vzEzSfkD_mdCDM5dbhuEiLvZgVLw' \
--data-raw '{
"listingId": 123
}'
Get details of Featured Properties (weekly) activation - request [008]
Path: /products/weekly-featured-properties/{weeklyFeaturedPropertiesUUID}
Example response: 200 OK
When a request is still PENDING
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "PENDING"
},
"isRenewable": false
}
When a request is completed and status is ACTIVATED
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00",
"isRenewable": false
}
When a request is completed but there was a problem during Featured Properties (weekly) activation
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ERROR",
"errors": [
{
"reason": "Listing ID doesn't exist",
"code": 2011011
}
]
},
"isRenewable": false
}
When there is already a pending Featured Properties (weekly) activation for the listingId
{
"errors": [
{
"reason": "There is already a weekly featured property activation pending for this listing ID",
"code": 2011004
}
]
}
Get all Featured Properties (weekly) activations
There is also an endpoint which allows you to get all requests to activate the Featured Properties (weekly) product the user has access to.
Method: Get
Path: /products/weekly-featured-properties
Example Response: 200 OK
[
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 567,
"createdAt": "2020-07-17T12:35:38.049963+01:00",
"updatedAt": "2020-07-17T12:35:38.049963+01:00",
"status": {
"result": "PENDING"
},
"isRenewable": false
},
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00",
"isRenewable": false
}
]
You can narrow the number of objects in the array by providing query parameters:
- listingId - return only activation requests related to the given listingId
- isWFP - return only activations which are currently effectively active
Both parameters can be combined in one request, and in such case, parameters are connected with logical AND. Further information on how to use parameters can be found below/
Example request: /products/weekly-featured/properties?listingId=123
[
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00",
"isRenewable": false
}
]
Note
API does not support pagination yet. This is going to be defined
How to check if a property listing is 'Featured Properties (weekly)' activated
Using endpoint /products/weekly-featured-properties provides the activation status of a listing without knowing the activation request uuid.
To check if a specific listingId is a Featured Properties (weekly), the following request can be used:
GET https://services.zoopla.co.uk/products/weekly-featured-properties?listingId=123&isWFP=true
If listing 123 is a Featured Properties (weekly) property, the response will look like this:
[
{
"id": "5ecba691-84d6-4a60-9587-ca810292f5b0",
"listingId": 123,
"createdAt": "2020-07-20T12:35:38.049963+01:00",
"updatedAt": "2020-07-20T12:35:38.049963+01:00",
"status": {
"result": "ACTIVATED"
},
"expiryAt": "2021-07-20T12:36:38.049963+01:00",
"isRenewable": false
}
]
If listing 123 is not a Featured Properties (weekly) property, the response will look like this:
[]
Errors
In case of an issue with the request, for example, validation failure, you can expect the JSON response to include details of the error. Example response:
{
"errors": [
"reason": "Internal error interpreting JSON data",
"code": 2011016
]
}
See Featured Properties (weekly) error code register for a complete list of all error codes and their meaning.
Postman collection
To make your start with our API easier, we are providing the Postman collection you can download below.
Questions
If you have any questions related to this tech documentation / API, please contact members@zoopla.co.uk.