Listar contactos
Contacts
GET /v1/contacts
List the messaging contacts of your company, with full-text search and channel filters.
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 thecontacts: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 onGET /v1/contacts/:id. searchuses a full-text index, so it matches whole words rather than partial strings.perezmatchesPérez;peredoes not.phoneis exact, including the+and country code — unlikeuser_id, which on WhatsApp is the same number without the+.- To page through the full set, increment
offsetbylimituntiloffset >= total.
Authorizations
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.
Filtrar por teléfono exacto
ObjectId del canal
Available options:
web, whatsapp, whatsapp_qr, facebook, messenger, instagram, tiktok, telegram, email, phone Fecha ISO 8601. Filtra por última actividad del contacto.
Fecha ISO 8601
Required range:
1 <= x <= 200Required range:
x >= 0