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

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

UUID de la etapa del funnel

string | string[]

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

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

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

Funnels

Templates

Agente IA

Equipo

Webhooks

Body Parameters

Filtros Disponibles

Teléfono

Nombre

Email

Tags

Funnel y Origen

Fechas

Otros

Ordenamiento

Ejemplos

Clientes Premium sin Contacto Reciente

Contactos por Dominio de Email

Leads Nuevos sin Tags

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

​Fechas

​Otros

​Ordenamiento

​Ejemplos

​Clientes Premium sin Contacto Reciente

​Contactos por Dominio de Email

​Leads Nuevos sin Tags

​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

Fechas

Otros

Ordenamiento

Ejemplos

Clientes Premium sin Contacto Reciente

Contactos por Dominio de Email

Leads Nuevos sin Tags

Contactos de Múltiples Orígenes

Respuesta

Casos de Uso

Próximos Pasos