Skip to content
VesttaDocs
VesttaDocs
API Reference Vestta

Loading…

Create a contact

Create a private CRM contact without initiating outreach.

POST/v1/leads

Requires the leads:write scope

On this page

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.

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 for a form with configured follow-up.

The optional Idempotency-Key header has the same 24-hour replay and conflict rules as property creation.

Example request

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

Authorization

  • X-Api-Keystringheaderrequired

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

Request headers

  • idempotency-keystring1–200 chars

Request body

application/json · required

  • namestringrequired1–200 chars
  • typestringrequired

    One ofdemandantepropietarioagencia-inmobiliariaentidad-bancariaproveedor-servicios

  • phone_number_1stringrequired5–30 chars
  • phone_number_2string≤ 30 chars
  • landline_phonestring≤ 30 chars
  • personal_emailstring≤ 254 chars
  • professional_emailstring≤ 254 chars
  • preferred_languagestring default: es

    One ofesgbfrgeit

  • activeboolean default: true
  • sourcestring1–100 chars default: external_api
  • search_preferencesarray of objects

Response

201 Successful response.

Example response
{
  "status": "ok",
  "id": 1355
}

Response fields

  • statusstring default: ok always ok
  • idintegerrequired

Errors

StatusWhen
401 UnauthorizedThe API key is missing, malformed, unknown, revoked or expired.
403 ForbiddenThe API key lacks the required scope.
404 Not FoundThe resource does not exist in this business.
409 ConflictDuplicate contact or idempotency key reused with a different payload.
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.