Premium Listings - Tech documentation

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 Premium Listings API enables you to programmatically activate premium listings directly within your internal CRM. 

Use the Premium Listings API to: 

• Activate the premium listings product, subject to available credits
• Check if a listing has a premium product activated
• Get a history of your premium listings product activations 

This article includes: 

• Prerequisites
• Authentication
• Working with the API
• How to check if the listing is premium
• Highlights update
• Errors
• 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 listings product you specified is now line 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 request payload and responses as shown in the sequence diagram above. 

Request premium listings activation - request [004]

Method: POST

Path:  /products/premium-listings

Payload:

 {
           "listingId": 123
 }

To activate the premium listings product, a unique request must be made for each listing and include the relevant listingId , highlights being an option property. 

Payload with option 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 listings 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 listings 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/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 listings 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 listings 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 listings activation from the listingId :

 { 
       "errors": [ 
           { 
               "reason": "There is already a premium listing pending for this listing ID", 
               "code": 1011004 
           } 
       ] 
 }

Get all premium listings activations

There is also an endpoint which allows you to get all requests to activate the premium listings 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 case, parameters are connected with logical AND . Further information on how to use parameters can be found below:

Example request: /products/premium-listings?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" 
    } 
 ]

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.

Example 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 Listings activation.

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": "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 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 technical document / API, please contact members@zoopla.co.uk.