Properties

A property is a listing managed in Vestta: an apartment for rent, a house for sale, a commercial unit offered for transfer. The API exposes the workspace's public catalogue — the same listings the agency chooses to publish — so you can show them on a website, feed another product or keep an external index in sync.

All property endpoints need the properties:read scope.

Endpoints

• GET/v1/ext/propertiesList propertiesList properties
• GET/v1/ext/properties/{property_id}Retrieve a propertyRetrieve a property

What is public

A property is returned only when, in Vestta:

• it is marked as public, and
• its status is not sold (vendida), rented (alquilada) or withdrawn (retirado).

In practice the API returns properties with status disponible or reservada. The response only carries listing data: public images, processed videos and the characteristics shown in a listing. Internal data — notes, owner and agency details, commission and captation figures, price history, portal settings — is never sent.

Address privacy

Each property has an address privacy setting in Vestta (Dirección exacta, Solo zona / calle or Ocultar ubicación). Every location field follows it, and specs.address_privacy tells you which one applies:

city, province and country are always returned when set. Properties without a privacy setting are treated as approximate, like in the Vestta app. specs.building_name is only included when the address is public.

When you draw approximate properties on a map, show an area rather than a pin: the coordinates mark a ~1 km cell, not the building.

Operations and prices

A property can be offered for more than one operation at once, so operation may hold several values separated by commas, such as venta,alquiler. Each operation has its own price:

When you filter or sort by price, the operation filter decides which of these fields is used. See List properties.

The property object

List properties and Retrieve a property return the same object.

• idintegerrequired

  Numeric property ID. Use it with Retrieve a property.

• operationstring

  Operations the property is offered for: venta, alquiler, traspaso, or several joined by commas (e.g. venta,alquiler).

• typestring

  Property type key, e.g. apartamento, casa, local, oficina, terreno or edificio.

• subtypestring

  Subtype as a Spanish display label (e.g. Ático, Local Comercial), or Sin Especificar.

• titlestring

  Listing title. May be empty.

• pricenumber

  Sale price in euros. Rent and transfer prices are in specs.price_calc.

• size_totalnumber

  Total size in m².

• bedroomsinteger
• bathroomsinteger
• postal_codestring

  Omitted when the property's location is hidden.

• descriptionstring

  Listing description as HTML.

• imagesarray of any

  Public images, as {id, url, order, is_primary, title} objects.

• videosarray of any

  Processed videos, as {id, title, order, url, hls_url, thumbnail_url, embed_url} objects.

• specsobject

  Listing characteristics. Keys depend on the property type. price_calc.price_alq and price_calc.price_trasp hold the monthly rent and transfer price; address_privacy is public, approximate or hidden; building_name is only present when the address is public.

• featuresarray of any

  Amenities as {label, key, value, isextra} objects. label is a display string; key is stable.

• statusstring

  disponible or reservada. Sold, rented and withdrawn properties are never returned.

• addressstring

  Follows the property's address privacy: the full address when public, the approximate address when approximate, omitted when hidden.

• citystring
• provincestring
• countrystring
• latnumber

  Latitude in decimal degrees. Exact when the address is public, rounded to 2 decimals (about 1 km) when approximate, omitted when hidden.

• lonnumber

  Longitude in decimal degrees, with the same precision rules as lat.

• is_featuredboolean

  Whether the business marked the property as featured.

• created_atstring

  ISO 8601 timestamp with UTC offset.

• updated_atstring

  ISO 8601 timestamp with UTC offset. The default sort key.

specs holds additional characteristics whose keys depend on the property type — floor, orientation, energy certificate, rental flags and so on. Read the keys you need and ignore the rest.