Upsert building (no spaces) | PropertyPal Developer Docs

curl -X PUT https://rightmove-feed.propertypal.com/v2/property/commercial/DEMO-001 \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "building": {
    "agentId": 12345,
    "description": "An exceptional 1,250 sq ft refurbished ground-floor office in the heart of Belfast city centre. Fully fitted with open-plan working areas, three meeting rooms, kitchen and shower facilities. Suits 25–35 people.",
    "summary": "Refurbished city-centre office, 1,250 sq ft, open-plan with 3 meeting rooms",
    "transactionType": "LETTINGS",
    "status": "AVAILABLE",
    "published": true,
    "tenureType": "LEASEHOLD",
    "tenureUnexpiredYears": 25,
    "yearBuilt": 1995,
    "yearRenovated": 2024,
    "floors": 3,
    "sizing": {
      "size": 1250,
      "unit": "SQFT",
      "measurementType": "NIA"
    },
    "pricing": {
      "price": 18000,
      "frequency": "YEARLY",
      "rentObligation": "FULLY_REPAIRING_AND_INSURING",
      "displayQualifier": "NONE"
    },
    "location": {
      "displayAddress": "12 Donegall Square West, Belfast",
      "buildingIdentifier": "Unit 1, 12 Donegall Square West",
      "postcode": "BT1 6JA",
      "latitude": 54.5973,
      "longitude": -5.9301,
      "showMap": true
    },
    "owner": {
      "name": "ExampleCo Property Holdings Ltd",
      "description": "A commercial real estate investment firm based in Belfast."
    },
    "keyFeatures": [
      "Open-plan working area",
      "Three meeting rooms",
      "Air conditioning",
      "Bike storage",
      "Shower facilities"
    ],
    "amenities": [
      "AIR_CONDITIONING",
      "PARKING",
      "BIKE_STORAGE",
      "SHOWER_FACILITIES",
      "NATURAL_LIGHT"
    ],
    "useClasses": [
      "CLASS_E"
    ],
    "environment": {
      "environmentalDescription": "Recently refurbished with LED lighting and improved insulation.",
      "breeamRating": 72,
      "epcRating": 86
    },
    "primaryPropertyClassification": {
      "subType": "OFFICE",
      "desks": 30,
      "capacity": {
        "minimum": 25,
        "maximum": 35
      },
      "gradeOfSpaceType": "B"
    },
    "secondaryPropertyClassifications": [],
    "letType": "LONG",
    "availableDate": "2026-08-01",
    "businessRates": 4500,
    "serviceCharge": 1500,
    "isRentAllInclusive": false,
    "letContractLength": 60,
    "condition": "FULL_FIT_OUT",
    "listedBuilding": false,
    "businessForSale": false,
    "auction": false,
    "parkingSpaces": 2,
    "planningPermission": "APPROVED",
    "media": {
      "photos": [
        {
          "url": "https://example.com/photos/exterior.jpg",
          "description": "Front exterior",
          "order": 1
        },
        {
          "url": "https://example.com/photos/open-plan.jpg",
          "description": "Open-plan office area",
          "order": 2
        },
        {
          "url": "https://example.com/photos/meeting-room.jpg",
          "description": "Main meeting room",
          "order": 3
        }
      ],
      "floorPlans": [
        {
          "url": "https://example.com/floorplans/ground.jpg",
          "description": "Ground floor plan",
          "order": 1
        }
      ],
      "epcs": [
        {
          "url": "https://example.com/epcs/epc-certificate.pdf",
          "description": "EPC certificate",
          "order": 1
        }
      ],
      "epcGraphs": [
        {
          "url": "https://example.com/epcs/epc-graph.jpg",
          "description": "EPC rating graph",
          "order": 1
        }
      ],
      "brochures": [
        {
          "url": "https://example.com/brochures/property.pdf",
          "description": "Property brochure",
          "order": 1
        }
      ],
      "virtualTours": [
        {
          "url": "https://example.com/tours/walkthrough.mp4",
          "description": "3D walkthrough",
          "order": 1
        }
      ]
    }
  }
}'

{
  "meta": {
    "requestTimestamp": "2026-06-19T09:00:00Z",
    "responseTimestamp": "2026-06-19T09:00:00.142Z",
    "traceId": "1d3b0a4e-9c9e-4d6a-9a45-c7c0a8f7c2a1"
  },
  "data": {
    "links": {
      "self": {
        "building": {
          "externalReference": "DEMO-001",
          "selfLink": "/v2/property/commercial/DEMO-001"
        }
      },
      "display": {
        "building": {
          "externalReference": "DEMO-001",
          "buildingDisplayLink": "/commercial-property/DEMO-001"
        }
      }
    }
  }
}

Create or update a commercial property.

The URL path segment {reference} is your stable identifier for the property — re-sending the same reference replaces the existing record. Use a new reference to create a new listing.

The request body accepts either of two shapes:

CommercialPropertyBuildingOnly — building details, no individual spaces.
CommercialPropertyWithSpaces — building details plus a spaces array (max 50) for floors / units to be marketed individually.

This collection includes one example of each — see the Upsert building (with spaces) sibling request for the spaces variant.

Required building-level fields

agentId, description, summary, transactionType (SALES/LETTINGS), pricing, location, keyFeatures, primaryPropertyClassification, status, published.

Status

Allowed values: AVAILABLE, SOLD_STC, SOLD_STCM, RESERVED, LET_AGREED, UNDER_OFFER. Anything else triggers an automatic published=false. See Property-upload visibility guidelines in the collection overview.

Response

200 OK — listing was updated. Body is PropertySaveAction containing self/display links.
201 Created — listing was newly created. Same body shape as 200.
400 Bad Request — validation failed. See ProblemDetail.properties.validationError.

**Create or update a commercial property.** The URL path segment `{reference}` is your stable identifier for the property — re-sending the same reference replaces the existing record. Use a new reference to create a new listing. The request body accepts either of two shapes: - **`CommercialPropertyBuildingOnly`** — building details, no individual spaces. - **`CommercialPropertyWithSpaces`** — building details plus a `spaces` array (max 50) for floors / units to be marketed individually. This collection includes one example of each — see the **Upsert building (with spaces)** sibling request for the spaces variant. ### Required building-level fields `agentId`, `description`, `summary`, `transactionType` (`SALES`/`LETTINGS`), `pricing`, `location`, `keyFeatures`, `primaryPropertyClassification`, `status`, `published`. ### Status Allowed values: `AVAILABLE`, `SOLD_STC`, `SOLD_STCM`, `RESERVED`, `LET_AGREED`, `UNDER_OFFER`. Anything else triggers an automatic `published=false`. See [Property-upload visibility guidelines](#) in the collection overview. ### Response - **`200 OK`** — listing was updated. Body is `PropertySaveAction` containing self/display links. - **`201 Created`** — listing was newly created. Same body shape as 200. - **`400 Bad Request`** — validation failed. See `ProblemDetail.properties.validationError`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

referencestringRequired

Request

This endpoint expects an object.

buildingobjectOptional

Response

200 — Updated

metaobject

dataobject

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

429

Too Many Requests Error

502

Bad Gateway Error

503

Service Unavailable Error