Weekly Featured Properties

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 Weekly Featured Properties API enables you to programmatically activate weekly featured properties directly within your internal CRM.

Use the Weekly Featured Properties API to:

📘

Note

This API is being continually improved so the and details provided in this documentation 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)
  • [Errors] (#Errors)
  • [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 weekly featured 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:
709

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

{
  "listingId": 123
}

To activate the weekly featured property product, a unique request must be made for each listing and includes the relevant listingId.

Validation rules:

You cannot request to activate the weekly featured property 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 weekly featured property product is already active for that specific listing
  5. The property is not a residential property
  6. The location of the property is not in the United Kingdom

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 weekly featured property 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 weekly featured property 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 weekly featured property activation for the listingId

{
  "errors": [
    {
      "reason": "There is already a weekly featured property activation pending for this listing ID",
      "code": 2011004
    }
  ]
}

Payload with custom details (weekly featured properties):

{
  "listingId": 123,
  "customDetails": {
    "orderNumber": 456
  }
}

Example response with custom details:

HTTP status of response: 202 Accepted

{
  "id": "f36fa5b1-df2a-4fe1-9a6c-f675d31e8a8d",
  "listingId": 123,
  "createdAt": "2021-07-16T13:59:42.462116906Z",
  "updatedAt": "2021-07-16T13:59:42.462116906Z",
  "createdBy": "34obarelcd7pnjrqff066juicv",
  "status": {
    "result": "PENDING"
  },
  "customDetails": {
    "orderNumber": 456
  },
  "isRenewable": false
}

Get all weekly featured property activations

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

📘

Info

API does not support pagination yet. This is going to be defined

How to check is the listing is activated as a Weekly Featured Property

Using endpoint /products/weekly-featured-properties provides the activation status if a listing without knowing the activation request uuid.

To check if a specific listingId is a weekly featured property, 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 weekly featured 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 weekly featured property, the response will look like this: 

[]

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":"Internal error interpreting JSON data",
      "code":2011016
   ]
}

See Weekly Featured Properties error code register for a complete list of all error codes and their meaning.

Postman collection

To make initial use of the API easier, the Postman collection can be downloaded below:

👍

Postman Collection Download Link

[Download Link] (https://support.zoopla.co.uk/hc/en-gb/article_attachments/360016810997/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 tech documentation / API, please contact [[email protected]] (mailto:[email protected]).

Updated almost 2 years ago