API for portals

# Listing details

# Overview

Listings are created to advertise properties, but unlike other platforms, in Keaze a listing can advertise a single property or a group of properties from the same development.

The listing details will contains all the relevant information, including gallery images, videos, brochures and detailed specifications.

When the listing advertises multiple properties and you want to get the list of properties, you can make an extra call to the API to get that list, or alternatively, you can use a single request to get both, the listing details and the list of properties. When the listing advertises a single property, the details of the property will come in one of the listing fields.

Info

To know if the listings is advertising a single property or multiple properties, check the field singleProperty. If true, the propertyDetails field of the listing details will contain the details for the property de listing is advertising.

# Endpoints

There are two basic endpoints, one to get the listing details and another to get all the properties the listing is advertising, but there are some alternative endpoints to deal with some different scenarios.

To get the listing details use the endpoint:

GET /api/rest/portal/listings/{listing-id}

Where listing-id is the listing reference id.

The same way as when searching listings, below headers are not required, but default values will be used if they are omitted.

Name Possible values Default value
Accept-Version number, indicating the version Last version available
Portal-Id number, indicating the portal id Keaze portal id

Depending on the amount of bedrooms the customer is interested in, you can use the QueryString parameter bedrooms[] to make the listing return the minimum prices based on that parameter. Notice you can request multiple values by repeating the parameter, example:

?bedrooms[]=1&bedrooms[]=2.

