Skip to content
VesttaDocs
VesttaDocs
API Reference Vestta

Loading…

Leads

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

On this page

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

Create a contact (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 and update for its subsequent lifecycle. Contacts remain private to the workspace.

The two form adapters below preserve their existing outreach behavior:

Ingest a rental leadCreate an inquiry
PayloadCompact rental-form formatFull lead: contact details and structured search preferences
Lead typeAlways demandanteFrom type (buyer, owner…)
Search preferencesDerived: rent an apartment or house, maximum rent from budget, minimum bedrooms, one locationExactly what you send in search_preferences
Urgencyalta-urgenciapoca-urgencia unless you send it
Phone already in the workspaceNothing is created; still returns 200Completes the existing lead if it has no name; otherwise 409
Returns the lead IDNoYes, lead_id
Follow-up schedulingNoYes
Scopeleads:ingestleads: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 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.

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

    Structured search requests 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.