> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whaapy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Búsqueda Avanzada

> Busca contactos con filtros complejos

Realiza búsquedas avanzadas con múltiples filtros y operadores. Ideal para segmentación y análisis.

<Tip>
  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](/api-reference/contacts/list).
</Tip>

***

## Body Parameters

<ParamField body="filters" type="object" required>
  Objeto con los filtros de búsqueda
</ParamField>

<ParamField body="sort" type="object">
  Configuración de ordenamiento
</ParamField>

<ParamField body="limit" type="number" default="50">
  Máximo 100 resultados por página
</ParamField>

<ParamField body="cursor" type="string">
  Cursor para paginación
</ParamField>

***

## Filtros Disponibles

### Teléfono

<ParamField body="filters.phone_number.eq" type="string">
  Coincidencia exacta
</ParamField>

<ParamField body="filters.phone_number.contains" type="string">
  Contiene substring
</ParamField>

### Nombre

<ParamField body="filters.name.eq" type="string">
  Coincidencia exacta
</ParamField>

<ParamField body="filters.name.contains" type="string">
  Contiene substring (case-insensitive)
</ParamField>

<ParamField body="filters.name.starts_with" type="string">
  Empieza con
</ParamField>

### Email

<ParamField body="filters.email.eq" type="string">
  Coincidencia exacta
</ParamField>

<ParamField body="filters.email.contains" type="string">
  Contiene substring
</ParamField>

<ParamField body="filters.email.domain" type="string">
  Filtrar por dominio (ej: `gmail.com`)
</ParamField>

### Tags

<ParamField body="filters.tags.all" type="string[]">
  Tiene **TODOS** los tags especificados
</ParamField>

<ParamField body="filters.tags.any" type="string[]">
  Tiene **AL MENOS UNO** de los tags
</ParamField>

<ParamField body="filters.tags.none" type="string[]">
  **NO** tiene ninguno de los tags
</ParamField>

### Funnel y Origen

<ParamField body="filters.funnel_stage_id" type="string">
  UUID de la etapa del funnel
</ParamField>

<ParamField body="filters.source" type="string | string[]">
  Origen(es) del contacto. Puede ser string o array.
</ParamField>

### Fechas

<ParamField body="filters.created_at.after" type="string">
  Creados después de (ISO 8601)
</ParamField>

<ParamField body="filters.created_at.before" type="string">
  Creados antes de (ISO 8601)
</ParamField>

<ParamField body="filters.last_contact_at.after" type="string">
  Última interacción después de
</ParamField>

<ParamField body="filters.last_contact_at.before" type="string">
  Última interacción antes de
</ParamField>

### Otros

<ParamField body="filters.has_conversation" type="boolean">
  `true` = tiene conversación, `false` = sin conversación
</ParamField>

<ParamField body="filters.custom_fields" type="object">
  Filtros en campos personalizados
</ParamField>

***

## Ordenamiento

<ParamField body="sort.field" type="string" default="created_at">
  Campo: `created_at`, `updated_at`, `name`, `last_contact_at`, `phone_number`
</ParamField>

<ParamField body="sort.order" type="string" default="desc">
  Orden: `asc` o `desc`
</ParamField>

***

## Ejemplos

### Clientes Premium sin Contacto Reciente

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript Node.js theme={null}
  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
    })
  });
  ```

  ```python Python theme={null}
  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
      }
  )
  ```
</RequestExample>

### Contactos por Dominio de Email

<RequestExample>
  ```json Request theme={null}
  {
    "filters": {
      "email": { "domain": "empresa.com" },
      "has_conversation": true
    }
  }
  ```
</RequestExample>

### Leads Nuevos sin Tags

<RequestExample>
  ```json Request theme={null}
  {
    "filters": {
      "tags": { "none": ["cliente", "descartado"] },
      "created_at": { "after": "2026-01-01T00:00:00Z" }
    },
    "sort": { "field": "created_at", "order": "desc" }
  }
  ```
</RequestExample>

### Contactos de Múltiples Orígenes

<RequestExample>
  ```json Request theme={null}
  {
    "filters": {
      "source": ["api", "webhook", "import"],
      "has_conversation": false
    }
  }
  ```
</RequestExample>

***

## Respuesta

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "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" }
    }
  }
  ```
</ResponseExample>

***

## Casos de Uso

<AccordionGroup>
  <Accordion title="Reactivación de clientes">
    Encuentra clientes que no han interactuado en los últimos 30 días:

    ```json theme={null}
    {
      "filters": {
        "tags": { "any": ["cliente"] },
        "last_contact_at": { 
          "before": "2025-12-28T00:00:00Z" 
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Segmentación por empresa">
    Encuentra todos los contactos de un dominio específico:

    ```json theme={null}
    {
      "filters": {
        "email": { "domain": "acme.com" }
      }
    }
    ```
  </Accordion>

  <Accordion title="Leads sin atender">
    Contactos nuevos sin conversación:

    ```json theme={null}
    {
      "filters": {
        "created_at": { "after": "2026-01-01T00:00:00Z" },
        "has_conversation": false
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Próximos Pasos

<CardGroup cols={2}>
  <Card title="Operaciones Masivas" icon="layer-group" href="/api-reference/contacts/bulk">
    Aplicar acciones a los resultados
  </Card>

  <Card title="Listar Tags" icon="tags" href="/api-reference/contacts/tags">
    Ver tags disponibles para filtrar
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Recibir notificaciones de cambios
  </Card>

  <Card title="Enviar Mensaje" icon="paper-plane" href="/api-reference/messages/send">
    Contactar a los resultados
  </Card>
</CardGroup>