Skip to content
VesttaDocs
VesttaDocs
API Reference Vestta

Loading…

List leads

Return the leads of the workspace, newest first.

GET/v1/leads

Requires the leads:read scope

On this page

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/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
  • offsetinteger≥ 0 default: 0

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": [
        {
          "operations": [
            "alquiler"
          ],
          "property_types": [
            "apartamento"
          ],
          "locations": [
            {
              "name": "Madrid"
            }
          ]
        }
      ],
      "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
  • countintegerrequired

    Total contacts in the business, across all 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

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.