Ingest a rental lead

Create a rental-seeking lead from the compact payload used by rental landing forms.

POST/v1/ext/leads/ingest

Requires the leads:ingest scope

On this page

How the payload is used
Duplicates
Example request
Authorization
Request body
Response
Errors

Creates a lead looking to rent from a short form submission. Vestta turns the payload into a lead of type demandante with search preferences, and a readable summary of the form in its notes. For full control over the lead, use Create an inquiry 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`	The upper bound becomes the maximum monthly rent. `1200` and `900-1200` both mean 1,200 €.
`search.habs`	Minimum bedrooms, for apartments and houses.
`search.location`	The search location used for matching.
`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.
`id`, `createdAt`	Required, but not stored. Use them for your own tracing.

The lead is created with operation alquiler and property types apartamento and casa, rating 3, and high urgency (alta-urgencia).

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. This makes retries safe, but it also means a returning visitor's new form is not recorded.

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.

Example request

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

Authorization

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

Request body

application/json · required

idstringrequired
Your identifier for the submission. Required, but not stored by Vestta.
createdAtstringrequired
When the form was submitted, ISO 8601. Required, but not stored by Vestta.
sourcestringrequired
Where the lead comes from, e.g. web. Stored as the lead source.
sourcePagestringrequired
URL of the page with the form. Added to the lead notes.
contactRentingLeadContactrequired
- namestringrequired
  Contact's full name. Stored as the lead name.
- phonestringrequired
  Phone number. Include the international prefix (+34600111222); numbers without one are read as Spanish.
- phoneRawstring
  Phone exactly as typed. Used only when no other phone field can be normalised.
- areaCodestring
  International prefix, e.g. +34. Combined with phoneNumber and tried first.
- phoneNumberstring
  National number without prefix. Combined with areaCode.
- phoneE164string
  Phone already in E.164 format. Tried after areaCode + phoneNumber.
searchRentingLeadSearchrequired
- budgetstringrequired
  Monthly budget in euros: a whole number (1200) or a range (900-1200). The upper bound is stored as the maximum rent.
- entryDatestringrequired
  Desired move-in date. Free text, added to the lead notes; YYYY-MM-DD recommended.
- exitDatestringrequired
  Desired move-out date. Free text, added to the lead notes.
- peoplestringrequired
  Number of occupants. Added to the lead notes.
- areastringrequired
  Preferred area, as free text. Added to the lead notes.
- habsstringrequired
  Minimum bedrooms. Stored as the minimum bedrooms for apartments and houses.
- petsstringrequired
  Whether the occupants have pets. Added to the lead notes.
- workSituationstringrequired
  Employment situation. Added to the lead notes.
- locationobjectrequired
  Location used for property matching, e.g. {"name": "Madrid"}, or a map area with geometry.
- freeTextstringrequired
  Free-text message from the contact. Added to the lead notes.

Response

200 Successful response.

Example response

{
  "status": "ok",
  "authenticated_as": "Inmobiliaria Ejemplo"
}

Response fields

statusstringrequired always ok
authenticated_asstring
Name of the business that owns the API key.

Errors

Status	When
401 Unauthorized	The API key is missing, malformed, unknown, revoked or expired, or lacks the required scope.
422 Unprocessable Content	A path parameter, query parameter or body field is invalid.
500 Internal Server Error	Unexpected server error while processing the request.

Error bodies and how to handle each case: Errors.