# Vestta API documentation Source: https://api-docs.vestta.io OpenAPI: https://api-docs.vestta.io/openapi.json --- # Vestta API URL: https://api-docs.vestta.io Build integrations on top of your real estate data. Use the Vestta API to read the public property catalogue of a Vestta workspace, work with its leads and connect websites, landing pages and external products to it. It is a JSON API over HTTPS, authenticated with API keys that carry explicit scopes. ## Get started Make your first authenticated API request. Understand API keys and scopes. Explore the available resources and schemas. ## Core resources Read property data from Vestta: the public catalogue, with filters, prices, images and locations. Read and send lead information, from simple rental forms to detailed contact requests. ## Guides The error format, every error the API returns and how to handle it. Fixes for the problems integrations run into most often. ## At a glance | | | | --- | --- | | Base URL | `https://api.vestta.io/v1` | | Authentication | `X-Api-Key` header with a key created in Vestta | | Format | JSON over HTTPS | | Availability | Workspaces on the Premium and Enterprise plans | | Schema | [`/openapi.json`](/openapi.json) (OpenAPI 3.1) | --- # Quickstart URL: https://api-docs.vestta.io/quickstart Create an API key and make your first authenticated request to the Vestta API. This guide takes you from no credentials to a working API call. You need a Vestta workspace on the **Premium** or **Enterprise** plan and a user with permission to manage API keys. ### Create an API key In Vestta, open [**Settings → API**](https://crm.vestta.io/settings?page=apis) and select **Nueva API Key**. The Vestta app is in Spanish; the fields are: - **Nombre** — where the key will be used, for example `Website`. - **Duración** — how long the key stays valid: 1, 3, 6 or 12 months. - **Permisos** — the scopes. For this guide, select **Propiedades** (`properties:read`). ### Save the key securely The full key is shown **only once**, right after you create it. It has this format: ```text AC_LIVE_. ``` Store it in a secret manager or an environment variable on your server. Never put it in front-end code or commit it to a repository. For this guide, export it in your terminal: ```bash export VESTTA_API_KEY="AC_LIVE_..." ``` ### Make your first request Call [Retrieve key context](/me). It works with any active key and returns the business and scopes behind it, which makes it the safest first call: #### cURL ```bash curl "https://api.vestta.io/v1/me" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/me', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/me", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, ) response.raise_for_status() data = response.json() ``` ### Inspect the response A `200` response confirms the key works. Check that `scopes` contains everything your integration needs: ```json { "status": "ok", "user": { "company_name": "Inmobiliaria Ejemplo", "scopes": [ "properties:read", "leads:read" ], "auth_method": "api_key" } } ``` If you get a `401` instead, the body tells you why — a missing header, a typo in the key, or a revoked or expired key. See [Errors](/errors#authentication-failures). ### Continue with Properties or Leads With `properties:read` granted, list the first page of your public catalogue: #### cURL ```bash curl "https://api.vestta.io/v1/properties?limit=20" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties?limit=20', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/properties", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, params={ "limit": 20, }, ) response.raise_for_status() data = response.json() ``` From here, go deeper into the resource you need: - [Properties](/properties) — filters, prices, map areas and the property object. - [Leads](/leads) — read leads, or send them from your forms with the `leads:ingest` scope. ## Next steps - [Authentication](/authentication) — both supported headers and what each scope unlocks. - [API keys](/api-keys) — expiry, revocation and rotating a key without downtime. - [Pagination](/pagination) — walk through every page of a list. --- # Authentication URL: https://api-docs.vestta.io/authentication Authenticate every request with an API key, and grant each key only the scopes it needs. Every request to the Vestta API is authenticated with an **API key**. A key belongs to one Vestta workspace: everything the API returns or creates is scoped to that workspace, and the key's **scopes** decide which endpoints it may call. Keys are created and managed in the Vestta app — see [API keys](/api-keys). ## Sending the key Send the key in the `X-Api-Key` header: ```bash curl "https://api.vestta.io/v1/me" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` For compatibility with existing integrations, the API also accepts the key in the `Authorization` header with the `ApiKey` scheme: ```bash curl "https://api.vestta.io/v1/me" \ -H "Authorization: ApiKey $VESTTA_API_KEY" ``` Use `X-Api-Key` in new integrations. When both headers are present, `X-Api-Key` is used and `Authorization` is ignored. `Authorization: Bearer ` is **not** supported. A request that only carries a Bearer token is rejected with `401 API key required`. ## Key format Keys look like this: ```text AC_LIVE_. ``` `key_id` identifies the key and is visible in the Vestta app; `secret` is shown only once, when the key is created. Vestta stores a hash of the secret, never the secret itself, so a lost key cannot be recovered — create a new one. ## Scopes A scope grants access to a group of endpoints. Scopes are chosen when the key is created (under **Permisos** in the Vestta app) and cannot be changed afterwards; to change them, create a new key. | Scope | In the Vestta app | Grants | | --- | --- | --- | | `properties:read` | Propiedades | Read the public property catalogue. | | `properties:write` | Editar propiedades | Create and update properties and upload photos. | | `properties:publish` | Publicar propiedades | Publish, unpublish and read processing state. | | `leads:write` | Editar contactos | Create and update private CRM contacts without outreach. | | `leads:read` | Leer leads | Read every lead of the workspace, including contact details. | | `leads:ingest` | Enviar consultas | Create leads from your forms and services. | This is how scopes map to endpoints, as declared in the [OpenAPI schema](/openapi.json): - `leads:ingest`: `POST /v1/leads/ingest`, `POST /v1/leads/inquiries` - `leads:read`: `GET /v1/leads`, `GET /v1/leads/{lead_id}` - `leads:write`: `POST /v1/leads`, `PATCH /v1/leads/{lead_id}` - `properties:publish`: `GET /v1/properties/{property_id}/publication`, `PUT /v1/properties/{property_id}/publication` - `properties:read`: `GET /v1/properties`, `GET /v1/properties/{property_id}` - `properties:write`: `POST /v1/properties`, `PATCH /v1/properties/{property_id}`, `POST /v1/properties/{property_id}/images/uploads`, `POST /v1/properties/{property_id}/images/uploads/{upload_id}/complete` Grant the minimum. A website that shows listings and sends contact requests needs `properties:read` and `leads:ingest` — not `leads:read`, which exposes the personal data of every lead in the workspace. ## How a request is checked Every operation verifies authentication, the required scope and its request schema: 1. **The key** — present, well formed, known, active, not expired, with a matching secret. Otherwise: `401`. 2. **The scope** — the key must have the endpoint's scope. Otherwise: `403` with `Insufficient scope`. 3. **The parameters and body** — validated against the schema. Otherwise: `422`. Do not depend on error precedence when a request fails more than one check. Authentication errors use `401`, insufficient scopes use `403`, and invalid input uses `422`. Each `401` has a specific message that tells you what failed. They are listed in [Errors](/errors). ## Where to call the API from Call the API from your server, not from the browser. The API answers cross-origin requests, but any key used in front-end code is visible to every visitor and can be copied. To send leads from a public website, post the form to your own backend and call [Create an inquiry](/leads/inquiries) from there, keeping the key in a server-side environment variable. --- # API keys URL: https://api-docs.vestta.io/api-keys Create, store, rotate and revoke the API keys that give your integrations access to Vestta. API keys are created in the Vestta app, in [**Settings → API**](https://crm.vestta.io/settings?page=apis). That page lists every key of the workspace with its status, creation date and last use. ## Who can manage keys - The workspace must be on the **Premium** or **Enterprise** plan. On other plans the API section shows *Acceso API no incluido*. - Creating, revoking, reactivating and deleting keys requires the **Administrar API Keys** permission. Other users can see the list but not change it. ## Creating a key Select **Nueva API Key** and fill in: | Field | Meaning | | --- | --- | | **Nombre** | A label for the integration that will use the key, such as `Website` or `Zapier`. | | **Duración** | 1, 3, 6 or 12 months. Each month counts as 30 days from the moment of creation. | | **Permisos** | The [scopes](/authentication#scopes) of the key. | The full key is displayed **once**, in the confirmation dialog. Copy it before closing the dialog: Vestta only keeps a hash of the secret and cannot show it again. Always select at least one scope. A key without scopes can only call [Retrieve key context](/me). ## Storing a key - Keep keys on the server, in environment variables or a secret manager. - Never put a key in front-end code, mobile apps, public repositories, logs or support tickets. - Use one key per integration, so you can revoke one without affecting the others, and so **Último uso** (last use) tells you which integration is active. Vestta records the date and IP address of the last successful request made with each key. ## Expiry A key stops working when its duration ends. Requests then fail with `401 API key expired`. An expired key cannot be extended: create a new key and replace the old one. The expiry date is shown in the key list. Plan the replacement before that date. ## Revoking, reactivating and deleting From the key list: - **Revocar** — the key stops working immediately. Requests fail with `401 API key is revoked`. - **Reactivar** — a revoked key accepts requests again, until its original expiry date. - **Eliminar** — the key is deleted permanently. Requests fail with `401 API key not found`. Revoke a key as soon as you suspect it has leaked. ## Rotating a key Vestta has no automatic rotation. To replace a key without downtime: ### Create the new key Create a key with the same scopes as the one you are replacing. ### Deploy it Update the secret in your integration and deploy. ### Verify it Call [Retrieve key context](/me) with the new key and check the `scopes` in the response. **Último uso** of the new key starts updating. ### Revoke the old key Revoke the old key once **Último uso** shows it is no longer used. Delete it later, when you are sure nothing depends on it. --- # Requests & responses URL: https://api-docs.vestta.io/requests Base URL, formats and conventions shared by every endpoint of the Vestta API. ## Base URL All endpoints live under one base URL: ```text https://api.vestta.io/v1 ``` The former host, `https://api.vestta.app/v1`, keeps answering the same requests, so existing integrations do not need to change at once. Paths in this documentation are shown in full — for example `GET /v1/properties` — so they can be pasted after the host. The `v1` segment is the API version; breaking changes would ship under a new version and be announced in the [changelog](/changelog). ## Requests - Use HTTPS. Request and response bodies are JSON encoded as UTF-8. - Send `Content-Type: application/json` with every `POST` body. - Query parameters are case-sensitive. Unknown query parameters are ignored. - Authenticate every request with your key — see [Authentication](/authentication). ## Responses Successful responses have status `200` and carry `"status": "ok"`. Responses that read data put it in `data`: ```json { "status": "ok", "data": [ … ], "count": 78, "limit": 20, "offset": 0, "authenticated_as": "Inmobiliaria Ejemplo" } ``` `authenticated_as` is the name of the workspace that owns the key — useful in logs when one service talks to several workspaces. Errors use a different shape, with a `detail` field. See [Errors](/errors). ## Data conventions | Kind | Convention | | --- | --- | | IDs | Integers, unique per resource: `"id": 1355`. | | Timestamps | ISO 8601 with UTC offset: `"2026-09-26T19:38:41.390976+02:00"`. | | Money | Numbers in euros, without currency symbols. | | Phone numbers | E.164: `"+34600111222"`. | | Missing values | Fields without a value are usually **omitted** rather than returned as `null`. Treat a missing field as `null`. | | Vocabulary | Business values are stored in Spanish, as in the Vestta app: `venta`, `alquiler`, `disponible`, `demandante`. Each field's values are listed in the reference. | Build integrations that **ignore fields they do not know**. New fields can be added to responses without a new API version. ## Caching Responses are sent with `Cache-Control: no-store`: they always reflect the current state of the workspace and must not be cached by proxies. If you cache on your side — for example to render a listings page — keep the cache per workspace and refresh it periodically. ## Rate limits The API does not currently enforce per-key rate limits. Keep traffic proportionate: cache what you can and avoid polling in tight loops. Any future limit will be announced in the [changelog](/changelog). ## OpenAPI The full contract is published as OpenAPI 3.1 at [`/openapi.json`](/openapi.json). It is the same schema the reference pages of this site are generated from, so you can import it into Postman, Insomnia or a client generator and get exactly what is documented here. --- # Pagination URL: https://api-docs.vestta.io/pagination Page through properties and leads with limit and offset. List endpoints return results in pages, controlled by two query parameters: | Parameter | Default | Range | Meaning | | --- | --- | --- | --- | | `limit` | `100` | 1–1000 | Maximum number of results in the page. | | `offset` | `0` | ≥ 0 | Number of results to skip. | A value outside its range returns [`422`](/errors#validation-errors). There are no cursors or `next` links. ## What `count` means Both list endpoints report the total matching records across all pages, including when the requested page is empty. | Endpoint | Order | `count` | | --- | --- | --- | | [List properties](/properties/list) | Last updated first, unless `sort` is set | **Total** matching properties, across all pages | | [List leads](/leads/list) | Newest first | **Total** contacts, across all pages | ## Paging through properties `count` is the total, so stop when `offset` reaches it: ```javascript [JavaScript] async function listAllProperties() { const properties = [] const limit = 100 for (let offset = 0; ; offset += limit) { const url = `https://api.vestta.io/v1/properties?limit=${limit}&offset=${offset}` const response = await fetch(url, { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY } }) if (!response.ok) throw new Error(`Vestta API ${response.status}`) const page = await response.json() properties.push(...page.data) if (offset + limit >= page.count) return properties } } ``` ## Paging through leads Stop when the offset reaches the total: ```python [Python] import os import requests def list_all_leads(): leads, limit, offset = [], 100, 0 while True: response = requests.get( "https://api.vestta.io/v1/leads", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, params={"limit": limit, "offset": offset}, ) response.raise_for_status() page = response.json() leads.extend(page["data"]) if offset + limit >= page["count"]: return leads offset += limit ``` ## Consistency Pages are computed when each request arrives. If properties or leads change while you page through them, a result can move between pages and be skipped or returned twice. When you need a complete, exact copy, de-duplicate by `id`, and run the sync again later rather than relying on a single pass. Filters are applied before pagination, including the map areas of [List properties](/properties/list#map-areas): `count` and the pages only contain matching properties. --- # Properties URL: https://api-docs.vestta.io/properties Create, edit and publish properties, and read their protected public catalogue. 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](/publishing). ## Endpoints - `GET /v1/properties` — List published properties (https://api-docs.vestta.io/properties/list) - `POST /v1/properties` — Create a property (https://api-docs.vestta.io/properties/create) - `GET /v1/properties/{property_id}` — Retrieve a published property (https://api-docs.vestta.io/properties/retrieve) - `PATCH /v1/properties/{property_id}` — Update a property (https://api-docs.vestta.io/properties/update) - `POST /v1/properties/{property_id}/images/uploads` — Prepare original image uploads (https://api-docs.vestta.io/properties/uploads) - `POST /v1/properties/{property_id}/images/uploads/{upload_id}/complete` — Complete image uploads (https://api-docs.vestta.io/properties/complete-uploads) - `GET /v1/properties/{property_id}/publication` — Retrieve publication (https://api-docs.vestta.io/properties/publication-status) - `PUT /v1/properties/{property_id}/publication` — Set property publication (https://api-docs.vestta.io/properties/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. The agency sets the watermark position and size in Vestta under **Configuración › Datos y marca**. 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: | Setting | `address` | `lat` / `lon` | `postal_code` | | --- | --- | --- | --- | | `public` | The full address | Exact | Returned | | `approximate` | The approximate address entered in Vestta, such as a neighbourhood or street | Rounded to 2 decimals (about 1 km) | Returned | | `hidden` | Omitted | Omitted | Omitted | `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: | Operation | Value | Price field | | --- | --- | --- | | Sale | `venta` | `price` | | Rent (monthly) | `alquiler` | `specs.price_calc.price_alq` | | Transfer | `traspaso` | `specs.price_calc.price_trasp` | When you filter or sort by price, the `operation` filter decides which of these fields is used. See [List properties](/properties/list#prices). ## The property object List properties and Retrieve a property return the same object. - `id` (integer, required): Numeric property ID. Use it with Retrieve a property. - `operation` (string, optional, nullable): Operations the property is offered for: `venta`, `alquiler`, `traspaso`, or several joined by commas (e.g. `venta,alquiler`). - `type` (string, optional, nullable): Property type key, e.g. `apartamento`, `casa`, `local`, `oficina`, `terreno` or `edificio`. - `subtype` (string, optional, nullable): Subtype as a Spanish display label (e.g. `Ático`, `Local Comercial`), or `Sin Especificar`. - `title` (string, optional, nullable): Listing title. May be empty. - `price` (number, optional, nullable): Sale price in euros. Rent and transfer prices are in `specs.price_calc`. - `size_total` (number, optional, nullable): Total size in m². - `bedrooms` (integer, optional, nullable) - `bathrooms` (integer, optional, nullable) - `postal_code` (string, optional, nullable): Omitted when the property's location is hidden. - `description` (string, optional, nullable): Listing description as HTML. - `images` (array of objects, optional): Opaque public copies. New photos are watermarked; legacy copies may remain unmarked. Original paths and IDs are never included. - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `videos` (array of objects, optional, nullable): Processed public videos. - `id` (string, required) - `title` (string, optional, nullable) - `order` (integer, optional, nullable) - `url` (string, optional, nullable) - `hls_url` (string, optional, nullable) - `thumbnail_url` (string, optional, nullable) - `embed_url` (string, optional, nullable) - `specs` (PublicationSpecs, optional, nullable): 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. - `translations` (TranslationSpec, optional, nullable): Traducciones de las descripciones - `ca` (TranslatedDescription, optional, nullable): Traduccion en catalán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `en` (TranslatedDescription, optional, nullable): Traduccion en ingles de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `fr` (TranslatedDescription, optional, nullable): Traduccion en francés de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `de` (TranslatedDescription, optional, nullable): Traduccion en alemán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `pt` (TranslatedDescription, optional, nullable): Traduccion en portuges de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `it` (TranslatedDescription, optional, nullable): Traduccion en italiano de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `usable_area` (number, optional, nullable, ≥ 0): Metros cuadrados útiles - `plot_size` (number, optional, nullable, ≥ 0): Metros cuadrados parcela - `size_built` (number, optional, nullable, ≥ 0): Superficie construida - `porch_size` (number, optional, nullable, ≥ 0): Metros cuadrados porche - `size_terraces` (number, optional, nullable, ≥ 0): Metros cuadrados terrazas - `attic_size` (number, optional, nullable, ≥ 0): Metros cuadrados ático - `storage_dimensions` (number, optional, nullable): Dimensiones del trastero - `doble_bedrooms` (integer, optional, nullable, ≥ 0): Número de habitaciones dobles - `suite_bathrooms` (integer, optional, nullable, ≥ 0): Número de baños en suite - `num_terraces` (integer, optional, nullable, ≥ 0): Número de terrazas - `conservation` (string, optional, nullable): Estado de conservación - `floor` (string, optional, nullable): Planta canónica para portales - `house_floors` (integer, optional, nullable, ≥ 1): Número de plantas de una casa - `elevator` (boolean, optional, nullable): Tiene ascensor (0/1 o Sí/No) - `views` (string, optional, nullable): Vistas de la propiedad - `orientation` (string, optional, nullable): Orientación (norte, sur, este, oeste) - `energy_certificate` (string, optional, nullable): Certificado energético A-G - `emissions` (string, optional, nullable): Emisiones A-G - `energy_consumption_value` (number, optional, nullable, ≥ 1, ≤ 999): Consumo (kWh/m² año) - `emissions_value` (number, optional, nullable, ≥ 1, ≤ 999): Emisiones (kg CO₂/m² año) - `height` (number, optional, nullable): Altura del local - `facade_meters` (number, optional, nullable): Metros de fachada - `meters_showcase` (number, optional, nullable): Metros de escaparate - `entrace_type` (string, optional, nullable): Tipo de entrada de la oficina - `position` (string, optional, nullable): 1ª/2ª Linea del mar - `offices` (integer, optional, nullable, ≥ 0): Número de despachos - `meeting_rooms` (integer, optional, nullable, ≥ 0): Número de salas de reuniones - `camino` (string, optional, nullable): Tipo de suelo - `terrain_extension` (string, optional, nullable): Tamaño (Grande/Pequeño) - `topography` (string, optional, nullable): Topografía del terreno - `num_seats` (integer, optional, nullable, ≥ 0): Número de plazas - `dimensions` (string, optional, nullable): Dimensiones del aparcamiento - `turistic_license` (string, optional, nullable): Licencia turística - `construction_year` (integer, optional, nullable): Año de construcción - `exposure` (string, optional, nullable): Interior o Exterior - `style` (string, optional, nullable): Conservación - `num_viviendas` (integer, optional, nullable): Número de viviendas - `num_locales` (integer, optional, nullable): Número de locales - `num_ascensores` (integer, optional, nullable): Número de ascensores - `num_parkings` (integer, optional, nullable, ≥ 0): Número de parkings incluidos - `num_floors` (integer, optional, nullable): Número de plantas - `luxury_property` (boolean, optional, nullable): Propiedad de lujo - `holiday_renting` (boolean, optional, nullable): Alquiler vacacional - `temporal_renting` (boolean, optional, nullable): Alquiler temporal - `purchase_option_rental` (boolean, optional, nullable): Alquiler con opción a compra - `address_privacy` (string, optional, nullable): Privacidad de la ubicación en portales: public | approximate | hidden - `activities` (ActivitiesSpec, optional, nullable): Actividades permitidas - `predefined` (array of strings, optional): Actividades predefinidas - `custom` (array of strings, optional): Actividades personalizadas - `num_entrances` (NumEntrancesSpec, optional, nullable): Número de entradas - `total` (integer, optional, ≥ 0, default 0): Total de entradas - `peaton_entrances` (integer, optional, ≥ 0, default 0): Entradas de peatones - `moto_entrances` (integer, optional, ≥ 0, default 0): Entradas de motos - `van_entrances` (integer, optional, ≥ 0, default 0): Entradas de furgoneta - `car_entrances` (integer, optional, ≥ 0, default 0): Entradas de coche - `floor_breakdown` (FloorBreakdownSpec, optional, nullable): Desglose de plantas - `base_floor` (integer, optional, default 0): Metros ² de la planta baja - `first_floor` (integer, optional, default 0): Metros ² de la primera planta - `second_floor` (integer, optional, default 0): Metros ² de la segunda planta - `price_calc` (PublicPrices, optional, nullable) - `price_alq` (number, optional, nullable, ≥ 0) - `price_trasp` (number, optional, nullable, ≥ 0) - `building_name` (string, optional, nullable): Published only when address privacy is public. - `features` (array of objects, optional, nullable): Typed amenities. `label` is a display string; `key` is stable. - `key` (string, required, 1–100 chars) - `label` (string, required, 1–200 chars) - `value` (string | boolean | integer | number, required) - `isextra` (boolean, optional, default false) - `status` (string, optional, nullable): Commercial status of the explicitly published property. Drafts are never returned. - `address` (string, optional, nullable): Follows the property's address privacy: the full address when public, the approximate address when approximate, omitted when hidden. - `city` (string, optional, nullable) - `province` (string, optional, nullable) - `country` (string, optional, nullable) - `lat` (number, optional, nullable): Latitude in decimal degrees. Exact when the address is public, rounded to 2 decimals (about 1 km) when approximate, omitted when hidden. - `lon` (number, optional, nullable): Longitude in decimal degrees, with the same precision rules as `lat`. - `is_featured` (boolean, optional, nullable): Whether the business marked the property as featured. - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. - `updated_at` (string, optional, nullable): 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. --- # List properties URL: https://api-docs.vestta.io/properties/list Return the public property catalogue, filtered, sorted and paginated. Returns a page of the public catalogue and the total number of matching properties. Without filters, it returns every public property, most recently updated first. ## Filters Filters combine with AND and use the same vocabulary as Vestta. `operation` and `city` ignore case; the other text filters must match exactly: | Filter | Match | Example | | --- | --- | --- | | `operation` | Contains the value, so `alquiler` also matches `venta,alquiler` | `operation=alquiler` | | `type` | Exact, lowercase key | `type=apartamento` | | `subtype` | Exact, using the subtype **key** | `subtype=atico` | | `city` | Exact, ignoring case | `city=Madrid` | | `status` | Exact | `status=reservada` | | `rental_type` | `temporal` or `anual` | `rental_type=anual` | | `min_bedrooms` | At least | `min_bedrooms=2` | | `is_featured` | `true` or `false` | `is_featured=true` | Note that `subtype` filters by key (`atico`) while responses return a display label (`Ático`). ## Prices `min_price`, `max_price` and `sort` compare the price of the operation you filter by: - `operation=alquiler` → the monthly rent, `specs.price_calc.price_alq`. - `operation=traspaso` → the transfer price, `specs.price_calc.price_trasp`. - any other value, or no `operation` → the sale price, `price`. So a rental search in Madrid between 800 and 1,200 € per month, cheapest first, is: ```text GET /v1/properties?operation=alquiler&city=Madrid&min_price=800&max_price=1200&sort=price_asc ``` ## Map areas `locations` restricts results to areas drawn on a map. It is a JSON array, URL-encoded into the query string. Each element is one area; a property matches if it falls inside **any** of them. Three shapes are supported: ```json [ { "geometry": { "type": "circle", "center": { "lat": 40.4168, "lng": -3.7038 }, "radius": 1500 } }, { "geometry": { "type": "polygon", "coordinates": [ { "lat": 40.43, "lng": -3.71 }, { "lat": 40.43, "lng": -3.68 }, { "lat": 40.41, "lng": -3.69 } ] } }, { "type": "point", "position": { "lat": 39.4699, "lng": -0.3763 }, "radius": 800 } ] ``` - **Circle** — `center` and `radius` in metres. - **Polygon** — at least three `coordinates`; `rectangle` is accepted as a synonym. Coordinates can also be `[lat, lng]` pairs, and `lon` is accepted in place of `lng`. - **Point** — a `position` and an optional `radius` in metres, 500 by default. `marker` is a synonym. Areas are matched against the **published** coordinates: rounded ones for approximate locations, none for hidden ones. Approximate properties can match an area up to about 1 km away from their real position, and properties with a hidden location never match an area. Elements without a recognised geometry — for example `{ "name": "Madrid" }` — are ignored, and so is the whole parameter if it is not valid JSON. The `filters.locations` field of the response echoes the areas that were applied, so you can check what was understood. Most HTTP clients URL-encode query parameters for you: pass the JSON string as the value of `locations` instead of encoding it by hand. ### GET /v1/properties Lists the public catalogue. Requires the `properties:read` scope. Required scope: `properties:read` Query parameters: - `limit` (integer, optional, ≥ 1, ≤ 1000, default 100): Maximum number of properties to return. - `offset` (integer, optional, ≥ 0, default 0): Number of matching properties to skip before returning results. - `status` (string, optional, nullable): Exact commercial status match. Only explicitly published properties are returned; drafts are excluded. - `operation` (string, optional, nullable): Operation: `venta`, `alquiler` or `traspaso`. Case-insensitive partial match, so properties offered for several operations match each of them. Also selects which price `min_price`, `max_price` and `sort` use. - `rental_type` (string, optional, nullable, values: `temporal` | `anual`): Rental type: `temporal` for temporary rentals, `anual` for long-term rentals that are neither temporary nor holiday rentals. - `type` (string, optional, nullable): Exact property type: `apartamento`, `casa`, `local`, `nave`, `almacenaje`, `oficina`, `terreno`, `aparcamiento` or `edificio`. - `subtype` (string, optional, nullable): Exact subtype key as stored in Vestta, for example `atico`, `duplex`, `chalet` or `villa`. Responses return the subtype as a display label. - `city` (string, optional, nullable): City name. Case-insensitive exact match. - `locations` (string, optional, nullable): URL-encoded JSON array of map areas. Supports `circle` (center + radius in metres), `polygon`/`rectangle` (coordinates) and `point`/`marker` (500 m default radius). Invalid JSON is ignored. - `min_price` (number, optional, nullable, ≥ 0): Minimum price, inclusive. Uses the rent or transfer price when `operation` is `alquiler` or `traspaso`. - `max_price` (number, optional, nullable, ≥ 0): Maximum price, inclusive. Uses the rent or transfer price when `operation` is `alquiler` or `traspaso`. - `min_bedrooms` (integer, optional, nullable, ≥ 0): Minimum number of bedrooms, inclusive. - `is_featured` (boolean, optional, nullable): `true` returns only featured properties; `false` only non-featured ones. - `sort` (string, optional, nullable, values: `price_asc` | `price_desc`): Sort by price (properties without a price go last). When omitted, results are ordered by last update, newest first. Response 200: Successful response. - `status` (string, required, values: `ok`) - `data` (array of objects, required): The requested page of properties. - `id` (integer, required): Numeric property ID. Use it with Retrieve a property. - `operation` (string, optional, nullable): Operations the property is offered for: `venta`, `alquiler`, `traspaso`, or several joined by commas (e.g. `venta,alquiler`). - `type` (string, optional, nullable): Property type key, e.g. `apartamento`, `casa`, `local`, `oficina`, `terreno` or `edificio`. - `subtype` (string, optional, nullable): Subtype as a Spanish display label (e.g. `Ático`, `Local Comercial`), or `Sin Especificar`. - `title` (string, optional, nullable): Listing title. May be empty. - `price` (number, optional, nullable): Sale price in euros. Rent and transfer prices are in `specs.price_calc`. - `size_total` (number, optional, nullable): Total size in m². - `bedrooms` (integer, optional, nullable) - `bathrooms` (integer, optional, nullable) - `postal_code` (string, optional, nullable): Omitted when the property's location is hidden. - `description` (string, optional, nullable): Listing description as HTML. - `images` (array of objects, optional): Opaque public copies. New photos are watermarked; legacy copies may remain unmarked. Original paths and IDs are never included. - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `videos` (array of objects, optional, nullable): Processed public videos. - `id` (string, required) - `title` (string, optional, nullable) - `order` (integer, optional, nullable) - `url` (string, optional, nullable) - `hls_url` (string, optional, nullable) - `thumbnail_url` (string, optional, nullable) - `embed_url` (string, optional, nullable) - `specs` (PublicationSpecs, optional, nullable): 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. - `translations` (TranslationSpec, optional, nullable): Traducciones de las descripciones - `ca` (TranslatedDescription, optional, nullable): Traduccion en catalán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `en` (TranslatedDescription, optional, nullable): Traduccion en ingles de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `fr` (TranslatedDescription, optional, nullable): Traduccion en francés de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `de` (TranslatedDescription, optional, nullable): Traduccion en alemán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `pt` (TranslatedDescription, optional, nullable): Traduccion en portuges de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `it` (TranslatedDescription, optional, nullable): Traduccion en italiano de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `usable_area` (number, optional, nullable, ≥ 0): Metros cuadrados útiles - `plot_size` (number, optional, nullable, ≥ 0): Metros cuadrados parcela - `size_built` (number, optional, nullable, ≥ 0): Superficie construida - `porch_size` (number, optional, nullable, ≥ 0): Metros cuadrados porche - `size_terraces` (number, optional, nullable, ≥ 0): Metros cuadrados terrazas - `attic_size` (number, optional, nullable, ≥ 0): Metros cuadrados ático - `storage_dimensions` (number, optional, nullable): Dimensiones del trastero - `doble_bedrooms` (integer, optional, nullable, ≥ 0): Número de habitaciones dobles - `suite_bathrooms` (integer, optional, nullable, ≥ 0): Número de baños en suite - `num_terraces` (integer, optional, nullable, ≥ 0): Número de terrazas - `conservation` (string, optional, nullable): Estado de conservación - `floor` (string, optional, nullable): Planta canónica para portales - `house_floors` (integer, optional, nullable, ≥ 1): Número de plantas de una casa - `elevator` (boolean, optional, nullable): Tiene ascensor (0/1 o Sí/No) - `views` (string, optional, nullable): Vistas de la propiedad - `orientation` (string, optional, nullable): Orientación (norte, sur, este, oeste) - `energy_certificate` (string, optional, nullable): Certificado energético A-G - `emissions` (string, optional, nullable): Emisiones A-G - `energy_consumption_value` (number, optional, nullable, ≥ 1, ≤ 999): Consumo (kWh/m² año) - `emissions_value` (number, optional, nullable, ≥ 1, ≤ 999): Emisiones (kg CO₂/m² año) - `height` (number, optional, nullable): Altura del local - `facade_meters` (number, optional, nullable): Metros de fachada - `meters_showcase` (number, optional, nullable): Metros de escaparate - `entrace_type` (string, optional, nullable): Tipo de entrada de la oficina - `position` (string, optional, nullable): 1ª/2ª Linea del mar - `offices` (integer, optional, nullable, ≥ 0): Número de despachos - `meeting_rooms` (integer, optional, nullable, ≥ 0): Número de salas de reuniones - `camino` (string, optional, nullable): Tipo de suelo - `terrain_extension` (string, optional, nullable): Tamaño (Grande/Pequeño) - `topography` (string, optional, nullable): Topografía del terreno - `num_seats` (integer, optional, nullable, ≥ 0): Número de plazas - `dimensions` (string, optional, nullable): Dimensiones del aparcamiento - `turistic_license` (string, optional, nullable): Licencia turística - `construction_year` (integer, optional, nullable): Año de construcción - `exposure` (string, optional, nullable): Interior o Exterior - `style` (string, optional, nullable): Conservación - `num_viviendas` (integer, optional, nullable): Número de viviendas - `num_locales` (integer, optional, nullable): Número de locales - `num_ascensores` (integer, optional, nullable): Número de ascensores - `num_parkings` (integer, optional, nullable, ≥ 0): Número de parkings incluidos - `num_floors` (integer, optional, nullable): Número de plantas - `luxury_property` (boolean, optional, nullable): Propiedad de lujo - `holiday_renting` (boolean, optional, nullable): Alquiler vacacional - `temporal_renting` (boolean, optional, nullable): Alquiler temporal - `purchase_option_rental` (boolean, optional, nullable): Alquiler con opción a compra - `address_privacy` (string, optional, nullable): Privacidad de la ubicación en portales: public | approximate | hidden - `activities` (ActivitiesSpec, optional, nullable): Actividades permitidas - `predefined` (array of strings, optional): Actividades predefinidas - `custom` (array of strings, optional): Actividades personalizadas - `num_entrances` (NumEntrancesSpec, optional, nullable): Número de entradas - `total` (integer, optional, ≥ 0, default 0): Total de entradas - `peaton_entrances` (integer, optional, ≥ 0, default 0): Entradas de peatones - `moto_entrances` (integer, optional, ≥ 0, default 0): Entradas de motos - `van_entrances` (integer, optional, ≥ 0, default 0): Entradas de furgoneta - `car_entrances` (integer, optional, ≥ 0, default 0): Entradas de coche - `floor_breakdown` (FloorBreakdownSpec, optional, nullable): Desglose de plantas - `base_floor` (integer, optional, default 0): Metros ² de la planta baja - `first_floor` (integer, optional, default 0): Metros ² de la primera planta - `second_floor` (integer, optional, default 0): Metros ² de la segunda planta - `price_calc` (PublicPrices, optional, nullable) - `price_alq` (number, optional, nullable, ≥ 0) - `price_trasp` (number, optional, nullable, ≥ 0) - `building_name` (string, optional, nullable): Published only when address privacy is public. - `features` (array of objects, optional, nullable): Typed amenities. `label` is a display string; `key` is stable. - `key` (string, required, 1–100 chars) - `label` (string, required, 1–200 chars) - `value` (string | boolean | integer | number, required) - `isextra` (boolean, optional, default false) - `status` (string, optional, nullable): Commercial status of the explicitly published property. Drafts are never returned. - `address` (string, optional, nullable): Follows the property's address privacy: the full address when public, the approximate address when approximate, omitted when hidden. - `city` (string, optional, nullable) - `province` (string, optional, nullable) - `country` (string, optional, nullable) - `lat` (number, optional, nullable): Latitude in decimal degrees. Exact when the address is public, rounded to 2 decimals (about 1 km) when approximate, omitted when hidden. - `lon` (number, optional, nullable): Longitude in decimal degrees, with the same precision rules as `lat`. - `is_featured` (boolean, optional, nullable): Whether the business marked the property as featured. - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. - `updated_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. The default sort key. - `count` (integer, required): Total number of properties matching the filters, across all pages. - `limit` (integer, required): The `limit` that was applied. - `offset` (integer, required): The `offset` that was applied. - `filters` (object, required): Echo of the filters that were applied; `null` for filters that were not sent. `locations` contains only the areas that were understood. - `authenticated_as` (string, optional, nullable): Name of the business that owns the API key. ```json { "status": "ok", "data": [ { "id": 1355, "operation": "traspaso,alquiler", "type": "local", "subtype": "Local Comercial", "title": "Local comercial en el centro", "price": 0, "size_total": 120, "bedrooms": 0, "bathrooms": 1, "postal_code": "07820", "description": "

