Skip to main content
GET
/
contacts
/
v1
curl -X GET "https://api.whaapy.com/contacts/v1?limit=20&tags=cliente" \
  -H "Authorization: Bearer wha_TU_API_KEY"

{
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5215512345678",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "avatar_url": null,
      "tags": ["cliente", "premium"],
      "custom_fields": { "company": "Acme Inc" },
      "external_ids": {},
      "notes": null,
      "funnel_stage": { "id": "uuid", "name": "Qualified" },
      "source": "whaapy",
      "company": "Acme Inc",
      "address": null,
      "city": "CDMX",
      "state": null,
      "postal_code": null,
      "country": "MX",
      "last_contact_at": "2026-01-28T10:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-28T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6Inl5eSJ9"
  }
}
Obtén todos los contactos de tu negocio con soporte para búsqueda, filtros y paginación cursor-based.

​
Query Parameters

​
limit
number
default:"50"
Número de contactos por página (máximo 100)
​
cursor
string
Cursor para paginación. Usar next_cursor de la respuesta anterior.
​
search
string
Búsqueda por nombre, teléfono o email
​
tags
string
Filtrar por tags (separados por coma). Ej: cliente,premium
​
funnel_stage_id
string
Filtrar por etapa del funnel (UUID)
​
source
string
Filtrar por origen: whaapy, api, import, webhook, manual
​
sort_by
string
default:"created_at"
Campo para ordenar: created_at, updated_at, name, last_contact_at
​
sort_order
string
default:"desc"
Orden: asc o desc

​
Ejemplos

curl -X GET "https://api.whaapy.com/contacts/v1?limit=20&tags=cliente" \
  -H "Authorization: Bearer wha_TU_API_KEY"

​
Respuesta Exitosa

{
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5215512345678",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "avatar_url": null,
      "tags": ["cliente", "premium"],
      "custom_fields": { "company": "Acme Inc" },
      "external_ids": {},
      "notes": null,
      "funnel_stage": { "id": "uuid", "name": "Qualified" },
      "source": "whaapy",
      "company": "Acme Inc",
      "address": null,
      "city": "CDMX",
      "state": null,
      "postal_code": null,
      "country": "MX",
      "last_contact_at": "2026-01-28T10:00:00Z",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-28T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6Inl5eSJ9"
  }
}

​
Campos de Respuesta

CampoDescripción
contactsArray de objetos de contacto
pagination.totalTotal de contactos que coinciden con los filtros
pagination.limitLímite usado en la consulta
pagination.has_moreSi hay más resultados disponibles
pagination.next_cursorCursor para la siguiente página (null si no hay más)

​
Paginación

Whaapy usa paginación cursor-based para eficiencia con grandes volúmenes de datos.
1

Primera página

Haz una request sin cursor:
GET /contacts/v1?limit=50
2

Páginas siguientes

Usa el next_cursor de la respuesta anterior:
GET /contacts/v1?limit=50&cursor=eyJpZCI6Inl5eSJ9
3

Fin de resultados

Cuando has_more sea false y next_cursor sea null, no hay más resultados.

​
Próximos Pasos

Obtener Contacto

Detalles completos de un contacto

Búsqueda Avanzada

Filtros complejos y operadores

Crear Contacto

Agregar nuevos contactos

Listar Tags

Ver todos los tags disponibles