openapi: 3.0.1
tags:
- name: Property
description: Create, Updated, Remove and Retrieve properties
info:
title: Commercial Listings API
description: |
## Overview
The Commercial Listings API allows you to upload, update, retrieve, and remove Commercial property listings for display on the Rightmove website.
It is designed for use by Commercial Agents and Feed Providers integrating with the Rightmove platform.
### Purpose
This API enables the management of commercial listings only. It supports:
- Uploading new listings
- Updating existing listings (based on the reference field)
- Retrieving and removing listings
⚠ Residential listings are not supported by this API. These must continue to be uploaded via the Rightmove Real Time Data Feed API.
---
### Property Scope
- This API supports commercial property listings only.
- Residential properties should still be uploaded using the **Rightmove Real Time Data Feed APIs**.
- If your branch uploads both commercial and residential properties, you must use the appropriate API per property type.
---
### Environments
#### Api-test environment
- Used for development and testing.
- Requires test credentials issued by the Rightmove Data Feed Team (email: adfsupport@rightmove.co.uk).
- Listings submitted here will not appear on the live website.
#### Production environment
- Used for live listings visible to consumers on the Rightmove site.
- Requires separate production credentials, also provided by the Rightmove Data Feed Team.
- To begin uploading for a new branch, please contact the Data Feed Team who will support you through setup and testing.
---
### Authentication
All endpoints require authentication using OAuth2 client credentials.
Credentials must be supplied by the Rightmove Data Feed Team.
Visit the [authentication page](/authentication) for implementation details.
---
### Versioning
This API follows semantic versioning (major.minor.patch):
- **Major:** Breaking changes (client updates required)
- **Minor:** Backwards-compatible enhancements
- **Patch:** Bug fixes or documentation updates (no structural changes)
Please ensure your integration is resilient to additional fields being returned.
---
### Property-upload visibility guidelines
#### Why this matters
Rightmove treats every feed item as something you want marketed. Uploading “draft” or inactive stock generates confusing enquiries for Consumers and Partners.
Follow the rules below to keep your live inventory clean and compliant.
| **Rule** | **What to do** | **What happens if you break it** |
|------|------------|-------------------------------|
| **1. Upload only properties you want on Rightmove** | Send through live listings only — i.e. anything you are happy to display publicly and receive leads for. | Off-market stock clutters the feed and will be rejected in future platform updates. |
| **2. Use an approved status** | Set the status field to one of the six values below (case-sensitive): AVAILABLE, SOLD_STC, SOLD_STCM, RESERVED, LET_AGREED, UNDER_OFFER | Any other value (e.g. SOLD_BY_US) triggers an automatic published =false flag, hiding the listing from search. |
| **3. Keep status & marketing intent aligned** | If a property’s internal CRM status implies it is no longer marketable (e.g. "completed" or "withdrawn"), either stop sending it or switch the feed status to one of the permitted inactive values above. | Mismatched statuses are auto-corrected to invisible. |
**Tip:** You can always re-activate a hidden listing by resending it with a compliant status and published=true.
Additional scenario: Managing visibility for buildings and their spaces
If a building is unpublished — either when it is first created or later updated with published=false — all associated spaces within that building will also automatically be set with published=false.
To re-publish the building, you can send it again with published=true. However, each space within the building will also need to be explicitly updated with published=true in order to be visible on the platform. This ensures that only intended spaces are marketed alongside the property.
#### Removing a Property
If a property should be removed from Rightmove, you can permanently remove it via the DELETE endpoint.
- Use the DELETE /v2/property/commercial/{reference} endpoint to remove the listing.
- When deleting, you must also provide a removalReason to indicate why the property is being removed.
- Once deleted, the property will no longer appear on Rightmove and will not be returned in future API queries. Note that this action will also remove any associated listings from Rightmove.
---
### Media Handling
The API supports various types of media for your commercial property listings, including photos, floor plans, EPCs (Energy Performance Certificates), EPC graphs, brochures, and virtual tours.
- Structure: Media is submitted within the building.media or building.spaces[].media objects. Each media type (e.g., photos, floorPlans) is an array of MediaAsset objects.
- MediaAsset Object: Each MediaAsset requires:
- url: A publicly accessible URL to the media file.
- Important for Brochures: URLs for brochures must end with a .pdf extension.
- description (optional): A brief description of the media asset (max 200 characters).
- order (optional): An integer to define the display order of assets within its type.
- Schema: Refer to the Media and MediaAsset schemas in the API Specification
ETag Recommendation: To optimize media downloads and reduce unnecessary data transfer, the API performs an ETag (Entity Tag) check via a HEAD request before downloading media resources.
It is highly recommended that your media asset URLs support and return an ETag HTTP header. This allows our system to fetch the asset only if it has changed since the last retrieval.
---
### Reference Field
We use the reference field to determine whether a property is new or existing:
- If a listing is uploaded with a new reference, it is treated as a new listing.
- To update an existing listing, submit the same reference value.
---
### Model Change
As of v1.2.3, the API supports the ability to change a Property's model from BUILDING to SPACE. This is useful if you initially uploaded a property as a standalone building but later decide to market individual spaces within that building.
Please ensure the following:
- Space Listings: When changing to the SPACE model, you must remove the existing model BUILDING object in the spaces array and create new space objects for each individual space you want to market within the building.
- Reference Consistency: The reference supplied at the path for the Building must remain the same when changing to Space. This ensures the existing property is updated to match the new model.
- Space Reference Uniqueness: Each space within the building must have a unique reference that is different from the building's reference (the one provided at the path). This prevents conflicts and ensures each space can be individually identified.
⚠ It is worth noting that whilst a BUILDING can be converted to a SPACE, the reverse is not currently supported. At present, if you need to change from SPACE back to BUILDING, you must first delete the existing property and then re-upload it with the BUILDING model.
---
### Asynchronous Processing
Our system is asynchronous, meaning changes (including uploads and removals) may take some time to reflect on the live website.
---
### Unsupported Features
The following are not currently supported by this API:
- Uploading or removing products (e.g. featured property and premium listing)
- Uploading residential property listings
- Sending error reports via email
- Setting property availability beyond core commercial statuses
---
### Error Handling
The API uses standard HTTP status codes to indicate the success or failure of an API request.
- 2xx Success Codes: Indicate that the request was successfully received, understood, and accepted (e.g., 200 OK, 201 Created).
- 4xx Client Error Codes: Indicate an error that seems to have been caused by the client (e.g., 400 Bad Request for malformed syntax or validation errors, 401 Unauthorized for missing/invalid credentials, 403 Forbidden for insufficient permissions, 404 Not Found if a resource doesn't exist, 429 Too Many Requests for rate limiting).
- 5xx Server Error Codes: Indicate an error on our side (e.g., 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable). If you consistently receive these errors, please contact the Rightmove Data Feed Team.
#### Problem Details:
For 4xx and 5xx error responses, the API will generally return a body in the JSON ProblemDetail format. This provides more specific information about the error.
Schema: Refer to the ProblemDetail schema in the API Specification
Key Fields:
- type: A URI identifier for the problem type.
- title: A short, human-readable summary of the problem type.
- status: The HTTP status code.
- detail: A human-readable explanation specific to this occurrence of the problem.
- instance: A URI reference that identifies the specific occurrence of the problem.
- properties: An optional object containing additional details. This may include:
- traceId: A unique identifier for the request, useful for support.
- timestamp: The time the error occurred.
- validationError (for 400 Bad Request): Contains specifics about validation failures, often including the field and message.
---
### Rate Limiting
To ensure fair usage and stability of the API for all clients, requests are subject to rate limiting.
- Response Code: If you exceed the number of allowed requests within a given time window, the API will respond with an HTTP 429 Too Many Requests status code.
- Quota Reset: The quota resets every 60 seconds. The specific number of allowed requests (the quota value) may vary per environment (e.g., staging vs. production) and per endpoint.
- Retry Strategy: If you receive a 429 response, your application should wait before retrying the request. Implementing an exponential backoff strategy for retries is recommended.
- Headers: While not explicitly detailed in the OpenAPI for this endpoint, APIs often include headers in 429 responses like Retry-After (indicating how long to wait before retrying) or headers detailing current rate limit status (e.g., X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). Check the response headers for any such information.
Please design your integration to handle 429 responses gracefully. If you anticipate needing higher rate limits, please contact the Rightmove Data Feed Team.
---
### Support
For access credentials or onboarding support, please contact the Rightmove Data Feed Team: adfsupport@rightmove.co.uk
---
### Changelog
#### v2.1.6 -- 2026-06-23
##### Changed
* Added subtype BUSINESS_PARK as a valid value for Offices property classification
* Added subtype SHOWROOM as a valid value for Retail property classification
* Added subtype TAKEAWAY as a valid value for Leisure And Hospitality property classification
* Added subtype WORKSHOP as a valid value for Industrial and Logistics property classification
#### v2.1.5 -- 2026-06-22
##### Changed
* `keyFeatures` is now optional at building level.
#### v2.1.4 -- 2026-05-22
##### Changed
* Renamed schemas to clearly distinguish building-level and space-level objects:
* `Pricing` renamed to `SpacePricing`
* `Sizing` renamed to `SpaceSizing`
* `PriceDisplayQualifier` renamed to `SpacePriceDisplayQualifier`
* Fixed the `CommercialPropertyWithSpaces` PUT schema so that building-level pricing references `BuildingPricing` (previously incorrectly referenced the space-level `Pricing`).
* Clarified pricing and sizing descriptions to make the validation rules explicit:
* `BuildingPricing` is mandatory at the building level.
* `SpacePricing` is optional at the space level.
* `BuildingSizing` is optional and now correctly refers to the building rather than the space.
* `SpaceSizing` is mandatory for every space, with `size` and `unit` required.
#### v2.1.3 -- 2026-01-07
##### Changed
* An additional field, `auction`, has been added to the building object to indicate whether the property is an auction property. This applies only to SALES listings. The field is optional and defaults to `false` if not provided.
#### v2.1.2 -- 2025-12-03
##### Changed
* INDUSTRIAL_DEVELOPMENT is removed from LAND_AND_DEVELOPMENT property classification and any existing properties with this subtype will be mapped to COMMERCIAL_DEVELOPMENT.
* AEROSPACE subtype has been removed from OTHER property classification
* FARM subtype has been moved to LAND_AND_DEVELOPMENT property classification from OTHER property classification
* Added WOODLAND subtype as a valid value for LAND_AND_DEVELOPMENT property classification
* Added subtypes DENTAL_CARE, PHARMACY and CARE_HOME_FACILITY as valid values for OTHER property classification
#### v2.1.1 -- 2025-11-12
##### Changed
* Added subtypes CAMPSITE_HOLIDAY_VILLAGE, COMM_GUEST_HOUSE as valid values for Leisure And Hospitality property classification
* Added subtypes POST_OFFICE, CONVENIENCE_STORE as valid values for Retail property classification
#### v2.1.0 -- 2025-11-07
##### Changed
Version 2.1.0 of the Commercial Listings API is now available.
We’ve restructured the API to make it simpler and easier to integrate with.
* All building-related fields should now be provided in the Building object.
* All space-related fields should now be provided in the Space object.
To upload a building, use this PUT schema: #/components/schemas/CommercialPropertyBuildingOnly
To upload a building with spaces, use this PUT schema: #/components/schemas/CommercialPropertyWithSpaces
##### What’s Changed
* The Space object is now optional — include this object only if you want to display a floor or unit within a building.
* Additional fields have been added to the Building object:
* status
* availableDate
* businessRates
* serviceCharge
* isRentAllInclusive
* letType
* letContractLength
* condition
* We will be deprecating and removing the following fields — please do not send these fields going forward:
* constructionType in the Building object
* model in the Space object
* PriceDisplayQualifier enum - the following values are supported:
* Space level only :
* NONE("~")
* PRICE_ON_APPLICATION("POA")
* Property (building) level only:
* NONE("~")
* PRICE_ON_APPLICATION("POA")
* GUIDE_PRICE("Guide Price ~")
* OFFERS_IN_EXCESS_OF("Offers in Excess of ~")
* OFFERS_IN_REGION_OF("Offers in Region of ~")
* FROM("From ~")
##### Recommendation:
We recommend that all new customers adopting the updated API structure begin including the new fields immediately.
#### v2.0.3 -- 2025-11-20
##### Changed
* Updated Pricing description.
#### v2.0.2 -- 2025-10-20
##### Changed
* Added ability to change a Property's model from BUILDING to SPACE. See the "Model Change" section above for details.
* Added the ability to provide pricing information at the building level.
#### v2.0.1 -- 2025-10-10
##### changed
* Added showStreetView field to the streetView object
#### v2.0.0 -- 2025-10-09
##### Breaking change
* Removed COMMERCIAL and STUDENT values from LetType field
#### v1.2.3 -- 2025-10-08
##### Changed
* Updated documentation for GET endpoint
#### v1.2.2 -- 2025-08-06
##### Changed
* Enforced validation against reference for SPACE and BUILDING model. When model is SPACE, than the reference must be unique for each space and different from the one used in the request url.
When model is BUILDING, then the reference must be equal to the one used in the request url.
#### v1.2.1 -- 2025-07-03
##### Changed
* Adding WAREHOUSE and SELF_STORAGE as valid values for the subType field for Industrial and Logistics property classification
#### v1.2.0 -- 2025-06-10
##### Changed
* Added optional minSize and maxSize fields to the sizing object on building
#### v1.1.6 -- 2025-06-09
##### Changed
* Allowing maximum of 50 spaces per building
#### v1.1.5 -- 2025-06-04
##### Changed
* Added remove Property section to the documentation
#### v1.1.4 -- 2025-05-29
##### Changed
* Added more information around the visibility guidelines for commercial properties
#### v1.1.3 -- 2025-05-27
##### Changed
* Removed the following statuses from the documentation - SOLD_BY_US, SOLD_BY_ANOTHER_AGENT, WITHDRAWN_FROM_MARKET, LOST_INSTRUCTION, REMOVED and LET_BY_US
#### v1.1.2 -- 2025-05-22
##### Changed
* Fixed style issues in the documentation
#### v1.1.1 -- 2025-05-21
##### Changed
* Updated introduction and authentication content
#### v1.1.0 -- 2025-05-08
##### Changed
* Release of version 1.1.0
* Retrieve properties by Branch endpoint added
#### v1.0.0 -- 2025-04-16
##### Changed
* Release of version 1.0.0
#### v0.6.1 -- 2025-04-03
##### Changed
* Changed measurement type field to be optional
#### v0.6.0 -- 2025-04-03
##### Changed
* Removed WEEKLY, DAILY, QUARTERLY from RentFrequency
#### v0.5.1 -- 2025-04-02
##### Changed
* Added SHOP as a valid value for the subType field for Retail property classification
* Added CAFE as a valid value for the subType field for Leisure And Hospitality property classification
* Added LIFE_SCIENCES_LABS as a valid value for the subType field for Other property classification
#### v0.5.0 -- 2025-04-01
##### Changed
* Added TRADE_COUNTER as a valid value for the subType field
* Split IPMS3 in to IPMS3_1 and IPMS3_2 in measurementType field
* Updated buildingIdentifier to be a maximum of 100 characters rather than 50
#### v0.4.0 -- 2025-03-13
##### Changed
* EPC rating field changed to accept values up to 500 to accommodate ESG credentials
#### v0.3.0 -- 2025-03-10
##### Changed
* Improved validation error messages to be more descriptive
* The following fields moved from mandatory to optional:
* Use Class
* Amenities
* Available Date
* EPC rating field changed to accept values up to 120 to accommodate ESG credentials
#### v0.2.0 -- 2025-03-03
##### Changed
* businessRate renamed to businessRates in order to match industry terminology
* The following fields moved from mandatory to optional:
* EPC rating
* Minimum/Maximum capacity
* Business Rates
* Added optional order field to space object to allow for ordering of spaces in a building.
#### v0.1.0 -- 2025-02-21
##### Changed
* Fix spelling of METERS to METRES with the Clear Height Unit field
* Fix spelling of yardDepthMeters to yardDepthMetres within the industrial and logistics classification
##### Fixed
* Documentation Update - Add missing response codes to the delete request
* Documentation Update - Fix spelling mistake with rent obligation allowed values
* Documentation Update - Ensure examples are clearer
* Documentation Update - Ensure specification values are generated using enumerated data when using testing tools
* Documentation Update - Update terms of service and licence links
---
### Upload Commercial Property
Submit details of new commercial properties, including offices, retail
units, warehouses, leisure and land, exclusively within the UK market.
---
### Update Commercial Property
Update details of commercial properties, including offices, retail
units, warehouses, leisure and land, exclusively within the UK market.
---
### Remove Commercial Property
Removes details of commercial properties, taking the reason for the removal.
---
### Retrieve Property Details
Retrieve information about your commercial properties for reconciliation and data referencing.
version: 1.0.0
termsOfService: https://api-docs.rightmove.co.uk/terms
contact:
email: adfsupport@rightmove.co.uk
name: Rightmove Data Feed Team
license:
name: Please refer to the End User License Agreement
url: https://api-docs.rightmove.co.uk/terms
servers:
- url: https://api-services.adftest.rightmove.com
description: Staging
- url: https://api-services.rightmove.co.uk
description: Production
paths:
/v2/property/commercial/{reference}:
get:
tags:
- Property
security:
- OAuth2: []
summary: Gets a Commercial Property (UK Only)
description: Gets a Commercial Property (UK Only)
operationId: getCommercialPropertyDetails
parameters:
- name: reference
in: path
description: The reference identifier of the property to retrieve.
required: true
schema:
type: string
- name: Rightmove-Agent-ID
in: header
description: The Agent ID associated with the property.
required: true
schema:
type: integer
format: int64
responses:
"503":
description: This response will be presented when an unexpected internal
error has occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"200":
description: Property is found and the response object will include all
the property details.
content:
application/json:
schema:
$ref: "#/components/schemas/PropertyAction"
"502":
description: "This response will be presented when an unexpected error has\
\ occurred, this is most likely to do with a client error. The user will\
\ be prompted to try again."
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"400":
description: This response will be presented when a validation error has occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"401":
description: This response will be presented when the attempt to call is
unauthorised.
content:
application/json: { }
"403":
description: This response will be presented when the attempt to call is
forbidden.
content:
application/json: { }
"429":
description: This response will be presented when your quota has been exceeded.
The quota resets every 60 seconds and the value varies per environment
content:
application/json: { }
put:
security:
- OAuth2: []
tags:
- Property
summary: Sends Commercial Properties (UK Only)
description: Upload or update commercial properties
operationId: sendCommercialPropertyDetails
parameters:
- name: reference
in: path
description: The reference of the property. This must be the same provided at space level, when the property defines a building with no spaces.
required: true
example: 'Property_Reference_123'
schema:
type: string
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: "#/components/schemas/CommercialPropertyWithSpaces"
- $ref: "#/components/schemas/CommercialPropertyBuildingOnly"
required: true
responses:
"200":
description: Successfully updated a property and the response contains metadata
about the update action.
content:
application/json:
schema:
$ref: "#/components/schemas/PropertySaveAction"
"201":
description: Successfully created a property and the response contains metadata
about the create action.
content:
application/json:
schema:
$ref: "#/components/schemas/PropertySaveAction"
"503":
description: This response will be presented when an unexpected internal
error has occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"400":
description: This response will be presented when a validation error has
occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"502":
description: "This response will be presented when an unexpected error has\
\ occurred, this is most likely to do with a client error. The user will\
\ be prompted to try again."
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"401":
description: This response will be presented when the attempt to call is
unauthorised.
content:
application/json: { }
"403":
description: This response will be presented when the attempt to call is
forbidden.
content:
application/json: { }
"429":
description: This response will be presented when your quota has been exceeded.
The quota resets every 60 seconds and the value varies per environment
content:
application/json: { }
delete:
security:
- OAuth2: []
tags:
- Property
summary: Removes Commercial Properties (UK Only)
description: Remove commercial properties
operationId: removeCommercialPropertyDetails
parameters:
- name: reference
in: path
description: The reference of the property. This must be the same provided at space level, when a property defines a building with no spaces.
example: 'Property_Reference_123'
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas/RemoveCommercialProperty"
required: true
responses:
"200":
description: Successfully removed the property and associated listings.
"401":
description: This response will be presented when the attempt to call is unauthorised.
content:
application/json: { }
"403":
description: This response will be presented when the attempt to call is forbidden.
content:
application/json: { }
"404":
description: This response will be presented when the property is not found.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"502":
description: This response will be presented when an unexpected error has occurred, please try again.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"503":
description: This response will be presented when an unexpected internal error has occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"429":
description: This response will be presented when your quota has been exceeded.
The quota resets every 60 seconds and the value varies per environment
content:
application/json: { }
/v2/property/commercial/branch:
get:
security:
- OAuth2:
- client Grants read and write access
summary: Gets list of commercial properties (UK Only) by branch
description: Gets list of commercial properties (UK Only) by branch
operationId: getCommercialPropertiesByBranch
parameters:
- name: id
in: query
description: The ID of the branch
required: true
schema:
type: integer
format: int64
- name: page
in: query
description: The page number to return
required: false
schema:
type: integer
format: int32
- name: size
in: query
description: The size of results to be returned in a page
required: false
schema:
type: integer
format: int32
responses:
"503":
description: This response will be presented when an unexpected internal
error has occurred.
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"200":
description: Properties are found for the branch and the response object will include all
the property details.
content:
application/json:
schema:
$ref: "#/components/schemas/PropertyAction"
"502":
description: "This response will be presented when an unexpected error has\
\ occurred, this is most likely to do with a client error. The user will\
\ be prompted to try again."
content:
application/json:
schema:
$ref: "#/components/schemas/ProblemDetail"
"401":
description: This response will be presented when the attempt to call is
unauthorised.
content:
application/json: { }
"403":
description: This response will be presented when the attempt to call is
forbidden.
content:
application/json: { }
"429":
description: This response will be presented when your quota has been exceeded.
The quota resets every 60 seconds and the value varies per environment
content:
application/json: { }
components:
securitySchemes:
OAuth2:
description: This API uses OAuth2 client credentials flow for server to server authentication
type: oauth2
flows:
implicit:
authorizationUrl: /oauth/token
scopes: {}
schemas:
Amenity:
type: string
description: List of amenities offered at advertised building.
enum:
- WIFI
- CONCIERGE
- PARKING
- GYM
- SECURITY_SYSTEM
- TWENTY_FOUR_HOUR_ACCESS
- BIKE_STORAGE
- BILLS_INCLUDED
- CAFE
- CLEANING_SERVICES
- COMMUNAL_AREAS
- COMMUNAL_GARDENS
- FLEXIBLE_TENANCIES
- PETS_ALLOWED
- RESTAURANT
- PROFESSIONAL_MANAGEMENT
- ROOF_TERRACE
- SERVICES_INCLUDED
- SHARED_WORKSPACE
- SOCIAL_ACTIVITIES
- TRANSPORT_LINKS
- WELL_CONNECTED
- CONTROLLED_ACCESS
- CONFERENCING_FACILITY
-
# --- truncated at 32 KB (73 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rightmove/refs/heads/main/openapi/rightmove-commercial-listings-openapi.yml