Características del local

Superficie total de 120 m² en planta baja…

", "images": [ { "id": "7eac604ad45147d19c7cedb2a10569aa", "url": "https://cdn.vestta.io/media/7eac604ad45147d19c7cedb2a10569aa.webp", "order": 1, "is_primary": true } ], "videos": [], "specs": { "holiday_renting": false, "temporal_renting": false, "address_privacy": "approximate", "price_calc": { "price_alq": 2000, "price_trasp": 25000 } }, "features": [ { "key": "air_conditioning", "label": "Aire Acondicionado", "value": "Sí", "isextra": false } ], "status": "disponible", "address": "San Antonio", "city": "San Antonio", "province": "Islas Baleares", "country": "España", "lat": 38.98, "lon": 1.3, "is_featured": false, "created_at": "2026-07-21T11:42:51.820440+02:00", "updated_at": "2026-09-26T19:38:41.390976+02:00" } ], "count": 78, "limit": 20, "offset": 0, "filters": { "locations": [], "operation": "alquiler" }, "authenticated_as": "Inmobiliaria Ejemplo" } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/properties?limit=20" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties?limit=20', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/properties", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, params={ "limit": 20, }, ) response.raise_for_status() data = response.json() ``` --- # Retrieve a property URL: https://api-docs.vestta.io/properties/retrieve Return one property of the public catalogue by its ID. Returns the same property object as [List properties](/properties/list). Use it to render a listing page or to refresh one property after a change. ## When a property is not found `404 Property not found` is returned when the ID does not exist, but also when the property exists and is **not part of the public catalogue**: it is not marked as public, it is still a draft, or it belongs to another workspace. Commercial status does not override explicit publication. The response does not say which, so a listing that disappears from your site should simply be removed. ### GET /v1/properties/{property_id} Retrieves an allowlisted public listing. Requires the `properties:read` scope. Required scope: `properties:read` Path parameters: - `property_id` (integer, required, ≥ 1) Response 200: Successful response. - `status` (string, required, values: `ok`) - `data` (ExternalProperty, required) - `id` (integer, required): Numeric property ID. Use it with Retrieve a property. - `operation` (string, optional, nullable): Operations the property is offered for: `venta`, `alquiler`, `traspaso`, or several joined by commas (e.g. `venta,alquiler`). - `type` (string, optional, nullable): Property type key, e.g. `apartamento`, `casa`, `local`, `oficina`, `terreno` or `edificio`. - `subtype` (string, optional, nullable): Subtype as a Spanish display label (e.g. `Ático`, `Local Comercial`), or `Sin Especificar`. - `title` (string, optional, nullable): Listing title. May be empty. - `price` (number, optional, nullable): Sale price in euros. Rent and transfer prices are in `specs.price_calc`. - `size_total` (number, optional, nullable): Total size in m². - `bedrooms` (integer, optional, nullable) - `bathrooms` (integer, optional, nullable) - `postal_code` (string, optional, nullable): Omitted when the property's location is hidden. - `description` (string, optional, nullable): Listing description as HTML. - `images` (array of objects, optional): Opaque public copies. New photos are watermarked; legacy copies may remain unmarked. Original paths and IDs are never included. - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `videos` (array of objects, optional, nullable): Processed public videos. - `id` (string, required) - `title` (string, optional, nullable) - `order` (integer, optional, nullable) - `url` (string, optional, nullable) - `hls_url` (string, optional, nullable) - `thumbnail_url` (string, optional, nullable) - `embed_url` (string, optional, nullable) - `specs` (PublicationSpecs, optional, nullable): 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. - `translations` (TranslationSpec, optional, nullable): Traducciones de las descripciones - `ca` (TranslatedDescription, optional, nullable): Traduccion en catalán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `en` (TranslatedDescription, optional, nullable): Traduccion en ingles de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `fr` (TranslatedDescription, optional, nullable): Traduccion en francés de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `de` (TranslatedDescription, optional, nullable): Traduccion en alemán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `pt` (TranslatedDescription, optional, nullable): Traduccion en portuges de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `it` (TranslatedDescription, optional, nullable): Traduccion en italiano de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `usable_area` (number, optional, nullable, ≥ 0): Metros cuadrados útiles - `plot_size` (number, optional, nullable, ≥ 0): Metros cuadrados parcela - `size_built` (number, optional, nullable, ≥ 0): Superficie construida - `porch_size` (number, optional, nullable, ≥ 0): Metros cuadrados porche - `size_terraces` (number, optional, nullable, ≥ 0): Metros cuadrados terrazas - `attic_size` (number, optional, nullable, ≥ 0): Metros cuadrados ático - `storage_dimensions` (number, optional, nullable): Dimensiones del trastero - `doble_bedrooms` (integer, optional, nullable, ≥ 0): Número de habitaciones dobles - `suite_bathrooms` (integer, optional, nullable, ≥ 0): Número de baños en suite - `num_terraces` (integer, optional, nullable, ≥ 0): Número de terrazas - `conservation` (string, optional, nullable): Estado de conservación - `floor` (string, optional, nullable): Planta canónica para portales - `house_floors` (integer, optional, nullable, ≥ 1): Número de plantas de una casa - `elevator` (boolean, optional, nullable): Tiene ascensor (0/1 o Sí/No) - `views` (string, optional, nullable): Vistas de la propiedad - `orientation` (string, optional, nullable): Orientación (norte, sur, este, oeste) - `energy_certificate` (string, optional, nullable): Certificado energético A-G - `emissions` (string, optional, nullable): Emisiones A-G - `energy_consumption_value` (number, optional, nullable, ≥ 1, ≤ 999): Consumo (kWh/m² año) - `emissions_value` (number, optional, nullable, ≥ 1, ≤ 999): Emisiones (kg CO₂/m² año) - `height` (number, optional, nullable): Altura del local - `facade_meters` (number, optional, nullable): Metros de fachada - `meters_showcase` (number, optional, nullable): Metros de escaparate - `entrace_type` (string, optional, nullable): Tipo de entrada de la oficina - `position` (string, optional, nullable): 1ª/2ª Linea del mar - `offices` (integer, optional, nullable, ≥ 0): Número de despachos - `meeting_rooms` (integer, optional, nullable, ≥ 0): Número de salas de reuniones - `camino` (string, optional, nullable): Tipo de suelo - `terrain_extension` (string, optional, nullable): Tamaño (Grande/Pequeño) - `topography` (string, optional, nullable): Topografía del terreno - `num_seats` (integer, optional, nullable, ≥ 0): Número de plazas - `dimensions` (string, optional, nullable): Dimensiones del aparcamiento - `turistic_license` (string, optional, nullable): Licencia turística - `construction_year` (integer, optional, nullable): Año de construcción - `exposure` (string, optional, nullable): Interior o Exterior - `style` (string, optional, nullable): Conservación - `num_viviendas` (integer, optional, nullable): Número de viviendas - `num_locales` (integer, optional, nullable): Número de locales - `num_ascensores` (integer, optional, nullable): Número de ascensores - `num_parkings` (integer, optional, nullable, ≥ 0): Número de parkings incluidos - `num_floors` (integer, optional, nullable): Número de plantas - `luxury_property` (boolean, optional, nullable): Propiedad de lujo - `holiday_renting` (boolean, optional, nullable): Alquiler vacacional - `temporal_renting` (boolean, optional, nullable): Alquiler temporal - `purchase_option_rental` (boolean, optional, nullable): Alquiler con opción a compra - `address_privacy` (string, optional, nullable): Privacidad de la ubicación en portales: public | approximate | hidden - `activities` (ActivitiesSpec, optional, nullable): Actividades permitidas - `predefined` (array of strings, optional): Actividades predefinidas - `custom` (array of strings, optional): Actividades personalizadas - `num_entrances` (NumEntrancesSpec, optional, nullable): Número de entradas - `total` (integer, optional, ≥ 0, default 0): Total de entradas - `peaton_entrances` (integer, optional, ≥ 0, default 0): Entradas de peatones - `moto_entrances` (integer, optional, ≥ 0, default 0): Entradas de motos - `van_entrances` (integer, optional, ≥ 0, default 0): Entradas de furgoneta - `car_entrances` (integer, optional, ≥ 0, default 0): Entradas de coche - `floor_breakdown` (FloorBreakdownSpec, optional, nullable): Desglose de plantas - `base_floor` (integer, optional, default 0): Metros ² de la planta baja - `first_floor` (integer, optional, default 0): Metros ² de la primera planta - `second_floor` (integer, optional, default 0): Metros ² de la segunda planta - `price_calc` (PublicPrices, optional, nullable) - `price_alq` (number, optional, nullable, ≥ 0) - `price_trasp` (number, optional, nullable, ≥ 0) - `building_name` (string, optional, nullable): Published only when address privacy is public. - `features` (array of objects, optional, nullable): Typed amenities. `label` is a display string; `key` is stable. - `key` (string, required, 1–100 chars) - `label` (string, required, 1–200 chars) - `value` (string | boolean | integer | number, required) - `isextra` (boolean, optional, default false) - `status` (string, optional, nullable): Commercial status of the explicitly published property. Drafts are never returned. - `address` (string, optional, nullable): Follows the property's address privacy: the full address when public, the approximate address when approximate, omitted when hidden. - `city` (string, optional, nullable) - `province` (string, optional, nullable) - `country` (string, optional, nullable) - `lat` (number, optional, nullable): Latitude in decimal degrees. Exact when the address is public, rounded to 2 decimals (about 1 km) when approximate, omitted when hidden. - `lon` (number, optional, nullable): Longitude in decimal degrees, with the same precision rules as `lat`. - `is_featured` (boolean, optional, nullable): Whether the business marked the property as featured. - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. - `updated_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. The default sort key. ```json { "status": "ok", "data": { "id": 1355, "operation": "traspaso,alquiler", "type": "local", "subtype": "Local Comercial", "title": "Local comercial en el centro", "price": 0, "size_total": 120, "bedrooms": 0, "bathrooms": 1, "postal_code": "07820", "description": "

