Skip to main content
POST
/
contacts
/
v1
/
search
curl -X POST https://api.whaapy.com/contacts/v1/search \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "tags": { "all": ["cliente", "premium"] },
      "last_contact_at": { "before": "2026-01-01T00:00:00Z" }
    },
    "sort": { "field": "last_contact_at", "order": "asc" },
    "limit": 50
  }'

{
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5215512345678",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "tags": ["cliente", "premium"],
      "funnel_stage": { "id": "uuid", "name": "Qualified" },
      "source": "whaapy",
      "last_contact_at": "2025-12-15T10:00:00Z",
      "created_at": "2025-06-01T00:00:00Z",
      "updated_at": "2025-12-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "filters_applied": {
    "tags": { "all": ["cliente", "premium"] },
    "last_contact_at": { "before": "2026-01-01T00:00:00Z" }
  }
}
Realiza búsquedas avanzadas con múltiples filtros y operadores. Ideal para segmentación y análisis.
Usa este endpoint cuando necesites filtros más avanzados que los disponibles en GET /contacts/v1. Para búsquedas simples, usa el query param search en el listado.

​
Body Parameters

​
filters
object
required
Objeto con los filtros de búsqueda
​
sort
object
Configuración de ordenamiento
​
limit
number
default:"50"
Máximo 100 resultados por página
​
cursor
string
Cursor para paginación

​
Filtros Disponibles

​
Teléfono

​
filters.phone_number.eq
string
Coincidencia exacta
​
filters.phone_number.contains
string
Contiene substring

​
Nombre

​
filters.name.eq
string
Coincidencia exacta
​
filters.name.contains
string
Contiene substring (case-insensitive)
​
filters.name.starts_with
string
Empieza con

​
Email

​
filters.email.eq
string
Coincidencia exacta
​
filters.email.contains
string
Contiene substring
​
filters.email.domain
string
Filtrar por dominio (ej: gmail.com)

​
Tags

​
filters.tags.all
string[]
Tiene TODOS los tags especificados
​
filters.tags.any
string[]
Tiene AL MENOS UNO de los tags
​
filters.tags.none
string[]
NO tiene ninguno de los tags

​
Funnel y Origen

​
filters.funnel_stage_id
string
UUID de la etapa del funnel
​
filters.source
string | string[]
Origen(es) del contacto. Puede ser string o array.

​
Fechas

​
filters.created_at.after
string
Creados después de (ISO 8601)
​
filters.created_at.before
string
Creados antes de (ISO 8601)
​
filters.last_contact_at.after
string
Última interacción después de
​
filters.last_contact_at.before
string
Última interacción antes de

​
Otros

​
filters.has_conversation
boolean
true = tiene conversación, false = sin conversación
​
filters.custom_fields
object
Filtros en campos personalizados

​
Ordenamiento

​
sort.field
string
default:"created_at"
Campo: created_at, updated_at, name, last_contact_at, phone_number
​
sort.order
string
default:"desc"
Orden: asc o desc

​
Ejemplos

​
Clientes Premium sin Contacto Reciente

curl -X POST https://api.whaapy.com/contacts/v1/search \
  -H "Authorization: Bearer wha_TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "tags": { "all": ["cliente", "premium"] },
      "last_contact_at": { "before": "2026-01-01T00:00:00Z" }
    },
    "sort": { "field": "last_contact_at", "order": "asc" },
    "limit": 50
  }'

​
Contactos por Dominio de Email

{
  "filters": {
    "email": { "domain": "empresa.com" },
    "has_conversation": true
  }
}

​
Leads Nuevos sin Tags

{
  "filters": {
    "tags": { "none": ["cliente", "descartado"] },
    "created_at": { "after": "2026-01-01T00:00:00Z" }
  },
  "sort": { "field": "created_at", "order": "desc" }
}

​
Contactos de Múltiples Orígenes

{
  "filters": {
    "source": ["api", "webhook", "import"],
    "has_conversation": false
  }
}

​
Respuesta

{
  "contacts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+5215512345678",
      "name": "Juan Pérez",
      "email": "juan@email.com",
      "tags": ["cliente", "premium"],
      "funnel_stage": { "id": "uuid", "name": "Qualified" },
      "source": "whaapy",
      "last_contact_at": "2025-12-15T10:00:00Z",
      "created_at": "2025-06-01T00:00:00Z",
      "updated_at": "2025-12-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "has_more": false,
    "next_cursor": null
  },
  "filters_applied": {
    "tags": { "all": ["cliente", "premium"] },
    "last_contact_at": { "before": "2026-01-01T00:00:00Z" }
  }
}

​
Casos de Uso

Encuentra clientes que no han interactuado en los últimos 30 días:
{
  "filters": {
    "tags": { "any": ["cliente"] },
    "last_contact_at": { 
      "before": "2025-12-28T00:00:00Z" 
    }
  }
}
Encuentra todos los contactos de un dominio específico:
{
  "filters": {
    "email": { "domain": "acme.com" }
  }
}
Contactos nuevos sin conversación:
{
  "filters": {
    "created_at": { "after": "2026-01-01T00:00:00Z" },
    "has_conversation": false
  }
}

​
Próximos Pasos

Operaciones Masivas

Aplicar acciones a los resultados

Listar Tags

Ver tags disponibles para filtrar

Webhooks

Recibir notificaciones de cambios

Enviar Mensaje

Contactar a los resultados