---
title: "Buscar contactos"
method: GET
path: "/v1/contacts"
tags: ["Contacts"]
---

# Buscar contactos

`GET /v1/contacts`

Búsqueda de contactos con filtros avanzados.

## Query parameters

- `search` string
- `email` string
- `name` string
- `phone` string
- `status` 'new' | 'active' | 'client' | 'long_term'
- `subStatus` string
- `websiteId` string
- `assignedTo` string
- `entryMethod` string
- `conversationTags` string
- `rating` string
- `dateFrom` string, date-time
- `dateTo` string, date-time
- `lastUpdateDateFrom` string, date-time
- `lastUpdateDateTo` string, date-time
- `orderBy` string
- `order` 'asc' | 'desc'
- `page` integer
- `limit` integer

## Response `200`

Resultados de la búsqueda

- ContactSearchResponse — Respuesta del listado de contactos. `data` es un **arreglo** de contactos (a diferencia del listado de conversaciones, donde `data` es un objeto indexado por id).
  - `pagination` Pagination — Metadatos de paginación que acompañan a las respuestas de listado. Usá `page`/`limit` o `offset`/`limit` para recorrer todas las páginas mientras `hasNext` sea `true`.
    - `page` integer — Número de página actual (1-based).
    - `limit` integer — Cantidad de resultados por página. Máximo: 100.
    - `total` integer — Total de resultados que matchean la consulta.
    - `totalPages` integer — Cantidad total de páginas.
    - `hasNext` boolean — Indica si hay una página siguiente.
    - `hasPrev` boolean — Indica si hay una página anterior.
  - `data` Contact[]
    - `id` string
    - `name` string
    - `email` string, email
    - `phone` string
    - `internationalPhoneNumber` string
    - `channelId` string — ID del canal donde se originó el contacto
    - `companyId` string — ID de la empresa dueña del contacto.
    - `conversationId` string — ID de la conversación que originó el contacto.
    - `status` 'new' | 'active' | 'client' | 'long_term' — Etapa del ciclo de vida comercial del contacto: `new` (recién creado), `active` (en gestión), `client` (convertido), `long_term` (seguimiento a largo plazo). **Casing:** el estado del contacto va en minúscula; no confundir con `Conversation.status`, que usa MAYÚSCULAS (`ACTIVE`, `CLOSED`, …). Son recursos y vocabularios distintos.
    - `subStatus` string — Sub-estado libre del contacto (configurable por la empresa).
    - `message` string — Último mensaje del contacto
    - `assignedTo` string, nullable — ID del agente asignado
    - `rating` integer — **Puntuación del lead** (estrellas), de 1 a 5; `0` significa sin puntuar. Vive en el contacto, no en la conversación: para puntuar una conversación traé su contacto por `contactId`.
    - `entryMethod` string — Método/canal por el que ingresó el contacto (ej. `WHATSAPP`, `WEB`, `FACEBOOK`). Es el dato base para distinguir el canal de adquisición. Filtrable con el parámetro `entryMethod` en la búsqueda de contactos.
    - `utmSource` string — Fuente de la campaña (UTM source). Ej. `google`, `facebook`, `instagram`.
    - `utmMedium` string — Medio de la campaña (UTM medium). Ej. `cpc`, `organic`, `social`.
    - `utmCampaign` string — Nombre de la campaña (UTM campaign).
    - `gclid` string — Google Click ID. Su presencia indica adquisición vía Google Ads (tráfico pago).
    - `conversionUrl` string — URL/página donde se generó el contacto.
    - `refererTracking` string — Referer completo de origen del tráfico.
    - `device` string — Dispositivo de origen del contacto.
    - `createdAt` string, date-time
    - `updatedAt` string, date-time

---

[API](https://skmtc.net/cliengo/apis/cliengo-public-api.md) · [All operations](https://skmtc.net/cliengo/apis/cliengo-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cliengo/cliengo-public-api/revisions/94c7ba7d6a11/schema)