> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://apidocs.propertypal.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://apidocs.propertypal.com/_mcp/server.

# API Reference

The **Commercial Listings API** lets you manage commercial property listings on
PropertyPal. It supports uploading new listings, updating existing ones (keyed on
the `reference` field), and retrieving or removing them.

Before you start, make sure you've read [Authentication](/docs/authentication) and
[Environments](/docs/environments).

## Endpoints

| Method   | Path                                  | Description                                  |
| -------- | ------------------------------------- | -------------------------------------------- |
| `PUT`    | `/v2/property/commercial/{reference}` | Create or update a commercial property.      |
| `GET`    | `/v2/property/commercial/{reference}` | Retrieve a single listing.                   |
| `GET`    | `/v2/property/commercial/branch`      | Page through all live listings for a branch. |
| `DELETE` | `/v2/property/commercial/{reference}` | Remove a listing.                            |

## Key concepts

* **`reference`** is your stable identifier for a property. Re-sending the same
  reference updates the existing record; a new reference creates a new listing.
* **Building vs. spaces** — upload a property as a standalone building, or include
  a `spaces[]` array to market individual floors/units. Converting `BUILDING` →
  `SPACE` is supported; the reverse is not.
* **Media** — photos, floor plans, EPCs, brochures and virtual tours are submitted
  as arrays of media assets. Brochure URLs must end in `.pdf`.

## Error handling

For `4xx` and `5xx` errors the API returns a JSON `ProblemDetail` body:

```json title="ProblemDetail (400)"
{
  "type": "https://api-services.rightmove.co.uk/problems/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "instance": "/v2/property/commercial/DEMO-001",
  "properties": {
    "traceId": "1d3b0a4e-9c9e-4d6a-9a45-c7c0a8f7c2a1",
    "timestamp": "2026-06-19T09:00:00Z",
    "validationError": [
      { "field": "building.location.postcode", "message": "postcode is required" }
    ]
  }
}
```

Include `properties.traceId` when contacting support about a failed request.

Browse the full endpoint reference in the sidebar for schemas, enums, and live
request/response examples.