Leads

Read the leads of a Vestta workspace and send new leads from your forms and services.

On this page

Endpoints
Choosing an endpoint
What happens after a lead is created
Phone numbers
The lead object

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

Choosing an endpoint

The two POST endpoints both create a lead, from different payloads and with different rules. Reading the differences once saves surprises later:

	Ingest a rental lead	Create an inquiry
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 for new integrations: you control the lead type and preferences, you get the ID back, and duplicates are reported explicitly. Ingest a rental lead exists for rental landing pages that already send its compact format.

List leads is read-only and needs the separate leads:read scope.

What happens after a lead is created

Both POST endpoints respond as soon as the lead is stored. Then, in the background, Vestta:

Matches the lead against the property catalogue, using its search preferences.
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.
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.

idintegerrequired
Numeric lead ID.
namestring
typestring
demandante (looking for a property), propietario (owner), agencia-inmobiliaria, entidad-bancaria or proveedor-servicios.
statusstring
Pipeline status, e.g. new, searching_property, active_negotiation, closed or inactive.
activeboolean
sourcestring
Where the lead came from, e.g. web, manual, or the source sent on ingestion.
phone_number_1string
Primary phone in E.164 format.
phone_number_2string
landline_phonestring
personal_emailstring
professional_emailstring
preferred_languagestring
es, gb, fr, ge or it.
search_preferencesany
What the lead is looking for (same shape as search_preferences in Create an inquiry), without internal notes.
created_atstring
ISO 8601 timestamp with UTC offset. Leads are ordered by this field, newest first.
updated_atstring
ISO 8601 timestamp with UTC offset.