List leads

Return the leads of the workspace, newest first.

GET/v1/ext/leads

Requires the leads:read scope

On this page

Pagination
Example request
Authorization
Query parameters
Response
Errors

Returns every lead of the workspace — whatever its type or status, and however it was created — ordered by creation date, newest first.

Pagination

count is the number of leads in this page, not the total. Keep requesting pages while count equals limit. See Pagination.

The endpoint has no filters. To pick up new leads periodically, page from offset=0 and stop when you reach a created_at (or an id) you have already processed.

Example request

curl "https://api.vestta.app/v1/ext/leads?limit=20" \
  -H "X-Api-Key: $VESTTA_API_KEY"

Authorization

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

Query parameters

limitinteger≥ 1≤ 1000 default: 100
Maximum number of leads to return.
offsetinteger≥ 0 default: 0
Number of leads to skip, newest first.

Response

200 Successful response.

Example response

{
  "status": "ok",
  "data": [
    {
      "id": 227,
      "name": "Ana García",
      "type": "demandante",
      "status": "searching_property",
      "active": true,
      "source": "web",
      "phone_number_1": "+34600111222",
      "preferred_language": "es",
      "search_preferences": [
        {
          "locations": [
            {
              "name": "Madrid"
            }
          ],
          "operations": [
            "alquiler"
          ],
          "property_types": [
            "apartamento"
          ]
        }
      ],
      "created_at": "2026-09-29T18:24:55.569028+02:00",
      "updated_at": "2026-09-29T18:24:55.569028+02:00"
    }
  ],
  "count": 1,
  "limit": 20,
  "offset": 0,
  "authenticated_as": "Inmobiliaria Ejemplo"
}

Response fields

statusstringrequired always ok
dataarray of objectsrequired
- 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.
countintegerrequired
Number of leads in this page (not the total across pages).
limitintegerrequired
The limit that was applied.
offsetintegerrequired
The offset that was applied.
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.