To get the list of properties being advertised by the listing (when it's no a single property listing) use the endpoint:

GET /api/rest/portal/listings/{listing-id}/properties

The same specifications for headers and the parameter bedrooms[] apply. When using the parameter bedrooms[], only properties matching the total amount of bedrooms requested will be returned.

# Alternative endpoints

If you want to get the listing details and the list of properties in the same response, you can use the endpoint:

GET /api/rest/portal/listings/{listing-id}/full-details

The response will contain an object with three fields:

  • listing: an object with the listing details
  • properties: the collection of properties. When the listing is singleProperty the collection will be empty.
  • checkEligibility: when true if means that the register interest process will require some extra fields to check the eligibility to the listing or any of its properties. This information can be used to customize the call to action.

There are analogous alternative endpoints for scenarios where you use friendly urls and don't expose the id of the listings, but their slug.

To get the listing details use the endpoint:

GET /api/rest/portal/listings/slug/{listing-slug}

To get the list of properties being advertised by the listing use the endpoint:

GET /api/rest/portal/listings/slug/{listing-slug}/properties

To get the listing details, the list of properties and the field checkEligibility, use the endpoint:

GET /api/rest/portal/listings/slug/{listing-slug}/full-details

Where listing-slug is the listing slug field returned in any of its resources.

Info

For all endpoints available to get listing details, there is support for parameter ignore_visibility. When this parameter is sent with value 1 or true, listings that haven't been published yet can be previewed.

# API response structure

All responses are JSON encoded, and when the request is correct, they will have the following fields.

# Listing fields

When requesting listing details, a JSON containing the following fields will be returned.

Field name Type Nullable Description
id number false Reference Id to use when calling API for details.
name string false Listing name to display.
slug string false Slug to use in friendly urls to identify the listing.
singleProperty boolean false true when the listings is advertising a single property.
propertyDetails object true Object containing the property details when the listing is single property.
schemes array false Array that contains details about the schemes for the listing. Every item is an object containing three fields: text (label of the tag), slug (Slug of the scheme) & color (hexadecimal color value, starting with #)
housingProvider object false Object that contains the id, name, contactEmail and logoUrl of the housing provider that owns the listing.
propertyTypeGroup string false A text with the general property type, which match the facet type. Example: House, Flat.
propertyType string false A text with a more specific property type. Example: Bungalow, Terraced house.
availabilityStatus object false Object that contains the code & name of the availability status. Regardless the occupancy type, there are only 4 possible values. Codes don't depend on the occupancy type, but names do. Codes are: coming-soon, available, under-offer & closed, and they can be used to associate colors to each status.
galleryImages array true Array that contains the image gallery. Every item contains urls for different view ports: largeSize (1080px width), mediumSize (720px width) & thumbnail (360px width), as well as two more fields that could be empty: alternativeText and caption. All images match the aspect ratio 16x9.
videos array true Array that contains videos urls and some extra details like the embed iframe code and the thumbnail image. For some videos there are not available thumbnail images.
brochures array true Array that contains urls to pdf documents.
featured boolean false Featured listing.
forSale boolean false The listing is for sale, otherwise is to rent.
firstDibs boolean false The listing is under a first dibs scheme, where it's only available for Londoners for a period of time.
favourite boolean true The listing is in the customer's favourite list. When there is no signed-in customer, this value will be null.
createdAt string false Date-time when the listing was created.
Address
displayAddress string false The address to display in the listing. The address doesn't contain the postcode.
postcode string true UK postcode for the listing.
localAuthority object true Object with the the local authority details.
latitude number false The latitude where the listing is.
longitude number false The longitude where the listing is.
mapImageUrl string false Map image url with a pin indicating the position of the property, useful if want to show an image instead of calling Google Map.
Descriptions
longDescription string true The full description of the listing.
localAreaName string true Name of the local area.
localAreaDescription string true Description of the local area.
specifications array true Array of objects, where each one contains three fields: name, description and imageUrls
termsAndConditions string true Terms and conditions.
disclaimer string true Disclaimer.
Premises details
newBuild boolean false true is the listing if for new build properties.
bedrooms array false An array containing the different amount of bedrooms of the listing properties. Its values can be altered based on the search filters.
bathrooms array true An array containing the different amount of bathrooms of the listing properties. Its values can be altered based on the search filters.
receptionRooms array true An array containing the different amount of reception rooms of the listing properties. Its values can be altered based on the search filters.
furnitureStatus array true An array containing the different furniture status of the listing properties. Its values can be altered based on the search filters. Possible values are: unfurnished, part-furnished & furnished.
tenure string false Condition on which a property is held: leasehold or freehold.
propertyFeatures array false Array of objects describing all property features. Every object has two fields: section (text with the property feature section, e.g.: Parking ) & values (an array of string, containing all the property features for the section).
For sale
fullMarketPrice number true The minimum full price.
depositPercentage number true The minimum deposit percentage.
depositValue number true The minimum deposit value.
isSharedOwnership boolean false The listing scheme is shared ownership, so there's a share to buy and the rest to rent.
minSharePercentage number true The minimum share percentage if isSharedOwnership.
minShareValue number true The minimum share value if isSharedOwnership.
subsidisedMonthlyRent number true The minimum amount to pay for rent of the part you don't own when isSharedOwnership.
maxGovernmentLoanPercent number true Depending on the scheme, eligible buyers could receive a government loan. In such a case, this value is the maximum government loan percent.
maxGovernmentLoanValue number true The maximum government loan value.
monthlyServiceCharge number true Monthly bill that covers the costs of any repairs or maintenance to the structure of the building, including drainage, insurance and management charges.
annualGroundRent number true Rent to pay annually to the freeholder or landlord of the leasehold property.
reservationFee number true Reservation fee to a developer that allows a buyer to reserve a property for a period.
To rent
monthlyRent number true Monthly rent.
weeklyRent number true Weekly rent.
rentalDeposit number true Rental deposit value.
minTenancyMonths number true Minimum tenancy term in months.
maxTenancyMonths number true Maximum tenancy term in months.
Both: For sale & To rent
administrationFee number true Fee charged by an agency to cover expenses related to record-keeping and/or other.
SEO
headline string false Page headline.
titleTag string false Page html title.
metaKeywords string false Page meta keywords.
metaDescription string false Page meta description.

# Property details fields

When requesting the list of properties in a listing, a JSON object containing the field data will be returned. That field is an array of properties, where each property will have the following structure.

Info

Notice that some fields match the ones in Listing details, and in many cases they are interpreted the same, but some as bedrooms, bathrooms and receptionRooms are not. In property details they are considered as numbers, while in listings they are array of numbers.

Field name Type Nullable Description
id number false Reference Id.
propertyNumber string false Number to identify the property.
schemes array false Array that contains details about the schemes for the listing. Every item is an object containing three fields: text (label of the tag), slug (Slug of the scheme) & color (hexadecimal color value, starting with #)
propertyType string false A text with a more specific property type. Example: Bungalow, Terraced house.
availabilityStatus object false Object that contains the code & name of the availability status. Regardless the occupancy type, there are only 4 possible values. Codes don't depend on the occupancy type, but names do. Codes are: coming-soon, available, under-offer & closed, and they can be used to associate colors to each status.
fullSpecifications string true A full description of the property.
floorplans array false Array containing the property floorplans. Every object has the original image url, the thumbnailUrl, and two more fields that could be empty: alternativeText and caption.
forSale boolean false The property is for sale, otherwise is to rent.
firstDibs boolean false The property is under a first dibs scheme, where it's only available for Londoners for a period of time.
firstDibsExpirationDate string true If the property is firstDibs the first dibs expiration date. When the property availability status is coming soon, this date could be null.
Premises details
newBuild boolean false true if the property is new build.
bedrooms number false Total number of bedrooms.
bathrooms number false Total number of bathrooms.
receptionRooms number true Total number of reception rooms.
furnitureStatus string true unfurnished, part-furnished or furnished.
floorArea number true Floor are in square meters.
rooms array No Collection of property rooms (empty if none). Every item has: name, additionalDetails, units (foot or metre), width, length and floorArea. Name and additional details are free texts, up to 255 chars length, while width, length and floorArea are numbers expressed in the provided units. Only name and units are required.
numberOfFloors number true Total number of floors the property has.
floor object true Entrance floor. Object containing: name and level. name is a readable text that usually ends with the word floor, like Ground floor or Basement, while level is the corresponding level number for the floor that can be used for sorting purposes, example 0 for Ground floor, -2 for Basement and 3 for 3rd floor. for sorting purposes
tenure string false Condition on which a property is held: leasehold or freehold.
leaseYears number true When the tenure is leasehold, the number of year the lease lasts.
propertyFeatures array false Array of objects describing all property features. Every object has two fields: section (text with the property feature section, e.g.: Parking ) & values (an array of string, containing all the property features for the section).
energyEfficiencyRatingCurrent number false Integer number less or equal than 100, that reflects the Energy rating for the property. When it's a new build property, this value will be the Predicted energy rating, otherwise it will be the Current energy rating
energyEfficiencyRatingPotential number false Integer number less or equal than 100, that reflects the Potential energy rating for resale properties (not new build).
environmentalImpactRatingCurrent number false Integer number less or equal than 100, that reflects the Environmental impact rating for the property. When it's a new build property, this value will be the Predicted environmental impact rating, otherwise it will be the Current environmental impact rating
environmentalImpactRatingPotential number false Integer number less or equal than 100, that reflects the Potential environmental impact rating for resale properties (not new build).
For sale
fullMarketPrice number true The minimum full price.
depositPercentage number true The minimum deposit percentage.
depositValue number true The minimum deposit value.
isSharedOwnership boolean false The property scheme is shared ownership, so there's a share to buy and the rest to rent.
minSharePercentage number true The minimum share percentage if isSharedOwnership.
minShareValue number true The minimum share value if isSharedOwnership.
subsidisedMonthlyRent number true The minimum amount to pay for rent of the part you don't own when isSharedOwnership.
maxGovernmentLoanPercent number true Depending on the scheme, eligible buyers could receive a government loan. In such a case, this value is the maximum government loan percent.
maxGovernmentLoanValue number true The maximum government loan value.
monthlyServiceCharge number true Monthly bill that covers the costs of any repairs or maintenance to the structure of the building, including drainage, insurance and management charges.
annualGroundRent number true Rent to pay annually to the freeholder or landlord of the leasehold property.
reservationFee number true Reservation fee to a developer that allows a buyer to reserve a property for a period.
To rent
monthlyRent number true Monthly rent.
weeklyRent number true Weekly rent.
rentalDeposit number true Rental deposit value.
minTenancyMonths number true Minimum tenancy term in months.
maxTenancyMonths number true Maximum tenancy term in months.
Both: For sale & To rent
administrationFee number true Fee charged by an agency to cover expenses related to record-keeping and/or other.

# Understanding prices fields

Although listings and properties bring all available prices fields, their use depends on the occupancy type and the schemes.

Warning

As Keaze is an update of a legacy system where any of the price fields could be null; some or even all the relevant prices fields could be null. In those cases those values should be treated as TBA (To be announced).

There are two different occupancy types: For sale or To rent. The listing and property details always contain the field forSale, which will be true when the occupancy type is For sale, otherwise is To rent.

# For sale fields

There are basically, regarding the prices fields, three different cases for sale properties:

  • Standard: There's a fullMarketPrice, and to buy the property, it's necessary to pay a depositValue.
  • Shared ownership: There's a share to buy and the rest to rent. The minimum share to buy is returned in the field minSharePercentage and the amount (computed from the full market price) is returned in minShareValue. The monthly rent for the rest is returned in the field subsidisedMonthlyRent. The depositValue is usually lower, because it's computed against the price for the share to buy.
  • The buyer can receive a government loan: It behaves like the Standard case, but field maxGovernmentLoanPercent will contain the percent of the government loan (usually 20 or 40, depending if the property is in London or not), and maxGovernmentLoanValue the amount it represents out of the fullMarketPrice.

When it has the behavior of Shared ownership, the flag isSharedOwnership will be true.

When buyers could receive a government loan, and fullMarketPrice is null, maxGovernmentLoanValue will be also null.

There are other fields that don't depend on the schemes, like:

  • monthlyServiceCharge: Monthly bill that covers the costs of any repairs or maintenance to the structure of the building, including drainage, insurance and management charges.
  • annualGroundRent: Rent to pay annually to the freeholder or landlord of the leasehold property. Notice this field only make sense when tenure is leasehold.
  • reservationFee: Reservation fee to a developer that allows a buyer to reserve a property for a period.
  • administrationFee: Fee charged by an agency to cover expenses related to record-keeping and/or other.

# To rent fields

There's no different cases for properties to rent.

The most important value is monthlyRent, but sometimes is a good idea to display the weeklyRent too, which is a computed value. rentalDeposit, minTenancyMonths and maxTenancyMonths are usually no specified by the housing providers.

administrationFee is the other relevant field for properties to rent, but it's not either common for housing providers to set this value.

# Displaying EPC charts

EPC stands for Energy Performance Certificates. They are documents that contain information about a property’s energy use and typical energy costs, as well as recommendations about how to reduce energy use and save money.

They gives a property an energy efficiency rating from A (most efficient) to G (least efficient), and provide a little colored chart which shows how well the property is rated in terms of energy efficiency.

Instead of uploading the EPC charts images or documents, Keaze generates the charts from the numerical values, for both, the energy rating and the environmental impact rating.

For new build properties, the numerical value is considered as a predicted value, while for resale properties, two values are possible, the first one is the current value, and the second one, if provided, is the potential value.

Example of the Energy Efficiency Rating chart Image

Example of the Environmental Impact Rating chart Image

← Register interest →