Skip to content
VesttaDocs
VesttaDocs
API Reference Vestta

Loading…

Create an inquiry

Create a lead with contact details and structured search preferences, and get its ID back.

POST/v1/ext/leads/inquiries

Requires the leads:ingest scope

On this page

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 sendStored as
buyer, tenant, comprador, inquilino, demandantedemandante — looking to buy or rent
owner, propietariopropietario — owns a property
agencia-inmobiliaria, entidad-bancaria, proveedor-serviciosUnchanged

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.

When at least one search has content, the lead is created with status searching_property; otherwise with status new.

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.

Example request

curl -X POST "https://api.vestta.app/v1/ext/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"
        }
      ]
    }
  ]
}'

Authorization

  • X-Api-Keystringheaderrequired

    Your API key, AC_LIVE_<key_id>.<secret>. Authorization: ApiKey <key> is also accepted.

Request body

application/json · required

  • namestringrequired

    Contact's full name.

  • dnistring

    National ID document number.

  • typestringrequired

    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_categorystring

    standard or potencial. Defaults to potencial.

  • urgency_profilestring

    alta-urgencia or poca-urgencia. Defaults to poca-urgencia.

  • preferred_languagestring

    es, gb, fr, ge or it.

  • phone_number_1stringrequired

    Primary phone. Normalised to E.164: include the international prefix (+34600111222); numbers without one are read as Spanish.

  • phone_number_2string

    Secondary phone, normalised to E.164.

  • landline_phonestring

    Landline, normalised to E.164.

  • personal_emailstring

    Personal email address.

  • professional_emailstring

    Work email address.

  • sourcestring default: manual

    Where the inquiry comes from, e.g. web or your site's name. Stored as the lead source; defaults to manual.

  • sourcePagestring

    URL of the page where the inquiry was submitted. Added to the lead notes.

  • notesstring

    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_preferencesarray of objects

    What the contact is looking for. All entries are stored and used for property matching; the first one is summarised in the notes.

  • agency_property_idsarray of integers

    Property IDs linked to the contact. Stored only when type is agencia-inmobiliaria.

  • servicesarray of objects

    Services offered by the contact. Stored only when type is entidad-bancaria or proveedor-servicios.

Accepted but ignored (6)

These fields pass validation because the endpoint shares its model with the Vestta app, but this endpoint does not use them. Leave them out.

  • ratinginteger default: 0

    Ignored: inquiries are stored with rating 3.

  • activeboolean

    Ignored: inquiries are always stored as active.

  • captured_bystring

    Ignored: inquiries are stored as captured by Web.

  • agency_idinteger≥ 1

    Ignored by this endpoint.

  • agency_client_idsarray of integers

    Ignored by this endpoint.

  • time_to_createinteger default: 0

    Ignored by this endpoint.

Response

200 Successful response.

Example response
{
  "status": "ok",
  "authenticated_as": "Inmobiliaria Ejemplo",
  "lead_id": 228
}

Response fields

  • statusstringrequired always ok
  • authenticated_asstring

    Name of the business that owns the API key.

  • lead_idinteger

    ID of the created lead, or of the existing unnamed lead that was completed.

Errors

StatusWhen
400 Bad RequestThe lead could not be stored.
401 UnauthorizedThe API key is missing, malformed, unknown, revoked or expired, or lacks the required scope.
409 ConflictThe business already has a named lead with this primary phone.
422 Unprocessable ContentA path parameter, query parameter or body field is invalid.
500 Internal Server ErrorUnexpected server error while processing the request.

Error bodies and how to handle each case: Errors.