Retrieving Advertising Data - V4 Advertising API

The following article should outline how to extract marketing data to allow advertising properties on a website using the API. This information may be best shared with your website developer. For more information on V4 Advertising API please see the below guides:

V4 API Tier Overview

How to Request an API Key

For additional support in advertising using our API, please contact [e-mail]. You can also contact us directly with your developer for us to assist them directly.

Accessing Branch ID

Most endpoints in the Advertising API require a branch ID in order to retrieve data. In order to retrieve the Branch ID, you will need to run the following endpoint located in the Company Controller:

GET /v4/advertising/{shortName}/company/branches/{offset}/{count}

You will need to retain the value of the OID field for the branch you will want to search against in any other endpoints.

Retrieving Lettings Advertising Data

Retrieving lettings from the API is a multi-step process. All endpoints for downloading data for lettings can be found within the LettingsController.

Lettings Summary

The first step will be to retrieve the summary of all the lettings. This can be done by executing the following endpoint:

GET /v4/advertising/{shortName}/lettings/advertised/{offset}/{count}

The above endpoint will return high level summary information for every tenancy in the system. This should provide you with enough information to populate a property snapshot on a search page. It is a good idea to run this API at set intervals (such as an overnight feed) and cache the results.

At the time of writing, the data populated in the model will be the following fields:

• OID
• ETag
• GlobalRefrence
• BranchOID
• AreaOID
• PropertyID
• IsTenancyProposed
• TermStart
• RentAdvertised
• TenantSystemTypes
• Furnished
• IsShareProperty
• IsStudentProperty
• MaximumTenants
• TermMinimum
• Address1
• Address2
• Address3
• Address4
• Postcode
• MainPhotoOID

Full Lettings Data

To retrieve the full tenancy information you will need to retain the OID from the Lettings Summary call, and execute the following endpoint:

GET /v4/advertising/{shortname}/lettings/advertised/{tenancyID}

This will return the same response model as the summary, however the model will be fully populated with all the data present in the system.

Property Data

Having retrieved information surrounding the letting, you will now be able to retrieve information regarding the property. To do so, you will need to retain the PropertyID which can be passed into the following endpoints:

GET /v4/advertising/{shortname}/lettings/properties/{propertyID}

This endpoint will allow you to retrieve the information surrounding the property associated with the tenancy.

GET /v4/advertising/{shortname}/lettings/properties/{propertyID}/facilities/{offset}/{count}

This endpoint will allow you to retrieve a collection of all the facilities set up on a property.

GET /v4/advertising/{shortName}/lettings/properties/{propertyID}/rooms/{offset}/{count}

This endpoint will allow you to retrieve a collection of all the rooms set up on the property, in the order they are set up on the property in the system.

GET /v4/advertising/{shortName}/lettings/properties/{propertyID}/photos/{offset}/{count}

This endpoint will return a collection of all the photos set up against a property in the system. (Please note this only contains information surrounding the photos, in order to have the images appear, they will need to be downloaded through the API, more information regarding how to do so can be found at the bottom of the article).

Retrieving Sales Advertising Data

Retrieving sales advertising data has similar steps to retrieving lettings data. All endpoints surrounding retrieving sales advertising data can be found under the SalesController.

Sales Summary

The first step will be to retrieve the summary of all the sales instructions. This can be done by executing the following endpoint:

GET /v4/advertising/{shortName}/sales/advertised/{offset}/{count}

The above endpoint will return high level summary information for every sales instruction in the system. This should provide you with enough information to populate a property snapshot on a search page. It is a good idea to run this API at set intervals (such as an overnight feed) and cache the results.

At the time of writing, the data populated in the model will be the following fields:

• OID
• ETag
• GlobalReference
• MainPhotoOID
• AddressNumber
• Address1
• Address2
• Address3
• Address4
• Postcode
• Price
• Description
• Area
• PropertyOwnableType
• VideoURL
• POA
• SalesBy

Full Sales Data

To retrieve the full sales data information you will need to retain the OID from the Sales Summary call, and execute the following endpoint:

GET /v4/advertising/{shortName}/sales/salesinstructions/{salesInstructionID}

This will return the same response model as the summary, however the model will be fully populated with all the data present in the system.

Property Data

Having retrieved information surrounding the letting, you will now be able to retrieve information regarding the property. To do so, you will need to retain the OID from the sales data calls which can be passed into the following endpoints:

GET /v4/advertising/{shortName}/sales/salesinstructions/{salesInstructionID}/features/{offset}/{count}

This endpoint will retrieve a collection of all the features set up on a sales instruction.

GET /v4/advertising/{shortName}/sales/salesinstructions/{salesInstructionID}/floorplans/{offset}/{count}

This endpoint will allow you to retrieve a collection of floor plans set up on the sales instruction. (Please note this only contains information surrounding the photos, in order to have the images appear, they will need to be downloaded through the API, more information regarding how to do so can be found at the bottom of the article).

GET /v4/advertising/{shortName}/sales/salesinstructions/{salesInstructionID}/rooms/{offset}/{count}

This endpoint will return a collection of all the rooms set up on a sales instruction.

GET /v4/advertising/{shortName}/sales/salesinstructions/{salesInstructionID}/photos/{offset}/{count}

This endpoint will return a collection of all the photos set up on a sales instruction. (Please note this only contains information surrounding the photos, in order to have the images appear, they will need to be downloaded through the API, more information regarding how to do so can be found at the bottom of the article).

Downloading Data

Photos, EPC certificates, and brochures all need to be downloaded from the system in order to be usable on a website. All the download requests can be found in the DownloadsController.

Downloading Photos

To download a photo through the API, you will need to retain the photo’s OID and the pass it into the following endpoint:

GET /v4/advertising/{shortName}/download/{photoID}

This will return a HTTP response that will download the image file from the system. You will need to link the website to where the file is downloaded to in order to show it.

Download EPC Certificates

To download EPC Certificates, you will either need to retain the PropertyID for a letting’s EPC, or the sales instruction’s OID for for a sales instruction’s EPC. When you have this ID, you will need to pass it into the following endpoint:

GET  /v4/advertising/{shortName}/download/{OID}/epc/{graphType}

This will return a HTTP response that will download the EPC file from the system. You will need to link the website to where the file is downloaded to in order to show it. graphType can be set to download EnergyEfficiency or EnvironmentalImpact to get the desired EPC Certificate.

Download Brochure

A brochure can be downloaded for a tenancy or sales instruction by retaining the tenancy’s OID or the sales instruction’s OID. This OID can then be passed into the following endpoint:

GET /v4/advertising/{shortName}/download/{OID}/brochure

This will return a HTTP response that will download the brochure file from the system.