Skip to main content
GET
Listar contactos
Returns a paginated list of contacts — the people on the other side of your channels. This is how you find the _id you need to open a CRM ticket or attach a note. Results cover the whole company, not just the project your token belongs to. Merged contacts and the internal playground channel are never returned.

Endpoint

Required scope

contacts:read

Headers

Query parameters

Example request

Response

200 OK

400 Bad Request

limit above 200, negative offset, a channel_type outside the allowed set, a malformed date, or an unknown query parameter.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the contacts:read scope.

502 Bad Gateway

The messaging service could not answer.

Operational notes

  • Results are sorted by last activity, most recent first. There is no way to change the sort order.
  • Merged contacts are hidden. When two contacts are merged in the portal, the absorbed one stops appearing here. If you cached its _id, that id will 404 on GET /v1/contacts/:id.
  • search uses a full-text index, so it matches whole words rather than partial strings. perez matches Pérez; pere does not.
  • phone is exact, including the + and country code — unlike user_id, which on WhatsApp is the same number without the +.
  • To page through the full set, increment offset by limit until offset >= total.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Query Parameters

Búsqueda full-text sobre nombre, apellido, usuario, teléfono y email.

phone
string

Filtrar por teléfono exacto

channel_id
string

ObjectId del canal

channel_type
enum<string>
Available options:
web,
whatsapp,
whatsapp_qr,
facebook,
messenger,
instagram,
tiktok,
telegram,
email,
phone
date_from
string

Fecha ISO 8601. Filtra por última actividad del contacto.

date_to
string

Fecha ISO 8601

limit
number
default:50
Required range: 1 <= x <= 200
offset
number
default:0
Required range: x >= 0

Response

200 - application/json
data
object[]
required
total
number
required
limit
number
required
offset
number
required