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.

Reading the catalogue needs properties:read. Creating, updating and uploading needs properties:write. Publication and processing status need properties:publish. See Publishing properties.

Endpoints

• GET/v1/propertiesList published propertiesList published properties
• POST/v1/propertiesCreate a propertyCreate a property
• GET/v1/properties/{property_id}Retrieve a published propertyRetrieve a published property
• PATCH/v1/properties/{property_id}Update a propertyUpdate a property

• POST/v1/properties/{property_id}/images/uploadsPrepare original image uploadsPrepare original image uploads
• POST/v1/properties/{property_id}/images/uploads/{upload_id}/completeComplete image uploadsComplete image uploads

• GET/v1/properties/{property_id}/publicationRetrieve publicationRetrieve publication
• PUT/v1/properties/{property_id}/publicationSet property publicationSet property publication

What is public

A property is returned only when, in Vestta:

• it is marked as public, and
• it is saved and is not a draft.

The API returns explicitly published properties regardless of their commercial status. Drafts are excluded. The response only carries listing data: public images with independent opaque URLs, processed videos and the characteristics shown in a listing. New photos are watermarked; migration-grandfathered photos may remain unmarked. 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 objects

  Opaque public copies. New photos are watermarked; legacy copies may remain unmarked. Original paths and IDs are never included.

  Show 5 child attributes

  • idstringrequired
  • urlstringrequired

    Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL.

  • orderinteger default: 1
  • is_primaryboolean default: false
  • titlestring default:
• videosarray of objects

  Processed public videos.

  Show 7 child attributes

  • idstringrequired
  • titlestring
  • orderinteger
  • urlstring
  • hls_urlstring
  • thumbnail_urlstring
  • embed_urlstring
• specsPublicationSpecs

  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.

  Show 52 child attributes

  • translationsTranslationSpec

    Traducciones de las descripciones

    Show 6 child attributes

    • caTranslatedDescription

      Traduccion en catalán de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

    • enTranslatedDescription

      Traduccion en ingles de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

    • frTranslatedDescription

      Traduccion en francés de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

    • deTranslatedDescription

      Traduccion en alemán de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

    • ptTranslatedDescription

      Traduccion en portuges de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

    • itTranslatedDescription

      Traduccion en italiano de la descripción

      Show 2 child attributes

      • titlestring

        Título de la descripción

      • descriptionstring

        Descripción

  • usable_areanumber≥ 0

    Metros cuadrados útiles

  • plot_sizenumber≥ 0

    Metros cuadrados parcela

  • size_builtnumber≥ 0

    Superficie construida

  • porch_sizenumber≥ 0

    Metros cuadrados porche

  • size_terracesnumber≥ 0

    Metros cuadrados terrazas

  • attic_sizenumber≥ 0

    Metros cuadrados ático

  • storage_dimensionsnumber

    Dimensiones del trastero

  • doble_bedroomsinteger≥ 0

    Número de habitaciones dobles

  • suite_bathroomsinteger≥ 0

    Número de baños en suite

  • num_terracesinteger≥ 0

    Número de terrazas

  • conservationstring

    Estado de conservación

  • floorstring

    Planta canónica para portales

  • house_floorsinteger≥ 1

    Número de plantas de una casa

  • elevatorboolean

    Tiene ascensor (0/1 o Sí/No)

  • viewsstring

    Vistas de la propiedad

  • orientationstring

    Orientación (norte, sur, este, oeste)

  • energy_certificatestring

    Certificado energético A-G

  • emissionsstring

    Emisiones A-G

  • energy_consumption_valuenumber≥ 1≤ 999

    Consumo (kWh/m² año)

  • emissions_valuenumber≥ 1≤ 999

    Emisiones (kg CO₂/m² año)

  • heightnumber

    Altura del local

  • facade_metersnumber

    Metros de fachada

  • meters_showcasenumber

    Metros de escaparate

  • entrace_typestring

    Tipo de entrada de la oficina

  • positionstring

    1ª/2ª Linea del mar

  • officesinteger≥ 0

    Número de despachos

  • meeting_roomsinteger≥ 0

    Número de salas de reuniones

  • caminostring

    Tipo de suelo

  • terrain_extensionstring

    Tamaño (Grande/Pequeño)

  • topographystring

    Topografía del terreno

  • num_seatsinteger≥ 0

    Número de plazas

  • dimensionsstring

    Dimensiones del aparcamiento

  • turistic_licensestring

    Licencia turística

  • construction_yearinteger

    Año de construcción

  • exposurestring

    Interior o Exterior

  • stylestring

    Conservación

  • num_viviendasinteger

    Número de viviendas

  • num_localesinteger

    Número de locales

  • num_ascensoresinteger

    Número de ascensores

  • num_parkingsinteger≥ 0

    Número de parkings incluidos

  • num_floorsinteger

    Número de plantas

  • luxury_propertyboolean

    Propiedad de lujo

  • holiday_rentingboolean

    Alquiler vacacional

  • temporal_rentingboolean

    Alquiler temporal

  • purchase_option_rentalboolean

    Alquiler con opción a compra

  • address_privacystring

    Privacidad de la ubicación en portales: public | approximate | hidden

  • activitiesActivitiesSpec

    Actividades permitidas

    Show 2 child attributes

    • predefinedarray of strings

      Actividades predefinidas

    • customarray of strings

      Actividades personalizadas

  • num_entrancesNumEntrancesSpec

    Número de entradas

    Show 5 child attributes

    • totalinteger≥ 0 default: 0

      Total de entradas

    • peaton_entrancesinteger≥ 0 default: 0

      Entradas de peatones

    • moto_entrancesinteger≥ 0 default: 0

      Entradas de motos

    • van_entrancesinteger≥ 0 default: 0

      Entradas de furgoneta

    • car_entrancesinteger≥ 0 default: 0

      Entradas de coche

  • floor_breakdownFloorBreakdownSpec

    Desglose de plantas

    Show 3 child attributes

    • base_floorinteger default: 0

      Metros ² de la planta baja

    • first_floorinteger default: 0

      Metros ² de la primera planta

    • second_floorinteger default: 0

      Metros ² de la segunda planta

  • price_calcPublicPrices
    Show 2 child attributes

    • price_alqnumber≥ 0
    • price_traspnumber≥ 0
  • building_namestring

    Published only when address privacy is public.

• featuresarray of objects

  Typed amenities. label is a display string; key is stable.

  Show 4 child attributes

  • keystringrequired1–100 chars
  • labelstringrequired1–200 chars
  • valuestring | boolean | integer | numberrequired
  • isextraboolean default: false
• statusstring

  Commercial status of the explicitly published property. Drafts 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.