Características del local

Superficie total de 120 m² en planta baja…

", "images": [ { "id": "7eac604ad45147d19c7cedb2a10569aa", "url": "https://cdn.vestta.io/media/7eac604ad45147d19c7cedb2a10569aa.webp", "order": 1, "is_primary": true } ], "videos": [], "specs": { "holiday_renting": false, "temporal_renting": false, "address_privacy": "approximate", "price_calc": { "price_alq": 2000, "price_trasp": 25000 } }, "features": [ { "key": "air_conditioning", "label": "Aire Acondicionado", "value": "Sí", "isextra": false } ], "status": "disponible", "address": "San Antonio", "city": "San Antonio", "province": "Islas Baleares", "country": "España", "lat": 38.98, "lon": 1.3, "is_featured": false, "created_at": "2026-07-21T11:42:51.820440+02:00", "updated_at": "2026-09-26T19:38:41.390976+02:00" } } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/properties/1355" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1355', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/properties/1355", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, ) response.raise_for_status() data = response.json() ``` --- # Create a property URL: https://api-docs.vestta.io/properties/create Creates a private CRM property. Publication is a separate operation. Operation, pricing, location, area and characteristics are separate validated objects. Each operation needs its price: `sale`, `rent` or `transfer`. `owner_id` is required and must identify an existing holder contact in the same workspace. `subtype` is required, just as in the CRM creation modal. Send a canonical key that belongs to `type`, such as `{"type": "apartamento", "subtype": "atico"}`. Display labels such as `Ático`, empty values and subtypes from another property type return `422`. | `type` | Allowed `subtype` keys | | --- | --- | | `apartamento` | `apartamento`, `atico`, `planta_baja`, `duplex`, `estudio` | | `casa` | `adosado`, `unifamiliar`, `multifamiliar`, `rustica`, `chalet`, `villa` | | `local` | `local_comercial` | | `nave` | `industrial`, `warehouse`, `other` | | `almacenaje` | `almacen`, `trastero` | | `oficina` | `on_high`, `ground_floor` | | `terreno` | `rustico`, `urbano`, `urbanizable`, `industrial`, `terciario`, `otros` | | `aparcamiento` | `garaje`, `parking`, `amarre` | | `edificio` | `hotel`, `edificio`, `apartahotel` | The response is `201` with the new `id`. Creating a property does not make it public. Next: [upload images](/properties/uploads), then [publish](/properties/publication). Send an optional `Idempotency-Key` header (1–200 characters). For 24 hours the same key, API key and operation with the same body returns the original result, without creating another record. Reusing it with a different body returns `409`. ### POST /v1/properties Creates a private CRM property using the structured listing model. Requires the `properties:write` scope. Supports `Idempotency-Key`. Required scope: `properties:write` Request headers: - `idempotency-key` (string, optional, nullable, 1–200 chars) Request body (PropertyCreateRequest, required, application/json): - `operations` (array of strings, required) - `type` (PropertyType, required) - `subtype` (PropertySubtype, required): Canonical subtype key for the property type: apartamento: apartamento, atico, planta_baja, duplex, estudio; casa: adosado, unifamiliar, multifamiliar, rustica, chalet, villa; local: local_comercial; nave: industrial, warehouse, other; almacenaje: almacen, trastero; oficina: on_high, ground_floor; terreno: rustico, urbano, urbanizable, industrial, terciario, otros; aparcamiento: garaje, parking, amarre; edificio: hotel, edificio, apartahotel. Responses return a Spanish display label instead of this key. - `title` (string, required, 1–300 chars) - `description` (string, optional, ≤ 50000 chars, default ) - `pricing` (PropertyPricing, required) - `sale` (number, optional, nullable, ≥ 0) - `rent` (number, optional, nullable, ≥ 0) - `transfer` (number, optional, nullable, ≥ 0) - `location` (PropertyLocation, required) - `city` (string, required, 2–150 chars) - `province` (string, optional, nullable, ≤ 150 chars) - `country` (string, optional, 2–100 chars, default España) - `address` (string, required, 2–500 chars) - `full_address` (string, required, 5–1000 chars) - `postal_code` (string, optional, nullable, ≤ 20 chars) - `coordinates` (Coordinates, required) - `latitude` (number, required, ≥ -90, ≤ 90) - `longitude` (number, required, ≥ -180, ≤ 180) - `visibility` (string, optional, default approximate, values: `public` | `approximate` | `hidden`) - `area` (PropertyArea, required) - `total` (number, required, ≥ 0) - `usable` (number, optional, nullable, ≥ 0) - `plot` (number, optional, nullable, ≥ 0) - `bedrooms` (integer, optional, ≥ 0, ≤ 1000, default 0) - `bathrooms` (integer, optional, ≥ 0, ≤ 1000, default 0) - `characteristics` (PropertyCharacteristics, optional) - `translations` (TranslationSpec, optional, nullable): Traducciones de las descripciones - `ca` (TranslatedDescription, optional, nullable): Traduccion en catalán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `en` (TranslatedDescription, optional, nullable): Traduccion en ingles de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `fr` (TranslatedDescription, optional, nullable): Traduccion en francés de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `de` (TranslatedDescription, optional, nullable): Traduccion en alemán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `pt` (TranslatedDescription, optional, nullable): Traduccion en portuges de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `it` (TranslatedDescription, optional, nullable): Traduccion en italiano de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `size_built` (number, optional, nullable, ≥ 0): Superficie construida - `porch_size` (number, optional, nullable, ≥ 0): Metros cuadrados porche - `size_terraces` (number, optional, nullable, ≥ 0): Metros cuadrados terrazas - `attic_size` (number, optional, nullable, ≥ 0): Metros cuadrados ático - `storage_dimensions` (number, optional, nullable): Dimensiones del trastero - `doble_bedrooms` (integer, optional, nullable, ≥ 0): Número de habitaciones dobles - `suite_bathrooms` (integer, optional, nullable, ≥ 0): Número de baños en suite - `num_terraces` (integer, optional, nullable, ≥ 0): Número de terrazas - `conservation` (string, optional, nullable): Estado de conservación - `floor` (string, optional, nullable): Planta canónica para portales - `house_floors` (integer, optional, nullable, ≥ 1): Número de plantas de una casa - `elevator` (boolean, optional, nullable): Tiene ascensor (0/1 o Sí/No) - `views` (string, optional, nullable): Vistas de la propiedad - `orientation` (string, optional, nullable): Orientación (norte, sur, este, oeste) - `energy_certificate` (string, optional, nullable): Certificado energético A-G - `emissions` (string, optional, nullable): Emisiones A-G - `energy_consumption_value` (number, optional, nullable, ≥ 1, ≤ 999): Consumo (kWh/m² año) - `emissions_value` (number, optional, nullable, ≥ 1, ≤ 999): Emisiones (kg CO₂/m² año) - `height` (number, optional, nullable): Altura del local - `facade_meters` (number, optional, nullable): Metros de fachada - `meters_showcase` (number, optional, nullable): Metros de escaparate - `entrace_type` (string, optional, nullable): Tipo de entrada de la oficina - `position` (string, optional, nullable): 1ª/2ª Linea del mar - `offices` (integer, optional, nullable, ≥ 0): Número de despachos - `meeting_rooms` (integer, optional, nullable, ≥ 0): Número de salas de reuniones - `camino` (string, optional, nullable): Tipo de suelo - `terrain_extension` (string, optional, nullable): Tamaño (Grande/Pequeño) - `topography` (string, optional, nullable): Topografía del terreno - `num_seats` (integer, optional, nullable, ≥ 0): Número de plazas - `dimensions` (string, optional, nullable): Dimensiones del aparcamiento - `turistic_license` (string, optional, nullable): Licencia turística - `construction_year` (integer, optional, nullable): Año de construcción - `exposure` (string, optional, nullable): Interior o Exterior - `style` (string, optional, nullable): Conservación - `num_viviendas` (integer, optional, nullable): Número de viviendas - `num_locales` (integer, optional, nullable): Número de locales - `num_ascensores` (integer, optional, nullable): Número de ascensores - `num_parkings` (integer, optional, nullable, ≥ 0): Número de parkings incluidos - `num_floors` (integer, optional, nullable): Número de plantas - `luxury_property` (boolean, optional, nullable): Propiedad de lujo - `holiday_renting` (boolean, optional, nullable): Alquiler vacacional - `purchase_option_rental` (boolean, optional, nullable): Alquiler con opción a compra - `activities` (ActivitiesSpec, optional, nullable): Actividades permitidas - `predefined` (array of strings, optional): Actividades predefinidas - `custom` (array of strings, optional): Actividades personalizadas - `num_entrances` (NumEntrancesSpec, optional, nullable): Número de entradas - `total` (integer, optional, ≥ 0, default 0): Total de entradas - `peaton_entrances` (integer, optional, ≥ 0, default 0): Entradas de peatones - `moto_entrances` (integer, optional, ≥ 0, default 0): Entradas de motos - `van_entrances` (integer, optional, ≥ 0, default 0): Entradas de furgoneta - `car_entrances` (integer, optional, ≥ 0, default 0): Entradas de coche - `floor_breakdown` (FloorBreakdownSpec, optional, nullable): Desglose de plantas - `base_floor` (integer, optional, default 0): Metros ² de la planta baja - `first_floor` (integer, optional, default 0): Metros ² de la primera planta - `second_floor` (integer, optional, default 0): Metros ² de la segunda planta - `features` (array of objects, optional) - `key` (string, required, 1–100 chars) - `label` (string, required, 1–200 chars) - `value` (string | boolean | integer | number, required) - `isextra` (boolean, optional, default false) - `owner_id` (integer, required, ≥ 1): Required existing holder contact in the same business. - `is_featured` (boolean, optional, default false) - `status` (string, optional, default disponible, values: `disponible` | `reservada`) Response 201: Successful response. - `status` (string, optional, default ok, values: `ok`) - `id` (integer, required) ```json { "status": "ok", "id": 1355 } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/properties" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "operations": [ "venta" ], "type": "apartamento", "subtype": "apartamento", "title": "Apartment in Madrid", "pricing": { "sale": 350000 }, "location": { "city": "Madrid", "address": "Calle de Serrano", "full_address": "Calle de Serrano 41, 3B", "coordinates": { "latitude": 40.425318, "longitude": -3.687934 }, "visibility": "approximate" }, "area": { "total": 95 }, "bedrooms": 2, "bathrooms": 1, "owner_id": 71 }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "operations": [ "venta" ], "type": "apartamento", "subtype": "apartamento", "title": "Apartment in Madrid", "pricing": { "sale": 350000 }, "location": { "city": "Madrid", "address": "Calle de Serrano", "full_address": "Calle de Serrano 41, 3B", "coordinates": { "latitude": 40.425318, "longitude": -3.687934 }, "visibility": "approximate" }, "area": { "total": 95 }, "bedrooms": 2, "bathrooms": 1, "owner_id": 71 }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/properties", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "operations": [ "venta", ], "type": "apartamento", "subtype": "apartamento", "title": "Apartment in Madrid", "pricing": { "sale": 350000, }, "location": { "city": "Madrid", "address": "Calle de Serrano", "full_address": "Calle de Serrano 41, 3B", "coordinates": { "latitude": 40.425318, "longitude": -3.687934, }, "visibility": "approximate", }, "area": { "total": 95, }, "bedrooms": 2, "bathrooms": 1, "owner_id": 71, }, ) response.raise_for_status() data = response.json() ``` --- # Update a property URL: https://api-docs.vestta.io/properties/update Update a property without exposing its private CRM record. Only supplied top-level fields change. `pricing` and `characteristics` merge supplied fields; `location` and `area` are complete replacement objects. `features` replaces the list. Only `subtype` can be cleared with `null`. A property must retain a holder: `owner_id` cannot be cleared. To update a legacy property without a holder, supply a valid `owner_id` with the changes. When changing `type` or `subtype`, the resulting subtype must belong to the resulting type. Send both together when switching to a type with different subtype options; use the [canonical subtype keys](/properties/create). Updates to unrelated fields preserve legacy subtype values. This endpoint cannot replace image URLs or set publication directly. Use upload sessions and the publication endpoint. Updating a public property's gallery queues marked-image processing before it is made visible again. ### PATCH /v1/properties/{property_id} Updates supplied fields while preserving private CRM metadata and media. Requires the `properties:write` scope. Required scope: `properties:write` Path parameters: - `property_id` (integer, required, ≥ 1) Request body (PropertyUpdateRequest, required, application/json): - `operations` (array of strings, optional, nullable) - `type` (PropertyType, optional, nullable) - `subtype` (PropertySubtype, optional, nullable): Canonical subtype key for the property type: apartamento: apartamento, atico, planta_baja, duplex, estudio; casa: adosado, unifamiliar, multifamiliar, rustica, chalet, villa; local: local_comercial; nave: industrial, warehouse, other; almacenaje: almacen, trastero; oficina: on_high, ground_floor; terreno: rustico, urbano, urbanizable, industrial, terciario, otros; aparcamiento: garaje, parking, amarre; edificio: hotel, edificio, apartahotel. Responses return a Spanish display label instead of this key. - `title` (string, optional, nullable, 1–300 chars) - `description` (string, optional, nullable, ≤ 50000 chars) - `pricing` (PropertyPricing, optional, nullable) - `sale` (number, optional, nullable, ≥ 0) - `rent` (number, optional, nullable, ≥ 0) - `transfer` (number, optional, nullable, ≥ 0) - `location` (PropertyLocation, optional, nullable) - `city` (string, required, 2–150 chars) - `province` (string, optional, nullable, ≤ 150 chars) - `country` (string, optional, 2–100 chars, default España) - `address` (string, required, 2–500 chars) - `full_address` (string, required, 5–1000 chars) - `postal_code` (string, optional, nullable, ≤ 20 chars) - `coordinates` (Coordinates, required) - `latitude` (number, required, ≥ -90, ≤ 90) - `longitude` (number, required, ≥ -180, ≤ 180) - `visibility` (string, optional, default approximate, values: `public` | `approximate` | `hidden`) - `area` (PropertyArea, optional, nullable) - `total` (number, required, ≥ 0) - `usable` (number, optional, nullable, ≥ 0) - `plot` (number, optional, nullable, ≥ 0) - `bedrooms` (integer, optional, nullable, ≥ 0, ≤ 1000) - `bathrooms` (integer, optional, nullable, ≥ 0, ≤ 1000) - `characteristics` (PropertyCharacteristics, optional, nullable) - `translations` (TranslationSpec, optional, nullable): Traducciones de las descripciones - `ca` (TranslatedDescription, optional, nullable): Traduccion en catalán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `en` (TranslatedDescription, optional, nullable): Traduccion en ingles de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `fr` (TranslatedDescription, optional, nullable): Traduccion en francés de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `de` (TranslatedDescription, optional, nullable): Traduccion en alemán de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `pt` (TranslatedDescription, optional, nullable): Traduccion en portuges de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `it` (TranslatedDescription, optional, nullable): Traduccion en italiano de la descripción - `title` (string, optional, nullable): Título de la descripción - `description` (string, optional, nullable): Descripción - `size_built` (number, optional, nullable, ≥ 0): Superficie construida - `porch_size` (number, optional, nullable, ≥ 0): Metros cuadrados porche - `size_terraces` (number, optional, nullable, ≥ 0): Metros cuadrados terrazas - `attic_size` (number, optional, nullable, ≥ 0): Metros cuadrados ático - `storage_dimensions` (number, optional, nullable): Dimensiones del trastero - `doble_bedrooms` (integer, optional, nullable, ≥ 0): Número de habitaciones dobles - `suite_bathrooms` (integer, optional, nullable, ≥ 0): Número de baños en suite - `num_terraces` (integer, optional, nullable, ≥ 0): Número de terrazas - `conservation` (string, optional, nullable): Estado de conservación - `floor` (string, optional, nullable): Planta canónica para portales - `house_floors` (integer, optional, nullable, ≥ 1): Número de plantas de una casa - `elevator` (boolean, optional, nullable): Tiene ascensor (0/1 o Sí/No) - `views` (string, optional, nullable): Vistas de la propiedad - `orientation` (string, optional, nullable): Orientación (norte, sur, este, oeste) - `energy_certificate` (string, optional, nullable): Certificado energético A-G - `emissions` (string, optional, nullable): Emisiones A-G - `energy_consumption_value` (number, optional, nullable, ≥ 1, ≤ 999): Consumo (kWh/m² año) - `emissions_value` (number, optional, nullable, ≥ 1, ≤ 999): Emisiones (kg CO₂/m² año) - `height` (number, optional, nullable): Altura del local - `facade_meters` (number, optional, nullable): Metros de fachada - `meters_showcase` (number, optional, nullable): Metros de escaparate - `entrace_type` (string, optional, nullable): Tipo de entrada de la oficina - `position` (string, optional, nullable): 1ª/2ª Linea del mar - `offices` (integer, optional, nullable, ≥ 0): Número de despachos - `meeting_rooms` (integer, optional, nullable, ≥ 0): Número de salas de reuniones - `camino` (string, optional, nullable): Tipo de suelo - `terrain_extension` (string, optional, nullable): Tamaño (Grande/Pequeño) - `topography` (string, optional, nullable): Topografía del terreno - `num_seats` (integer, optional, nullable, ≥ 0): Número de plazas - `dimensions` (string, optional, nullable): Dimensiones del aparcamiento - `turistic_license` (string, optional, nullable): Licencia turística - `construction_year` (integer, optional, nullable): Año de construcción - `exposure` (string, optional, nullable): Interior o Exterior - `style` (string, optional, nullable): Conservación - `num_viviendas` (integer, optional, nullable): Número de viviendas - `num_locales` (integer, optional, nullable): Número de locales - `num_ascensores` (integer, optional, nullable): Número de ascensores - `num_parkings` (integer, optional, nullable, ≥ 0): Número de parkings incluidos - `num_floors` (integer, optional, nullable): Número de plantas - `luxury_property` (boolean, optional, nullable): Propiedad de lujo - `holiday_renting` (boolean, optional, nullable): Alquiler vacacional - `purchase_option_rental` (boolean, optional, nullable): Alquiler con opción a compra - `activities` (ActivitiesSpec, optional, nullable): Actividades permitidas - `predefined` (array of strings, optional): Actividades predefinidas - `custom` (array of strings, optional): Actividades personalizadas - `num_entrances` (NumEntrancesSpec, optional, nullable): Número de entradas - `total` (integer, optional, ≥ 0, default 0): Total de entradas - `peaton_entrances` (integer, optional, ≥ 0, default 0): Entradas de peatones - `moto_entrances` (integer, optional, ≥ 0, default 0): Entradas de motos - `van_entrances` (integer, optional, ≥ 0, default 0): Entradas de furgoneta - `car_entrances` (integer, optional, ≥ 0, default 0): Entradas de coche - `floor_breakdown` (FloorBreakdownSpec, optional, nullable): Desglose de plantas - `base_floor` (integer, optional, default 0): Metros ² de la planta baja - `first_floor` (integer, optional, default 0): Metros ² de la primera planta - `second_floor` (integer, optional, default 0): Metros ² de la segunda planta - `features` (array of objects, optional, nullable) - `key` (string, required, 1–100 chars) - `label` (string, required, 1–200 chars) - `value` (string | boolean | integer | number, required) - `isextra` (boolean, optional, default false) - `owner_id` (integer, optional, nullable, ≥ 1) - `is_featured` (boolean, optional, nullable) - `status` (string, optional, nullable, values: `disponible` | `reservada` | `retirado` | `vendida` | `alquilada`) Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `id` (integer, required) ```json { "status": "ok", "id": 1355 } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X PATCH "https://api.vestta.io/v1/properties/1" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Updated apartment title", "pricing": { "sale": 340000 } }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1', { method: 'PATCH', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "title": "Updated apartment title", "pricing": { "sale": 340000 } }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.patch( "https://api.vestta.io/v1/properties/1", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "title": "Updated apartment title", "pricing": { "sale": 340000, }, }, ) response.raise_for_status() data = response.json() ``` --- # Prepare image uploads URL: https://api-docs.vestta.io/properties/uploads Get temporary PUT URLs for original image uploads. Send file metadata to reserve an upload session. Upload each accepted file's bytes directly to `upload_url` with HTTP `PUT` and the declared `Content-Type`. Do not send your Vestta API key to the storage URL. Files must be JPEG, PNG or WebP, at most 10 MiB each. A property can contain at most 15 images. `file_id` is your correlation ID and must be unique within the session. The original goes into private storage. An upload URL is temporary, permits upload only and is not a public photo URL. Inspect `rejected` before continuing; complete only accepted uploads. ### POST /v1/properties/{property_id}/images/uploads Returns short-lived PUT URLs into private storage. Upload each file, then complete the session. No original download URL is returned. Requires the `properties:write` scope. Required scope: `properties:write` Path parameters: - `property_id` (integer, required, ≥ 1) Request body (ImageUploadRequest, required, application/json): - `files` (array of objects, required) - `file_id` (string, required, 1–100 chars) - `filename` (string, required, 1–255 chars) - `content_type` (string, required, values: `image/jpeg` | `image/png` | `image/webp`) - `size` (integer, required, > 0, ≤ 10485760) Response 201: Successful response. - `session_id` (string, required) - `accepted` (array of objects, required) - `file_id` (string, required) - `upload_id` (string, required) - `upload_url` (string, required) - `rejected` (array of objects, required) - `file_id` (string, required) - `filename` (string, required) - `reason` (string, required) ```json { "session_id": "upl_21_example", "accepted": [ { "file_id": "photo-1", "upload_id": "1234567890ABCDEF", "upload_url": "https://private-storage.example/upload?signed=temporary" } ], "rejected": [] } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/properties/1/images/uploads" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "files": [ { "file_id": "photo-1", "filename": "living-room.jpg", "content_type": "image/jpeg", "size": 125000 } ] }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1/images/uploads', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "files": [ { "file_id": "photo-1", "filename": "living-room.jpg", "content_type": "image/jpeg", "size": 125000 } ] }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/properties/1/images/uploads", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "files": [ { "file_id": "photo-1", "filename": "living-room.jpg", "content_type": "image/jpeg", "size": 125000, }, ], }, ) response.raise_for_status() data = response.json() ``` --- # Complete image uploads URL: https://api-docs.vestta.io/properties/complete-uploads Verify uploaded originals and attach them to the property. Use the returned `session_id` as the path's `upload_id`. Supply each accepted `file_id`, title, order and primary flag after its PUT succeeds. The session is bound to the property and workspace. Completion validates the stored bytes before attaching them. Repeating completion with the same session and metadata is safe while the session remains valid. The response contains image references, never original download URLs. New static images larger than 1 MiB are gently optimized during completion: up to 2560 pixels on the longest side and JPEG quality 90. Opaque photographs may change to JPEG; transparency is retained as PNG. No WebP is generated. A smaller result is adopted; 1 MiB is the processing threshold, not a final size limit. Images at or below the threshold retain their exact bytes, as do animated or multi-page images. The returned filename, content type and file size describe the stored result. Next: [publish](/properties/publication) to generate public marked copies. ### POST /v1/properties/{property_id}/images/uploads/{upload_id}/complete Verifies uploaded originals and attaches them to the property. Publish to generate the public copies. Requires the `properties:write` scope. Required scope: `properties:write` Path parameters: - `upload_id` (string, required) - `property_id` (integer, required, ≥ 1) Request body (ImageUploadCompleteRequest, required, application/json): - `images` (array of objects, required) - `file_id` (string, required, 1–100 chars) - `title` (string, optional, ≤ 200 chars, default ) - `is_primary` (boolean, optional, default false) - `order` (integer, optional, nullable, ≥ 1) Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `property_id` (integer, required) - `images` (array of objects, required) - `id` (string, required) - `title` (string, optional, default ) - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) ```json { "status": "ok", "property_id": 1355, "images": [ { "id": "1234567890ABCDEF", "title": "Living room", "order": 1, "is_primary": true } ] } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/properties/1/images/uploads/session-id-from-upload-response/complete" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "images": [ { "file_id": "photo-1", "title": "Living room", "is_primary": true, "order": 1 } ] }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1/images/uploads/session-id-from-upload-response/complete', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "images": [ { "file_id": "photo-1", "title": "Living room", "is_primary": true, "order": 1 } ] }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/properties/1/images/uploads/session-id-from-upload-response/complete", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "images": [ { "file_id": "photo-1", "title": "Living room", "is_primary": True, "order": 1, }, ], }, ) response.raise_for_status() data = response.json() ``` --- # Publish or unpublish URL: https://api-docs.vestta.io/properties/publication Set desired visibility and generate protected public images. Send `{"published": true}` to publish. The response is `202 Accepted`, with `Location` and `Retry-After: 2`. Follow [publication status](/properties/publication-status) until `published` is true. A property remains private while processing or after an error. Send `{"published": false}` to remove it from the catalogue immediately (`200`). A pending worker cannot publish it afterwards. This does not guarantee removal of images already downloaded or cached by third parties. Publication is an explicit choice, independent of commercial status. Save the property before publishing; external API requests also require type, operation, title and city. Each public photo is a permanent copy with an independent random ID. New photos are watermarked; existing photos grandfathered during migration may remain unmarked. No original path, filename or private storage URL is returned. ### PUT /v1/properties/{property_id}/publication Sets desired visibility. Publishing returns 202 while public copies are prepared; new photos are watermarked. Unpublishing returns 200. Poll Retrieve publication until published or failed. Requires the `properties:publish` scope. Required scope: `properties:publish` Path parameters: - `property_id` (integer, required, ≥ 1) Request body (PublicationRequest, required, application/json): - `published` (boolean, required): Desired visibility. Publishing prepares public copies before making the property public; new photos are watermarked. Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `data` (PublicationState, required) - `status` (string, required, values: `private` | `pending` | `processing` | `published` | `ready` | `failed`) - `published` (boolean, required) - `requested` (boolean, required) - `images` (array of objects, optional) - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `error` (string, optional, nullable): Safe diagnostic code. Retry the same publication request after correcting the cause. ```json { "status": "ok", "data": { "status": "private", "published": false, "requested": false, "images": [] } } ``` Response 202: Accepted - `status` (string, optional, default ok, values: `ok`) - `data` (PublicationState, required) - `status` (string, required, values: `private` | `pending` | `processing` | `published` | `ready` | `failed`) - `published` (boolean, required) - `requested` (boolean, required) - `images` (array of objects, optional) - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `error` (string, optional, nullable): Safe diagnostic code. Retry the same publication request after correcting the cause. ```json { "status": "ok", "data": { "status": "private", "published": false, "requested": false, "images": [] } } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X PUT "https://api.vestta.io/v1/properties/1/publication" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "published": true }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1/publication', { method: 'PUT', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "published": true }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.put( "https://api.vestta.io/v1/properties/1/publication", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "published": True, }, ) response.raise_for_status() data = response.json() ``` --- # Retrieve publication status URL: https://api-docs.vestta.io/properties/publication-status Check requested visibility, processing state and marked images. `status` is `private`, `pending`, `processing`, `published`, `ready` or `failed`. `requested` is desired catalogue visibility; `published` is effective visibility. `ready` means public copies are available for an export without publishing the property. New photos are watermarked; migration-grandfathered photos retain their unmarked copies. While pending or processing, poll every two seconds. When `failed`, inspect the safe `error` code, fix the cause and repeat the publication request. Automatic retries are bounded; do not busy-loop failed requests. ### GET /v1/properties/{property_id}/publication Returns processing status and opaque public image URLs, including approved legacy copies. Requires the `properties:publish` scope. Required scope: `properties:publish` Path parameters: - `property_id` (integer, required, ≥ 1) Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `data` (PublicationState, required) - `status` (string, required, values: `private` | `pending` | `processing` | `published` | `ready` | `failed`) - `published` (boolean, required) - `requested` (boolean, required) - `images` (array of objects, optional) - `id` (string, required) - `url` (string, required): Permanent opaque public-copy URL. New photos are watermarked; migrated legacy copies may remain unmarked. Never an original or upload URL. - `order` (integer, optional, default 1) - `is_primary` (boolean, optional, default false) - `title` (string, optional, default ) - `error` (string, optional, nullable): Safe diagnostic code. Retry the same publication request after correcting the cause. ```json { "status": "ok", "data": { "status": "private", "published": false, "requested": false, "images": [] } } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/properties/1/publication" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/properties/1/publication', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/properties/1/publication", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, ) response.raise_for_status() data = response.json() ``` --- # Leads URL: https://api-docs.vestta.io/leads Read the leads of a Vestta workspace and send new leads from your forms and services. A lead is a contact the agency works with: someone looking to buy or rent (`demandante`), an owner (`propietario`), or a partner such as another agency, a bank or a service provider. Leads carry contact details and, for people searching, **search preferences** that Vestta uses to match them against the property catalogue. ## Endpoints - `GET /v1/leads` — List contacts (https://api-docs.vestta.io/leads/list) - `POST /v1/leads` — Create a contact (https://api-docs.vestta.io/leads/create) - `GET /v1/leads/{lead_id}` — Retrieve a contact (https://api-docs.vestta.io/leads/retrieve) - `PATCH /v1/leads/{lead_id}` — Update a contact (https://api-docs.vestta.io/leads/update) - `POST /v1/leads/ingest` — Ingest a rental lead (https://api-docs.vestta.io/leads/ingest) - `POST /v1/leads/inquiries` — Create an inquiry (https://api-docs.vestta.io/leads/inquiries) ## Choosing an endpoint [Create a contact](/leads/create) (`POST /v1/leads`, scope `leads:write`) is the canonical endpoint for CRM integrations. It accepts a strict contact model, supports `Idempotency-Key`, returns the ID and does not trigger outreach. Use [retrieve](/leads/retrieve) and [update](/leads/update) for its subsequent lifecycle. Contacts remain private to the workspace. The two form adapters below preserve their existing outreach behavior: | | [Ingest a rental lead](/leads/ingest) | [Create an inquiry](/leads/inquiries) | | --- | --- | --- | | Payload | Compact rental-form format | Full lead: contact details and structured search preferences | | Lead type | Always `demandante` | From `type` (`buyer`, `owner`…) | | Search preferences | Derived: rent an apartment or house, maximum rent from `budget`, minimum bedrooms, one location | Exactly what you send in `search_preferences` | | Urgency | `alta-urgencia` | `poca-urgencia` unless you send it | | Phone already in the workspace | Nothing is created; still returns `200` | Completes the existing lead if it has no name; otherwise `409` | | Returns the lead ID | No | Yes, `lead_id` | | Follow-up scheduling | No | Yes | | Scope | `leads:ingest` | `leads:ingest` | Use Create an inquiry when submitting a form that should trigger matching and outreach. Ingest a rental lead exists for rental landing pages that already send its compact format. [List leads](/leads/list) is read-only and needs the separate `leads:read` scope. ## What happens after a lead is created The two form adapters respond as soon as the lead is stored. Then, in the background, Vestta: 1. **Matches** the lead against the property catalogue, using its search preferences. 2. **Contacts the lead on WhatsApp**, if the workspace has WhatsApp connected: one approved template message, sent once per lead, after which the Vestta assistant can carry on the conversation when the lead replies. 3. For inquiries only, **schedules follow-ups**. For people searching, every 30 days if they want to rent and every 90 days if they want to buy or take over a business, based on the operations in `search_preferences`; for other lead types, according to the workspace's follow-up rules. None of this changes the response. If WhatsApp is not connected, the lead is still created. ## Phone numbers The primary phone identifies a lead within a workspace: two leads cannot share it. Send numbers in international format, such as `+34600111222`. Numbers without a prefix are read as Spanish, and numbers that are not valid phone numbers are rejected with `422`. ## The lead object List leads returns lead objects with these fields. Fields without a value are omitted. - `id` (integer, required): Numeric lead ID. - `name` (string, optional, nullable) - `type` (string, optional, nullable): `demandante` (looking for a property), `propietario` (owner), `agencia-inmobiliaria`, `entidad-bancaria` or `proveedor-servicios`. - `status` (string, optional, nullable): Pipeline status, e.g. `new`, `searching_property`, `active_negotiation`, `closed` or `inactive`. - `active` (boolean, optional, nullable) - `source` (string, optional, nullable): Where the lead came from, e.g. `web`, `manual`, or the `source` sent on ingestion. - `phone_number_1` (string, optional, nullable): Primary phone in E.164 format. - `phone_number_2` (string, optional, nullable) - `landline_phone` (string, optional, nullable) - `personal_email` (string, optional, nullable) - `professional_email` (string, optional, nullable) - `preferred_language` (string, optional, nullable): `es`, `gb`, `fr`, `ge` or `it`. - `search_preferences` (array of objects, optional, nullable): Structured search requests without internal notes. - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `locations` (array of objects, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. Leads are ordered by this field, newest first. - `updated_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. --- # List leads URL: https://api-docs.vestta.io/leads/list Return the leads of the workspace, newest first. Returns every lead of the workspace — whatever its type or status, and however it was created — ordered by creation date, newest first. Leads contain personal data: names, phone numbers and emails. Grant `leads:read` only to systems that need it, such as a CRM sync, and never to a key used by a public website. Internal CRM data is not part of the response: notes, ID documents, rating and scoring, assigned agent, capture details and follow-up dates stay in Vestta. ## Pagination `count` is the number of leads **in this page**, not the total. Keep requesting pages while `count` equals `limit`. See [Pagination](/pagination#paging-through-leads). The endpoint has no filters. To pick up new leads periodically, page from `offset=0` and stop when you reach a `created_at` (or an `id`) you have already processed. ### GET /v1/leads Lists the business contacts. Requires the `leads:read` scope. Required scope: `leads:read` Query parameters: - `limit` (integer, optional, ≥ 1, ≤ 1000, default 100) - `offset` (integer, optional, ≥ 0, default 0) Response 200: Successful response. - `status` (string, required, values: `ok`) - `data` (array of objects, required) - `id` (integer, required): Numeric lead ID. - `name` (string, optional, nullable) - `type` (string, optional, nullable): `demandante` (looking for a property), `propietario` (owner), `agencia-inmobiliaria`, `entidad-bancaria` or `proveedor-servicios`. - `status` (string, optional, nullable): Pipeline status, e.g. `new`, `searching_property`, `active_negotiation`, `closed` or `inactive`. - `active` (boolean, optional, nullable) - `source` (string, optional, nullable): Where the lead came from, e.g. `web`, `manual`, or the `source` sent on ingestion. - `phone_number_1` (string, optional, nullable): Primary phone in E.164 format. - `phone_number_2` (string, optional, nullable) - `landline_phone` (string, optional, nullable) - `personal_email` (string, optional, nullable) - `professional_email` (string, optional, nullable) - `preferred_language` (string, optional, nullable): `es`, `gb`, `fr`, `ge` or `it`. - `search_preferences` (array of objects, optional, nullable): Structured search requests without internal notes. - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `locations` (array of objects, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. Leads are ordered by this field, newest first. - `updated_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. - `count` (integer, required): Total contacts in the business, across all pages. - `limit` (integer, required): The `limit` that was applied. - `offset` (integer, required): The `offset` that was applied. - `authenticated_as` (string, optional, nullable): Name of the business that owns the API key. ```json { "status": "ok", "data": [ { "id": 227, "name": "Ana García", "type": "demandante", "status": "searching_property", "active": true, "source": "web", "phone_number_1": "+34600111222", "preferred_language": "es", "search_preferences": [ { "operations": [ "alquiler" ], "property_types": [ "apartamento" ], "locations": [ { "name": "Madrid" } ] } ], "created_at": "2026-09-29T18:24:55.569028+02:00", "updated_at": "2026-09-29T18:24:55.569028+02:00" } ], "count": 1, "limit": 20, "offset": 0, "authenticated_as": "Inmobiliaria Ejemplo" } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/leads?limit=20" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads?limit=20', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/leads", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, params={ "limit": 20, }, ) response.raise_for_status() data = response.json() ``` --- # Retrieve a contact URL: https://api-docs.vestta.io/leads/retrieve Retrieve a contact belonging to your workspace. Requires `leads:read`, which exposes personal contact details. Keep this permission on trusted server integrations, not on a public website. Unknown IDs and contacts from another workspace both return `404`. ### GET /v1/leads/{lead_id} Retrieves a contact belonging to the business. Requires the `leads:read` scope. Required scope: `leads:read` Path parameters: - `lead_id` (integer, required, ≥ 1) Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `data` (ExternalLead, required) - `id` (integer, required): Numeric lead ID. - `name` (string, optional, nullable) - `type` (string, optional, nullable): `demandante` (looking for a property), `propietario` (owner), `agencia-inmobiliaria`, `entidad-bancaria` or `proveedor-servicios`. - `status` (string, optional, nullable): Pipeline status, e.g. `new`, `searching_property`, `active_negotiation`, `closed` or `inactive`. - `active` (boolean, optional, nullable) - `source` (string, optional, nullable): Where the lead came from, e.g. `web`, `manual`, or the `source` sent on ingestion. - `phone_number_1` (string, optional, nullable): Primary phone in E.164 format. - `phone_number_2` (string, optional, nullable) - `landline_phone` (string, optional, nullable) - `personal_email` (string, optional, nullable) - `professional_email` (string, optional, nullable) - `preferred_language` (string, optional, nullable): `es`, `gb`, `fr`, `ge` or `it`. - `search_preferences` (array of objects, optional, nullable): Structured search requests without internal notes. - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `locations` (array of objects, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) - `created_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. Leads are ordered by this field, newest first. - `updated_at` (string, optional, nullable): ISO 8601 timestamp with UTC offset. Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/leads/1" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads/1', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/leads/1", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, ) response.raise_for_status() data = response.json() ``` --- # Create a contact URL: https://api-docs.vestta.io/leads/create Create a private CRM contact without initiating outreach. Requires `leads:write`. The canonical contact types are `demandante`, `propietario`, `agencia-inmobiliaria`, `entidad-bancaria` and `proveedor-servicios`. Phone numbers are normalized to international E.164; email addresses are validated. Use `notes` for general CRM contact notes (up to 50,000 characters) and `rating` for an integer star rating from `0` to `5`; `0` means unrated and is the default. Both fields are optional and remain private: lead reads do not return them. `search_preferences[].internal_notes` holds notes about an individual search request. It remains supported independently of the contact's `notes` and is also excluded from lead reads. The response is `201` with the new `id`. Contacts and their personal data are private to the workspace; this operation does not publish them on the property portal or start automated outreach. Use [Create an inquiry](/leads/inquiries) for a form with configured follow-up. The optional `Idempotency-Key` header has the same 24-hour replay and conflict rules as property creation. ### POST /v1/leads Creates a CRM contact without initiating outreach. Requires the `leads:write` scope. Supports `Idempotency-Key`. Required scope: `leads:write` Request headers: - `idempotency-key` (string, optional, nullable, 1–200 chars) Request body (LeadCreateRequest, required, application/json): - `name` (string, required, 1–200 chars) - `type` (string, required, values: `demandante` | `propietario` | `agencia-inmobiliaria` | `entidad-bancaria` | `proveedor-servicios`) - `phone_number_1` (string, required, 5–30 chars) - `phone_number_2` (string, optional, nullable, ≤ 30 chars) - `landline_phone` (string, optional, nullable, ≤ 30 chars) - `personal_email` (string, optional, nullable, ≤ 254 chars) - `professional_email` (string, optional, nullable, ≤ 254 chars) - `preferred_language` (string, optional, default es, values: `es` | `gb` | `fr` | `ge` | `it`) - `active` (boolean, optional, default true) - `source` (string, optional, 1–100 chars, default external_api) - `notes` (string, optional, nullable, ≤ 50000 chars): Private CRM contact notes. Not returned by lead reads. - `rating` (integer, optional, ≥ 0, ≤ 5, default 0): CRM star rating from 0 (unrated) to 5. Not returned by lead reads. - `search_preferences` (array of objects, optional) - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `locations` (array of objects, optional) - `internal_notes` (string, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) Response 201: Successful response. - `status` (string, optional, default ok, values: `ok`) - `id` (integer, required) ```json { "status": "ok", "id": 1355 } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/leads" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Ana García", "type": "demandante", "phone_number_1": "+34600111222", "source": "integration", "notes": "Prefiere visitas por la tarde.", "rating": 4 }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "name": "Ana García", "type": "demandante", "phone_number_1": "+34600111222", "source": "integration", "notes": "Prefiere visitas por la tarde.", "rating": 4 }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/leads", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "name": "Ana García", "type": "demandante", "phone_number_1": "+34600111222", "source": "integration", "notes": "Prefiere visitas por la tarde.", "rating": 4, }, ) response.raise_for_status() data = response.json() ``` --- # Update a contact URL: https://api-docs.vestta.io/leads/update Update only supplied contact fields. Requires `leads:write`. Omitted fields, internal CRM metadata and related records are preserved. Supply `null` to clear a secondary phone, landline or email. Required fields cannot be cleared. `search_preferences` replaces the preference list. `notes` and `rating` can also be updated. Set `notes` to `null` to clear it; set `rating` to `0` to remove the star rating. Ratings must be integers from `0` to `5` and cannot be `null`. Omitted notes and ratings keep their saved values. Neither field is returned by lead reads. ### PATCH /v1/leads/{lead_id} Updates only supplied fields. Requires the `leads:write` scope. Required scope: `leads:write` Path parameters: - `lead_id` (integer, required, ≥ 1) Request body (LeadUpdateRequest, required, application/json): - `name` (string, optional, nullable, 1–200 chars) - `type` (string, optional, nullable, values: `demandante` | `propietario` | `agencia-inmobiliaria` | `entidad-bancaria` | `proveedor-servicios`) - `phone_number_1` (string, optional, nullable, 5–30 chars) - `phone_number_2` (string, optional, nullable, ≤ 30 chars) - `landline_phone` (string, optional, nullable, ≤ 30 chars) - `personal_email` (string, optional, nullable, ≤ 254 chars) - `professional_email` (string, optional, nullable, ≤ 254 chars) - `preferred_language` (string, optional, nullable, values: `es` | `gb` | `fr` | `ge` | `it`) - `active` (boolean, optional, nullable) - `source` (string, optional, nullable, 1–100 chars) - `notes` (string, optional, nullable, ≤ 50000 chars): Private CRM contact notes. Use null to clear them. - `rating` (integer, optional, nullable, ≥ 0, ≤ 5): CRM star rating from 0 (unrated) to 5. Use 0 to reset it. - `search_preferences` (array of objects, optional, nullable) - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `locations` (array of objects, optional) - `internal_notes` (string, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) Response 200: Successful response. - `status` (string, optional, default ok, values: `ok`) - `id` (integer, required) ```json { "status": "ok", "id": 1355 } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X PATCH "https://api.vestta.io/v1/leads/1" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Ana García", "personal_email": "ana@example.com" }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads/1', { method: 'PATCH', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "name": "Ana García", "personal_email": "ana@example.com" }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.patch( "https://api.vestta.io/v1/leads/1", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "name": "Ana García", "personal_email": "ana@example.com", }, ) response.raise_for_status() data = response.json() ``` --- # Ingest a rental lead URL: https://api-docs.vestta.io/leads/ingest Create a rental-seeking lead from the compact payload used by rental landing forms. Creates a lead of type `demandante` from a rental form submission, with a readable summary in its notes and a tenant profile. General search forms also create a search request from the criteria sent, even when partial. Forms about a specific property (`propertyId`) save the candidacy without creating a general search request. For full control over the lead, use [Create an inquiry](/leads/inquiries) instead. ## How the payload is used | Field | What Vestta does with it | | --- | --- | | `contact.name` | Lead name. | | `contact` phone fields | The first value that is a valid phone number becomes the primary phone, in this order: `areaCode` + `phoneNumber`, `phoneE164`, `phone`, `phoneRaw`. | | `search.budget` | For general searches, the upper bound becomes the maximum monthly rent. `1200` and `900-1200` both mean 1,200 €. Empty means unknown. | | `search.habs` | For general searches, minimum bedrooms for apartments and houses. Empty means unknown. | | `search.location` | For general searches, the location used for matching. `{}` means unknown. | | `source` | Lead source. | | `sourcePage`, `search.entryDate`, `search.exitDate`, `search.people`, `search.area`, `search.pets`, `search.workSituation`, `search.freeText` | Written into the lead notes for the agent. The ones Vestta can read also fill the tenant profile (see below). | | `tenant` | Optional. Structured tenant data stored as the contact's tenant profile. | | `propertyId` | Optional. The property the form was about: the contact becomes a candidate of its open rental, without a general search request. Search criteria remain in the notes. | | `id`, `createdAt` | Required, but not stored. Use them for your own tracing. | All new leads have rating 3 and high urgency (`alta-urgencia`). Without `propertyId`, sending a budget, bedroom count or location creates a general residential search with operation `alquiler` and property types `apartamento` and `casa`; missing criteria remain unset. A profile alone (income, employment, pets, occupants or dates) does not create a search request. Leads without a search request start with status `new`; those with one start with `searching_property`. For general searches, a nonempty `search.budget` must be a whole number or a range of whole numbers, and nonempty `search.habs` must be a non-negative whole number. Invalid numeric values fail with `422`. Leave unknown values empty. Property-specific submissions keep these values in the notes without requiring search criteria. ## Tenant profile and rental applications Each lead keeps one tenant profile, which Vestta compares with the requirements of every rental the agency is marketing. It is filled from: - `search.people` (a number of occupants), `search.pets` (`No`, `Sí`, `Sí, un gato`…), `search.workSituation` (`Contrato indefinido`, `Autónomo`, `Estudiante`…), `search.entryDate` and `search.exitDate` (as `YYYY-MM-DD`, for the move-in date and the length of stay). A value Vestta cannot read is left out of the profile, never guessed. - `tenant`, when you send it. Its fields always win over what was read from `search`, and it is the only way to send the household's net monthly income (`monthlyIncome`), smokers, a guarantor or the contact's consent to hear about other rentals (`benchConsent`). With `propertyId`, the contact is added as a candidate of that property's open rental and rated against its requirements right away. If the property has no open rental, or the lead cannot be a tenant, the lead is still created and nothing else happens: the request does not fail. ## Duplicates If the workspace already has a lead with the same primary phone, **nothing is created and the response is still `200`**, without a lead ID. The existing lead is not updated, except for its tenant profile and, with `propertyId`, its rental application: answers are merged into the profile and the contact is added as a candidate unless they already are. This makes retries safe. If no phone field holds a valid number, the request fails with `422` and the message `Invalid phone number. Use international format, e.g. +34600111222`. ### POST /v1/leads/ingest Accepts the existing rental landing payload. Duplicate phones are ignored. Requires the `leads:ingest` scope. Required scope: `leads:ingest` Request body (RentingLead, required, application/json): - `id` (string, required): Your identifier for the submission. Required, but not stored by Vestta. - `createdAt` (string, required): When the form was submitted, ISO 8601. Required, but not stored by Vestta. - `source` (string, required): Where the lead comes from, e.g. `web`. Stored as the lead source. - `sourcePage` (string, required): URL of the page with the form. Added to the lead notes. - `contact` (RentingLeadContact, required) - `name` (string, required): Contact's full name. Stored as the lead name. - `phone` (string, required): Phone number. Include the international prefix (`+34600111222`); numbers without one are read as Spanish. - `phoneRaw` (string, optional, nullable): Phone exactly as typed. Used only when no other phone field can be normalised. - `areaCode` (string, optional, nullable): International prefix, e.g. `+34`. Combined with `phoneNumber` and tried first. - `phoneNumber` (string, optional, nullable): National number without prefix. Combined with `areaCode`. - `phoneE164` (string, optional, nullable): Phone already in E.164 format. Tried after `areaCode` + `phoneNumber`. - `search` (RentingLeadSearch, required) - `budget` (string, required): Monthly budget in euros: a whole number (`1200`), a range (`900-1200`), or empty when unknown. For general searches, the upper bound becomes the maximum rent. With `propertyId`, kept only in the notes. - `entryDate` (string, required): Desired move-in date. Free text, added to the lead notes; `YYYY-MM-DD` recommended. - `exitDate` (string, required): Desired move-out date. Free text, added to the lead notes. - `people` (string, required): Number of occupants. Added to the lead notes. - `area` (string, required): Preferred area, as free text. Added to the lead notes. - `habs` (string, required): Minimum bedrooms as a whole number, or empty when unknown. For general searches, stored for apartments and houses. With `propertyId`, kept only in the notes. - `pets` (string, required): Whether the occupants have pets. Added to the lead notes. - `workSituation` (string, required): Employment situation. Added to the lead notes. - `location` (object, required): Location for a general search, e.g. `{"name": "Madrid"}`, or a map area with `geometry`. Use `{}` when unknown. With `propertyId`, kept only in the notes. - `freeText` (string, required): Free-text message from the contact. Added to the lead notes. - `tenant` (RentingLeadTenant, optional, nullable): Structured tenant data. Stored as the contact's tenant profile, which rates them against each rental's requirements. - `occupants` (integer, optional, nullable, ≥ 1, ≤ 20): People who would live in the home. - `monthlyIncome` (number, optional, nullable, ≥ 0, ≤ 1000000): Net monthly income of the whole household, in euros. - `employment` (string, optional, nullable, values: `indefinido` | `temporal` | `funcionario` | `autonomo` | `pensionista` | `estudiante` | `desempleado` | `otro`): Employment situation: permanent contract (`indefinido`), temporary, civil servant, self-employed, pensioner, student, unemployed or other. - `pets` (boolean, optional, nullable): Whether they have pets. - `petsDetail` (string, optional, nullable, ≤ 120 chars): Which pets, e.g. `a small dog`. - `smoker` (boolean, optional, nullable): Whether anyone smokes. - `guarantor` (boolean, optional, nullable): Whether they have a guarantor or can add a guarantee. - `moveIn` (string, optional, nullable): Desired move-in date. - `stayMonths` (integer, optional, nullable, ≥ 1, ≤ 600): How many months they want to stay. - `benchConsent` (boolean, optional, nullable): They agree to hear about other rentals that fit them. - `propertyId` (integer, optional, nullable, ≥ 1): Vestta property the form was about. When it has an open rental, the contact becomes a candidate of it. No general search request is created for a property-specific submission, even without an open rental. Response 200: Successful response. - `status` (string, required, values: `ok`) - `authenticated_as` (string, optional, nullable): Name of the business that owns the API key. ```json { "status": "ok", "authenticated_as": "Inmobiliaria Ejemplo" } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/leads/ingest" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "id": "web-123", "createdAt": "2026-09-22T10:30:00Z", "source": "web", "sourcePage": "https://example.com/alquiler", "contact": { "name": "Ana García", "phone": "+34600111222" }, "search": { "budget": "900-1200", "entryDate": "2026-10-01", "exitDate": "2027-09-30", "people": "2", "area": "Madrid centro", "habs": "2", "pets": "No", "workSituation": "Contrato indefinido", "location": { "name": "Madrid" }, "freeText": "Preferimos una vivienda amueblada" } }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads/ingest', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "id": "web-123", "createdAt": "2026-09-22T10:30:00Z", "source": "web", "sourcePage": "https://example.com/alquiler", "contact": { "name": "Ana García", "phone": "+34600111222" }, "search": { "budget": "900-1200", "entryDate": "2026-10-01", "exitDate": "2027-09-30", "people": "2", "area": "Madrid centro", "habs": "2", "pets": "No", "workSituation": "Contrato indefinido", "location": { "name": "Madrid" }, "freeText": "Preferimos una vivienda amueblada" } }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/leads/ingest", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "id": "web-123", "createdAt": "2026-09-22T10:30:00Z", "source": "web", "sourcePage": "https://example.com/alquiler", "contact": { "name": "Ana García", "phone": "+34600111222", }, "search": { "budget": "900-1200", "entryDate": "2026-10-01", "exitDate": "2027-09-30", "people": "2", "area": "Madrid centro", "habs": "2", "pets": "No", "workSituation": "Contrato indefinido", "location": { "name": "Madrid", }, "freeText": "Preferimos una vivienda amueblada", }, }, ) response.raise_for_status() data = response.json() ``` --- # Create an inquiry URL: https://api-docs.vestta.io/leads/inquiries Create a lead with contact details and structured search preferences, and get its ID back. Creates a lead from a contact form or any external service, with the contact details and search preferences you provide. This is the recommended way to send leads to Vestta. ## Lead type `type` accepts Vestta's lead types and a few English and Spanish aliases: | You send | Stored as | | --- | --- | | `buyer`, `tenant`, `comprador`, `inquilino`, `demandante` | `demandante` — looking to buy or rent | | `owner`, `propietario` | `propietario` — owns a property | | `agencia-inmobiliaria`, `entidad-bancaria`, `proveedor-servicios` | Unchanged | Matching is case-insensitive. Any other value fails. ## Search preferences `search_preferences` is a list of searches. Each entry has the operations and property types the lead wants, optional criteria per property type, and locations: ```json { "operations": ["alquiler"], "property_types": ["apartamento", "casa"], "apartamento": { "bedrooms_min": 2, "price_rent_max": 1200 }, "casa": { "bedrooms_min": 3, "price_rent_max": 1500 }, "locations": [{ "name": "Madrid" }] } ``` - `operations`: `venta`, `alquiler` and/or `traspaso`. - `property_types`: `apartamento`, `casa`, `local`, `nave`, `almacenaje`, `oficina`, `terreno`, `aparcamiento`, `edificio`. Criteria for each type go in the object of the same name, such as `apartamento.price_rent_max` or `casa.price_max`. - `locations`: places by `name`, or map areas in the same shapes as the [`locations` filter](/properties/list#map-areas). When at least one search has content, the lead is created with status `searching_property`; otherwise with status `new`. Partial search requests are accepted: no minimum set of criteria is required. If the form only collects contact details, omit `search_preferences` or send `[]`. Empty entries are discarded, and Vestta does not invent criteria or run matching for a contact without a search request. ## Notes Vestta writes a summary of the inquiry into the lead notes — operations, property types, locations, origin page and your message — so agents can read it at a glance. Your message is taken from `search_preferences[0].internal_notes` if set, otherwise from `notes`. ## Defaults set by Vestta Inquiries are always stored as **active**, with **rating 3** and captured by `Web`. `profile_category` defaults to `potencial`, `urgency_profile` to `poca-urgencia` and `source` to `manual` — send `"source": "web"` or your site's name so agents know where the lead came from. ## Duplicates The primary phone is unique within a workspace: - If a lead with the same phone exists **without a name** (for example, someone who first wrote on WhatsApp), it is **completed** with this inquiry and its `lead_id` is returned. - If a lead with the same primary phone exists **with a name**, the request fails with `409`. Treat it as "already in Vestta": do not retry. ### POST /v1/leads/inquiries Accepts structured contact-form inquiries and retains configured outreach. Requires the `leads:ingest` scope. Required scope: `leads:ingest` Request body (LeadInquiryRequest, required, application/json): - `name` (string, required): Contact's full name. - `dni` (string, optional, nullable): National ID document number. - `type` (string, required): Lead type. `buyer`, `comprador`, `demandante`, `tenant` and `inquilino` are stored as `demandante`; `owner` and `propietario` as `propietario`. Other values must be a Vestta lead type (`agencia-inmobiliaria`, `entidad-bancaria`, `proveedor-servicios`). - `profile_category` (string, optional, nullable): `standard` or `potencial`. Defaults to `potencial`. - `urgency_profile` (string, optional, nullable): `alta-urgencia` or `poca-urgencia`. Defaults to `poca-urgencia`. - `preferred_language` (string, optional, nullable): `es`, `gb`, `fr`, `ge` or `it`. - `phone_number_1` (string, required): Primary phone. Normalised to E.164: include the international prefix (`+34600111222`); numbers without one are read as Spanish. - `phone_number_2` (string, optional, nullable): Secondary phone, normalised to E.164. - `landline_phone` (string, optional, nullable): Landline, normalised to E.164. - `personal_email` (string, optional, nullable): Personal email address. - `professional_email` (string, optional, nullable): Work email address. - `source` (string, optional, nullable, default manual): Where the inquiry comes from, e.g. `web` or your site's name. Stored as the lead source; defaults to `manual`. - `sourcePage` (string, optional, nullable): URL of the page where the inquiry was submitted. Added to the lead notes. - `notes` (string, optional, nullable): Free-text message. Vestta stores a generated summary of the inquiry as the lead notes and includes this text in it, unless `search_preferences[0].internal_notes` is set. - `search_preferences` (array of objects, optional): What the contact is looking for. All entries are stored and used for property matching; the first one is summarised in the notes. - `request_id` (string, optional, nullable) - `operations` (array of strings, optional) - `property_types` (array of strings, optional) - `apartamento` (ApartmentPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `casa` (HousePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `bedrooms_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `doble_bedrooms_min` (integer, optional, nullable) - `suite_bathrooms_min` (integer, optional, nullable) - `plot_size_min` (integer, optional, nullable) - `porch_size_min` (integer, optional, nullable) - `local` (LocalPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `nave` (NavePreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `height_min` (integer, optional, nullable) - `facade_meters_min` (integer, optional, nullable) - `showcase_meters_min` (integer, optional, nullable) - `almacenaje` (StoragePreferences, optional): Preferencias para almacenes y trasteros independientes. - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `oficina` (OficinaPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `offices_min` (integer, optional, nullable) - `bathrooms_min` (integer, optional, nullable) - `meeting_rooms_min` (integer, optional, nullable) - `num_terraces_min` (integer, optional, nullable) - `size_terraces_min` (integer, optional, nullable) - `terreno` (TerrenoPreferences, optional) - `requireds` (array of strings, optional) - `views` (array of strings, optional, nullable) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `topography` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `size_built_min` (integer, optional, nullable) - `aparcamiento` (AparcamientoPreferences, optional) - `requireds` (array of strings, optional) - `features` (array of strings, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `min_seats` (integer, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `edificio` (BuildingPreferences, optional) - `requireds` (array of strings, optional) - `specs` (object, optional, nullable) - `features` (array of strings, optional, nullable) - `size_max` (integer, optional, nullable) - `size_min` (integer, optional, nullable) - `subtypes` (array of strings, optional, nullable) - `price_max` (integer, optional, nullable) - `price_min` (integer, optional, nullable) - `price_rent_max` (integer, optional, nullable) - `price_rent_min` (integer, optional, nullable) - `num_floors_min` (integer, optional, nullable) - `num_locales_min` (integer, optional, nullable) - `usable_area_min` (integer, optional, nullable) - `num_parkings_min` (integer, optional, nullable) - `num_viviendas_min` (integer, optional, nullable) - `locations` (array of objects, optional) - `internal_notes` (string, optional, nullable) - `title` (string, optional, nullable) - `color` (string, optional, nullable) - `urgency` (string, optional, nullable) - `status` (string, optional, nullable) - `agency_property_ids` (array of integers, optional): Property IDs linked to the contact. Stored only when `type` is `agencia-inmobiliaria`. - `services` (array of objects, optional): Services offered by the contact. Stored only when `type` is `entidad-bancaria` or `proveedor-servicios`. - `name` (string, required, 1–255 chars) - `category` (string, optional, nullable, ≤ 80 chars) - `approximate_cost` (number, optional, nullable, ≥ 0) - `notes` (string, optional, nullable, ≤ 2000 chars) Accepted but ignored — leave these fields out: - `rating` (integer, optional, nullable, default 0) — ignored: Ignored: inquiries are stored with rating 3. - `active` (boolean, optional, nullable) — ignored: Ignored: inquiries are always stored as active. - `captured_by` (string, optional, nullable) — ignored: Ignored: inquiries are stored as captured by `Web`. - `agency_id` (integer, optional, nullable, ≥ 1) — ignored: Ignored by this endpoint. - `agency_client_ids` (array of integers, optional) — ignored: Ignored by this endpoint. - `time_to_create` (integer, optional, nullable, default 0) — ignored: Ignored by this endpoint. Response 200: Successful response. - `status` (string, required, values: `ok`) - `authenticated_as` (string, optional, nullable): Name of the business that owns the API key. - `lead_id` (integer, optional, nullable): ID of the created lead, or of the existing unnamed lead that was completed. ```json { "status": "ok", "authenticated_as": "Inmobiliaria Ejemplo", "lead_id": 228 } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl -X POST "https://api.vestta.io/v1/leads/inquiries" \ -H "X-Api-Key: $VESTTA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Ana García", "type": "demandante", "preferred_language": "es", "phone_number_1": "+34600111222", "personal_email": "ana@example.com", "source": "web", "sourcePage": "https://example.com/contacto", "notes": "Busco piso de dos habitaciones cerca del centro.", "search_preferences": [ { "operations": [ "alquiler" ], "property_types": [ "apartamento" ], "apartamento": { "price_rent_max": 1200, "bedrooms_min": 2 }, "locations": [ { "name": "Madrid" } ] } ] }' ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/leads/inquiries', { method: 'POST', headers: { 'X-Api-Key': process.env.VESTTA_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ "name": "Ana García", "type": "demandante", "preferred_language": "es", "phone_number_1": "+34600111222", "personal_email": "ana@example.com", "source": "web", "sourcePage": "https://example.com/contacto", "notes": "Busco piso de dos habitaciones cerca del centro.", "search_preferences": [ { "operations": [ "alquiler" ], "property_types": [ "apartamento" ], "apartamento": { "price_rent_max": 1200, "bedrooms_min": 2 }, "locations": [ { "name": "Madrid" } ] } ] }), }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.post( "https://api.vestta.io/v1/leads/inquiries", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, json={ "name": "Ana García", "type": "demandante", "preferred_language": "es", "phone_number_1": "+34600111222", "personal_email": "ana@example.com", "source": "web", "sourcePage": "https://example.com/contacto", "notes": "Busco piso de dos habitaciones cerca del centro.", "search_preferences": [ { "operations": [ "alquiler", ], "property_types": [ "apartamento", ], "apartamento": { "price_rent_max": 1200, "bedrooms_min": 2, }, "locations": [ { "name": "Madrid", }, ], }, ], }, ) response.raise_for_status() data = response.json() ``` --- # Retrieve key context URL: https://api-docs.vestta.io/me Return the workspace and scopes of the API key used for the request. Use this endpoint to check a key: at deploy time, in a health check, or when a user pastes a key into your product. It works with any active key, needs no scope and does not read or change workspace data. Compare `user.scopes` with the scopes your integration needs, and fail early with a clear message if one is missing — instead of waiting for the first `401 Lack of permissions`. ### GET /v1/me Returns the authenticated business and granted scopes. Any active key can call this operation. Required scope: none (any active key) Response 200: Successful response. - `status` (string, required, values: `ok`) - `user` (ApiKeyContext, required) - `company_name` (string, optional, nullable): Name of the business that owns the API key. - `scopes` (array of strings, required): Granted scopes: properties:read, properties:write, properties:publish, leads:read, leads:write, leads:ingest. - `auth_method` (string, required, values: `api_key`) ```json { "status": "ok", "user": { "company_name": "Inmobiliaria Ejemplo", "scopes": [ "properties:read", "leads:read" ], "auth_method": "api_key" } } ``` Response 401: The API key is missing, malformed, unknown, revoked or expired. Response 403: The API key lacks the required scope, or the business plan does not include API access. Response 404: The resource does not exist in this business. Response 409: Duplicate contact or idempotency key reused with a different payload. Response 422: A path parameter, query parameter or body field is invalid. Response 500: Unexpected server error while processing the request. ### Example requests #### cURL ```bash curl "https://api.vestta.io/v1/me" \ -H "X-Api-Key: $VESTTA_API_KEY" ``` #### JavaScript ```javascript const response = await fetch('https://api.vestta.io/v1/me', { headers: { 'X-Api-Key': process.env.VESTTA_API_KEY }, }) const data = await response.json() ``` #### Python ```python import os import requests response = requests.get( "https://api.vestta.io/v1/me", headers={"X-Api-Key": os.environ["VESTTA_API_KEY"]}, ) response.raise_for_status() data = response.json() ``` --- # Errors URL: https://api-docs.vestta.io/errors Standard problem responses, request IDs and safe retry rules. Errors use HTTP status codes and `application/problem+json` (RFC 9457): ```json { "type": "about:blank", "title": "Forbidden", "status": 403, "detail": "Insufficient scope", "instance": "/v1/properties", "request_id": "0123456789abcdef0123456789abcdef" } ``` The same correlation ID appears in `X-Request-Id`. Keep it when contacting support. Errors never echo API keys, request bodies, SQL text or storage credentials. Branch on HTTP status rather than matching the message. ## Status codes | Status | Meaning | Action | | --- | --- | --- | | `400` | An upload or existing form request cannot be processed. | Correct the request. | | `401` | Missing, malformed, unknown, expired or revoked key. | Correct or rotate the key. | | `403` | Valid key without the required scope. | Create a key with the needed permission. | | `404` | Resource does not exist in the workspace, or listing is not public. | Do not infer whether another workspace owns it. | | `409` | Duplicate contact or an idempotency/session key used with a different request. | Reconcile the existing resource or use a new key for a new request. | | `422` | Invalid fields, incompatible pricing or incomplete publication data. | Correct all reported fields. | | `500` | Unexpected server error. | Retry safely with backoff; keep the request ID. | ## Validation errors A `422` can include `errors`, each containing `type`, `loc` and `msg`. For example, `loc: ["body", "pricing", "sale"]` identifies the invalid field. Input values are deliberately omitted. ## Retry rules GET requests are safe to retry. Property and contact creation support [idempotency keys](/publishing): reuse the same key and body after a lost response. Without a key, check whether creation succeeded before retrying. Repeating the same publication request is safe. Do not poll failed jobs indefinitely; correct the cause first. Existing rental ingestion ignores known phone numbers; inquiry creation can return a conflict when a previous attempt was stored. Server-side outreach errors do not expose internals. --- # Troubleshooting URL: https://api-docs.vestta.io/troubleshooting Fixes for the problems integrations with the Vestta API run into most often. ## Every request returns 401 Read the `detail` of the response — it names the cause. The most common ones: - **`API key required`** — the header did not reach the API. Check its name (`X-Api-Key`), and that no proxy, gateway or HTTP library drops custom headers. `Authorization: Bearer` is not accepted. - **`Invalid API key format`** — the value was cut, or includes quotes or whitespace. Environment files often add quotes; print the length of the value you send. - **`API key expired`** or **`API key is revoked`** — create a new key or reactivate it in **Settings → API**. ## A working key gets 403 "Insufficient scope" The key is valid but lacks the endpoint's scope. Call [Retrieve key context](/me) to see the scopes it has. Scopes are fixed at creation, so create a new key with the right ones — see [scopes](/authentication#scopes). ## A property is in Vestta but not in the API The API only returns the **public catalogue**. Check in Vestta that the property: - is marked as public; - is not sold, rented or withdrawn; - belongs to the workspace of the key you are using. The same rules make [Retrieve a property](/properties/retrieve) return `404`. ## A property has no address `address`, `postal_code` and the coordinates follow the property's address privacy setting: with a hidden location only `city`, `province` and `country` are returned, and with an approximate location the coordinates are rounded to about 1 km. See [Address privacy](/properties#address-privacy). ## Rent prices are missing or `price` is 0 `price` is the **sale** price. Monthly rent and transfer prices live in `specs.price_calc.price_alq` and `specs.price_calc.price_trasp`. Filter with `operation=alquiler` to make `min_price`, `max_price` and `sort` use the rent. See [Operations and prices](/properties#operations-and-prices). ## A map filter returns nothing, or everything - If `locations` is not valid JSON, it is ignored and you get every property. Check `filters.locations` in the response: it lists the areas that were applied. - Areas need a `geometry` (or `"type": "point"`): `{ "name": "Madrid" }` is ignored. Use the `city` filter for names. - Properties with a hidden location never match an area, and approximate ones are matched by their rounded coordinates. - Coordinates are `lat`/`lng` in degrees; swapping them puts the area in another part of the world. ## A rental lead returns 200 but does not appear [Ingest a rental lead](/leads/ingest) does not create a lead when the workspace already has one with the same phone, and still returns `200`. Search for the phone in Vestta: the existing lead is the one the agency will work with. ## Create an inquiry returns 409 A lead with the same primary phone already exists in the workspace. The contact is already in Vestta; do not retry. ## A lead request fails with 422 for the phone Send numbers in international format, such as `+34600111222`. Numbers without a prefix are read as Spanish, so foreign numbers need their prefix. ## A rental lead has an invalid budget Check `search.budget`: it must be a whole number (`1200`) or a range of whole numbers (`900-1200`). Unsupported budget formats are rejected; send a numeric amount or supported range. ## The lead did not get a WhatsApp message The automatic first message is only sent when the workspace has WhatsApp connected in Vestta, and only once per lead. Lead creation does not depend on it. ## Requests from the browser The API answers cross-origin requests, but calling it from front-end code exposes your key to every visitor. Send requests from your server. For public forms, post to your backend and call [Create an inquiry](/leads/inquiries) from there. --- # Publishing properties URL: https://api-docs.vestta.io/publishing Create a listing, upload original photos and publish marked images safely. Publishing is a backend operation. The CRM keeps original images; websites, the external catalogue, the public portal and PDF exports use separate watermarked copies. Existing photos grandfathered during migration retain unmarked copies with independent public URLs. New uploads still receive watermarks, including new photos added to an existing property. This exception cannot be requested through the API. ## Integration flow 1. [Create a contact](/leads/create) if the property needs a holder. Contacts are private CRM records, not public listings. 2. [Create a property](/properties/create) with its operation, price, location privacy, area and characteristics. Save the returned ID. 3. [Prepare uploads](/properties/uploads), PUT each accepted photo to its temporary upload URL, and [complete the session](/properties/complete-uploads). 4. [Request publication](/properties/publication) with `published: true`. 5. [Poll status](/properties/publication-status) until `published: true`, or handle a failed job. Then [retrieve the listing](/properties/retrieve). Give an importer `properties:write`, `properties:publish` and optionally `leads:write`. A public website needs only `properties:read` and, for contact forms, `leads:ingest`. ## Photo protection The workspace's logo is centered and translucent. If no customer logo exists, a small Vestta SVG mark appears at the bottom right. URLs and image IDs are random and independent from the original. Public responses contain neither private paths nor original filenames. If processing fails, no original photo is substituted. Downloads from the authenticated CRM remain unmarked. Preparing a PDF's marked photos does not publish the property. ## Migration from the old API The only API base is now `https://api.vestta.io/v1`; the former mount has been removed. Update your integration's base URL before switching traffic. Existing API keys keep their scopes: write and publish permissions must be explicitly granted on a new key. Errors now use `application/problem+json`, valid keys without permission receive `403`, and `count` is the total on both list resources. Response envelopes stay `status` plus `data` for reads; creates and updates return `status` plus `id`. --- # Documentation for AI agents URL: https://api-docs.vestta.io/agents Read any documentation page as Markdown or plain text, or download the complete API reference. Every documentation page is available as HTML, Markdown and plain text. These are representations of the same public content: the endpoint descriptions, parameters, request bodies, responses and examples come from the same OpenAPI snapshot used by the website. ## Request a page as Markdown Send `Accept: text/markdown` to the normal documentation URL: ```bash curl -H 'Accept: text/markdown' \ 'https://api-docs.vestta.io/properties/list' ``` The response uses `Content-Type: text/markdown; charset=utf-8`. The URL stays the same. HTML remains the default for browsers and clients that do not explicitly request Markdown or plain text. Quality weights in `Accept` are respected; `q=0` excludes a format. ## Direct Markdown and text URLs Append `.md` to a page path, or `.txt` for the same text with `Content-Type: text/plain`: ```text https://api-docs.vestta.io/index.md https://api-docs.vestta.io/authentication.md https://api-docs.vestta.io/properties/list.md https://api-docs.vestta.io/properties/list.txt ``` The homepage uses `index.md` or `index.txt`. Direct URLs also work for clients that cannot configure request headers. They link back to the canonical HTML page; the HTML pages remain the search-engine sitemap entries. ## Discover or download the documentation - [llms.txt](/llms.txt): the documentation index and links to individual Markdown pages. - [llms-full.txt](/llms-full.txt): the complete authored documentation with OpenAPI components expanded. - [openapi.json](/openapi.json): the machine-readable API contract. Start with the index and retrieve the pages needed for your task. Use the full file when your client has enough context for the entire reference. HTML pages advertise their alternatives using `link rel="alternate"`; HTTP responses include `Vary: Accept` and canonical links. ## Scope and authentication The documentation is public and needs no API key. Actual calls to `https://api.vestta.io/v1` still need the documented API key and scopes. Markdown access does not grant access to CRM accounts or private data, and does not execute the actions described in examples. The public marketing website offers the same reading formats; see [Vestta for AI agents](https://www.vestta.io/para-agentes). The CRM application is outside this feature. --- # Changelog URL: https://api-docs.vestta.io/changelog Changes to the Vestta API and its documentation. Changes that affect integrations are listed here, newest first. This overhaul includes an explicit migration of the old mount and error/pagination contracts. ## November 2026 ### Unmarked photo copies withdrawn — November 17 The `watermark` query parameter on [List properties](/properties/list) and [Retrieve a property](/properties/retrieve) has been removed. Requests that still send `watermark=false` are not rejected: the parameter is ignored and photos keep the agency watermark. These endpoints no longer return `503` for photo preparation. ### Markdown and plain-text documentation — November 17 Every documentation page supports `Accept: text/markdown` and `Accept: text/plain`, plus direct `.md` and `.txt` URLs. The homepage uses `/index.md` and `/index.txt`. HTML remains the default, and format preferences respect quality weights. The [AI agents guide](/agents), `llms.txt`, `llms-full.txt` and OpenAPI provide discovery and the complete reference. API authentication and resource contracts are unchanged. ## October 2026 ### Form submissions and search requests — October 29 [Rental lead ingestion](/leads/ingest) with `propertyId` now saves the contact, tenant profile and rental candidacy without creating a general search request. General rental searches accept partial criteria: unknown budget and bedroom fields can be empty, and an unknown location can be `{}`. A tenant profile alone does not create a search request. Contact forms and [inquiries](/leads/inquiries) without search criteria store an empty request list and do not start matching. Explicit partial search requests remain supported. Existing contacts retain their saved search requests when applying to a rental. ### Property subtypes and contact notes — October 15 Property creation now requires `subtype`, using one of the canonical keys for the selected property type. Integrations that omitted it must add it to their creation payloads; see [the subtype table](/properties/create). The schema lists the selectable keys. Property updates check supplied type/subtype changes against the saved property. Contact creation and updates now accept private `notes` and `rating` (an integer from `0` to `5`, default `0` on creation). Read responses continue to omit these fields and request-specific `internal_notes`. ### Professional integration and publication API — AN0-455 / AN0-22 The API is mounted directly at `/v1`. Property and private contact creation and updates, private image upload sessions, and asynchronous publication are now documented. Creation supports durable 24-hour idempotency keys. Reads return opaque public copies with random independent IDs: new photos are watermarked, while migration-grandfathered photos may remain unmarked. The CRM retains originals. Missing scope now returns `403`, errors use RFC 9457 problem details, and both list counts report totals. Read the [migration and publication guide](/publishing) before switching an integration. ### Public API documentation The Vestta API now has its own documentation site, with guides, an endpoint reference generated from the [OpenAPI schema](/openapi.json), and [Swagger UI](/swagger). ### Property responses only contain public data [List properties](/properties/list) and [Retrieve a property](/properties/retrieve) now return the same set of fields, all of them documented in [the property object](/properties#the-property-object). - Internal fields are no longer returned: internal notes, owner and agency links, capture details and `source`; in `specs`, the commission, captation and VAT figures, price history, portal settings and internal flags. - `specs` only contains documented listing characteristics; images and videos only their public playback fields, and only processed videos. - Location follows the property's [address privacy](/properties#address-privacy): exact for public addresses, rounded to about 1 km for approximate ones, and only the municipality for hidden ones. Map-area filters use the same published coordinates. - Both endpoints now return `title`, `country`, `created_at` and `updated_at`. ### Lead responses only contain contact and search data [List leads](/leads/list) returns the lead's identity, contact details, status and search preferences. Internal notes, ID documents, rating and scoring, the assigned agent, capture details, follow-up dates and internal IDs are no longer returned, and internal notes are removed from `search_preferences`. ### Error messages no longer include internal details [Create an inquiry](/leads/inquiries) answers `409 Lead already exists`, `400 Lead could not be created` and `500 Error creating lead inquiry` instead of database or exception text. ### Schema published only on this site The API no longer serves its own reference pages or `openapi.json`. The schema is published at [`/openapi.json`](/openapi.json) on this site. --- # API reference URL: https://api-docs.vestta.io/reference Every endpoint of the Vestta API, generated from its OpenAPI schema. Base URL: `https://api.vestta.io/v1`. Every request needs an [API key](/authentication) in the `X-Api-Key` header. ## Properties - `GET /v1/properties` — List published properties (https://api-docs.vestta.io/properties/list) - `POST /v1/properties` — Create a property (https://api-docs.vestta.io/properties/create) - `GET /v1/properties/{property_id}` — Retrieve a published property (https://api-docs.vestta.io/properties/retrieve) - `PATCH /v1/properties/{property_id}` — Update a property (https://api-docs.vestta.io/properties/update) ## Leads - `GET /v1/leads` — List contacts (https://api-docs.vestta.io/leads/list) - `POST /v1/leads` — Create a contact (https://api-docs.vestta.io/leads/create) - `GET /v1/leads/{lead_id}` — Retrieve a contact (https://api-docs.vestta.io/leads/retrieve) - `PATCH /v1/leads/{lead_id}` — Update a contact (https://api-docs.vestta.io/leads/update) - `POST /v1/leads/ingest` — Ingest a rental lead (https://api-docs.vestta.io/leads/ingest) - `POST /v1/leads/inquiries` — Create an inquiry (https://api-docs.vestta.io/leads/inquiries) ## Authentication - `GET /v1/me` — Retrieve key context (https://api-docs.vestta.io/me) ## Machine-readable schema The reference pages are generated from the same OpenAPI 3.1 document you can download: - [`/openapi.json`](/openapi.json) — import it into Postman or Insomnia, or use it with an OpenAPI client generator. - [Swagger UI](/swagger) — the raw schema rendered as an interactive explorer.