Búsqueda Avanzada

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
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      tags: { all: ['cliente', 'premium'] },
      last_contact_at: { before: '2026-01-01T00:00:00Z' }
    },
    sort: { field: 'last_contact_at', order: 'asc' },
    limit: 50
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/search',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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" }
  }
}

POST

contacts

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
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      tags: { all: ['cliente', 'premium'] },
      last_contact_at: { before: '2026-01-01T00:00:00Z' }
    },
    sort: { field: 'last_contact_at', order: 'asc' },
    limit: 50
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/search',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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

object

required

Objeto con los filtros de búsqueda

object

Configuración de ordenamiento

number

default:"50"

Máximo 100 resultados por página

string

Cursor para paginación

Filtros Disponibles

Teléfono

string

Coincidencia exacta

string

Contiene substring

string

Prefijo del número (ej: 52155 para números de CDMX). Se ignoran espacios, guiones, paréntesis, puntos y el + antes de comparar.

Nombre

string

Coincidencia exacta

string

Contiene substring (case-insensitive)

string

Empieza con

Email

string

Coincidencia exacta

string

Contiene substring

string

Filtrar por dominio (ej: gmail.com)

Funnel y Origen

string | string[] | null

Etapa del funnel. Acepta:

un UUID: contactos en esa etapa;
un arreglo de UUID (1 a 50): contactos en cualquiera de esas etapas;
null: contactos sin etapa.

string | string[]

Origen(es) del contacto. Puede ser string o array.

string | string[]

Origen distinto de estos valores. Los contactos sin origen no coinciden (igual que una comparación SQL <>).

Segmento

string

UUID de un segmento del negocio, estático o dinámico. Devuelve solo los contactos que pertenecen a él y se combina con el resto de filtros. Si el segmento no existe o no es de tu negocio responde 404; si sus reglas guardadas no son válidas, 400.

Fechas

string

Creados después de (ISO 8601)

string

Creados antes de (ISO 8601)

string

Última interacción después de

string

Última interacción antes de

Los filtros de fecha (created_at, updated_at y last_contact_at) también aceptan ventanas móviles relativas a “ahora”:

number

Dentro de los últimos N días (entero de 1 a 3650). Ej: { "within_days": 7 } = con actividad esta semana.

number

Hace más de N días (entero de 1 a 3650). Ej: { "older_than_days": 30 } = sin contacto en el último mes.

Los mismos campos within_days y older_than_days existen en created_at y updated_at. Como el cálculo es relativo a “ahora”, el resultado cambia con el tiempo sin que edites el filtro; por eso son ideales para segmentos dinámicos.

Otros

boolean

true = tiene conversación, false = sin conversación

object

Filtros en campos personalizados

Ordenamiento

string

default:"created_at"

Campo: created_at, updated_at, name, last_contact_at, phone_number

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
  }'

const response = await fetch('https://api.whaapy.com/contacts/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wha_TU_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filters: {
      tags: { all: ['cliente', 'premium'] },
      last_contact_at: { before: '2026-01-01T00:00:00Z' }
    },
    sort: { field: 'last_contact_at', order: 'asc' },
    limit: 50
  })
});

import requests

response = requests.post(
    'https://api.whaapy.com/contacts/v1/search',
    headers={
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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 un Prefijo, en Varias Etapas y sin Actividad Reciente

{
  "filters": {
    "phone_number": { "starts_with": "5255" },
    "funnel_stage_id": [
      "11111111-1111-4111-8111-111111111111",
      "22222222-2222-4222-8222-222222222222"
    ],
    "source_not": "import",
    "last_contact_at": { "older_than_days": 30 }
  }
}

Contactos sin Etapa del Funnel

{
  "filters": { "funnel_stage_id": null }
}

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

Reactivación de clientes

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" 
    }
  }
}

Segmentación por empresa

Encuentra todos los contactos de un dominio específico:

{
  "filters": {
    "email": { "domain": "acme.com" }
  }
}

Leads sin atender

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

General

Mensajes

Media

Conversaciones

Contactos

Segmentos

Funnels

Templates

Agente IA

Equipo

Webhooks

Body Parameters

Filtros Disponibles

Teléfono

Nombre

Email

Tags

Funnel y Origen

Segmento

Fechas

Otros

Ordenamiento

Ejemplos

Clientes Premium sin Contacto Reciente

Contactos por Dominio de Email

Leads Nuevos sin Tags

Contactos de un Prefijo, en Varias Etapas y sin Actividad Reciente

Contactos sin Etapa del Funnel

Contactos de Múltiples Orígenes

Respuesta

Casos de Uso

Próximos Pasos

Operaciones Masivas

Listar Tags

Webhooks

Enviar Mensaje

​Body Parameters

​Filtros Disponibles

​Teléfono

​Nombre

​Email

​Tags

​Funnel y Origen

​Segmento

​Fechas

​Otros

​Ordenamiento

​Ejemplos

​Clientes Premium sin Contacto Reciente

​Contactos por Dominio de Email

​Leads Nuevos sin Tags

​Contactos de un Prefijo, en Varias Etapas y sin Actividad Reciente

​Contactos sin Etapa del Funnel

​Contactos de Múltiples Orígenes

​Respuesta

​Casos de Uso

​Próximos Pasos

Operaciones Masivas

Listar Tags

Webhooks

Enviar Mensaje

Body Parameters

Filtros Disponibles

Teléfono

Nombre

Email

Tags

Funnel y Origen

Segmento

Fechas

Otros

Ordenamiento

Ejemplos

Clientes Premium sin Contacto Reciente

Contactos por Dominio de Email

Leads Nuevos sin Tags

Contactos de un Prefijo, en Varias Etapas y sin Actividad Reciente

Contactos sin Etapa del Funnel

Contactos de Múltiples Orígenes

Respuesta

Casos de Uso

Próximos Pasos