Premium Listings

Suggest Edits
968

An application programming interface (API) is a computing interface that 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, and the conventions to follow.

The Premium Listings API enables you to programmatically activate premium listings directly within your internal CRM.

Use the Premium Listings API to:

📘

Info

This API is being continually improved and so details in this article are subject to change

This article includes:

  • [Prerequisites] (#prerequisites)
  • [Authentication] (#authentication)
  • [Working with the API] (#working-with-the-api)
  • [How to check if the listing is premium] (#how-to-check-if-the-listing-is-premium)
  • [Highlights update] (#highlights-update)
  • [Questions] (#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 Premium Listings API is to set up authentication for your client. Please follow the steps in Authentication - Tech Documentation to configure authentication.

Working with the API

This API is asynchronous. What does this mean? When you make a request to activate a premium listing, we validate the request and place it in a queue for further processing, returning to a status of PENDING.

Once processed, there are two possible statuses:

  • ACTIVATED which means the premium listing product 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:
746

Available endpoints

Below you will find details about the request payload and responses as shown in the sequence diagram above.

Method: POST

Path: /products/premium-listings

Payload:

{
   "listingId":123
}

To activate the premium listing product, a unique request must be made for each listing and includes the relevant listingId , highlights which is an optional property.

Payload with optional highlights (premium listings):

{
   "listingID":123,
   "highlights":[
      {
         "id":456,
         "description":"optional text description of highlight"
      }
   ]
}

A list of valid highlight ID's can be found here: Premium Listings Highlights chart

Example response with highlights:

HTTP status of response: 202 Accepted

{
   "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"
   },
   "highlights":[
      {
         "id":456,
         "description":"optional text description of highlight"
      }
   ]
}

Validation rules:

You cannot request to activate the premium listing product in the event:

  1. The listingId doesn't exist or is invalid
  2. The client doesn't have access to the listing
  3. A listingId has an activation status of PENDING
  4. The premium listing product is already active for that specific listing

Example cURL request: :

 curl --location --request POST 'https://services.zoopla.co.uk/products/premium-listings' \ 
 --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 premium listing activation - request [008]

Path: /products/premium-listings/{premiumListingUUID}
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"
   }
}
  • 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"
}
  • When a request is completed but there was a problem during premium listing 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":1011011
         }
      ]
   }
}
  • When there is already a pending premium listing activation from the listingId :
{
   "errors":[
      {
         "reason":"There is already a premium listing pending for this listing ID",
         "code":1011004
      }
   ]
}

Get all premium listing activations

There is also an endpoint that allows you to get all requests to activate the premium listing product the user has access to.

Method: GET

Path: /products/premium-listings

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"
      }
   },
   {
      "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"
   }
]

You can narrow the number of objects in the array by providing query parameters:

  • listingId - return only activation request related to the given listingId
  • isPremium - return only activations which are currently effectively active

Both parameters can be combined in one request, and in such a case, parameters are connected with logical AND. Further information on how to use parameters can be found below:

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

📘

Note

The API does not yet support pagination.

How to check if the listing is premium

Using endpoint /products/premium-listings provides the activation status of a listing without knowing the activation request uuid.

The check if a specific listingId is premium, the following request can be used:

GET https://services.zoopla.co.uk/products/premium-listings?listingId=123&isPremium=true

If listing 123 is premium 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"
   }
]

If listing 123 is not premium the response will look like this: 

[]

Highlights update

API allows highlights updating. To perform this operation you should make the PATCH request.

PATCH https://services.zoopla.co.uk/products/premium-listings/{premiumListingUUID}

Example request body:


{
   "highlights":[
      {
         "id":42
      }
   ]
}

Response:

[
   {
      "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",
         "currently":"WAITING_FOR_UPDATE"
      },
      "expiryAt":"2021-07-20T12:36:38.049963+01:00"
   }
]

The request is asynchronous and after a while (usually, it takes less than 1 second) you can make the GET request to retrieve the current (updated) representation of the Premium Listing activation.

Errors

In case of an issue with the request, for example, a validation failure, the JSON response would include details of the error. Example response:

{
   "errors":[
      "reason":"Not enough credits",
      "code":1011234
   ]
}

A list of all error codes and their meanings can be found here: Premium Listings error code register

Postman collection

To make initial use of the API easier, the Postman collection has been provided below:

View: https://support.zoopla.co.uk/hc/en-gb/article_attachments/360016811117/Products-API.json

Limitations

❗️

You can not immediately upgrade a listing after it's submission

Once you submit a listing to Zoopla it is subjects to some checks and while it is processed the does not have an associated Zoopla specific identifier. Until the listing has an associated identifier it is not possible to upgrade a listing to premium. Typically this lag will not be more than a few minutes for API and Zoopla Pro submissions. But we advise users of our api to delay attempting to upgrade their listing for at least 30 minutes from the time of submission.

Questions

If you have any questions related to this technical document / API, please contact [[email protected]] ([email protected]).

Updated almost 2 years ago