Para qué sirve#
Permite que otro sistema (por ejemplo la página web de la empresa) busque contactos en Connecto por uno o varios campos (la cédula, el correo, el teléfono, el estado, un campo que tú creaste…) y reciba todos los datos del contacto y sus redes o canales asociados. Solo lee: no crea ni modifica nada.
Permiso que necesita la credencial: contactos:consultar (lectura). También lo cubre el permiso especial «todas las APIs de lectura».
Quién la habilita: un administrador, en Configuración → APIs y Webhooks: la API viene habilitada y se da acceso marcando la casilla de Lectura de la fila «Consulta de contactos» al generar o al editar una credencial.
Endpoints#
| Método | Ruta | Para qué |
|---|---|---|
POST | /api/v1/contactos/consultar | Consulta con los filtros en el cuerpo (JSON) |
GET | /api/v1/contactos/consultar?filtro[campo]=valor | La misma consulta con los filtros en la dirección |
GET | /api/v1/contactos/campos | Lista los campos por los que se puede consultar, con sus operadores y valores válidos |
Cómo se pide#
Envía en filtros uno o varios campos con su valor. Debe haber al menos un filtro: no se puede pedir toda la base.
POST https://crm.tuempresa.com/api/v1/contactos/consultar
Authorization: Bearer cnx_TU_LLAVE
Content-Type: application/json
{
"filtros": { "numero_documento": "1020304050", "estado": "ACTIVO" },
"coincidencia": "todos",
"pagina": 1,
"limite": 25
}| Dato | Qué hace |
|---|---|
filtros | Objeto {campo: valor}. Máximo 10 campos. |
coincidencia | todos (por defecto: se deben cumplir todos los filtros) o alguno (basta con uno). |
pagina, limite | Paginación: 25 por página por defecto, hasta 100. |
Formas del valor de un campo:
- Un valor:
"estado": "ACTIVO". - Una lista de valores (basta con que coincida uno):
"numero_documento": ["1020304050", "55667788"]. - Con operador:
"nombre": {"operador": "contiene", "valor": "ana"}.
Operadores: igual (por defecto), contiene, empieza_con, desde (≥), hasta (≤), vacio (no tiene valor) y no_vacio. Cada campo admite solo algunos; si usas uno que no admite, el error te dice cuáles.
Con GET: ?filtro[numero_documento]=1020304050&filtro[estado]=ACTIVO. Para varios valores: ?filtro[estado][]=ACTIVO&filtro[estado][]=INACTIVO. Para un operador: ?filtro[nombre][operador]=contiene&filtro[nombre][valor]=ana.
Campos por los que se puede consultar#
La lista depende de tu configuración: si activas, desactivas o creas campos en Configuración, la API (y su guía) se actualizan solas. Consulta GET /contactos/campos o la guía de la credencial para ver los de hoy.
Datos básicos
| Campo | Operadores | Notas |
|---|---|---|
id | igual, desde, hasta | Número interno del contacto |
nombre | igual, contiene, empieza_con, vacio, no_vacio | Sin importar mayúsculas ni tildes |
email | igual, contiene, vacio, no_vacio | Cualquiera de los correos del contacto (el principal o los adicionales) |
telefono | igual, contiene, vacio, no_vacio | Cualquiera de sus teléfonos o WhatsApp. Se comparan los dígitos: «+57 300 123 4567» y «3001234567» coinciden. Con igual envía 9 o más dígitos; con contiene puedes usar desde 6 (más lento). |
estado | igual | ACTIVO, INACTIVO, BANEADO, ELIMINADO. Por defecto no se devuelven los eliminados; pídelos con este filtro. |
tipo_contacto | igual, contiene | Id o nombre |
propietario | igual, contiene, vacio, no_vacio | Id o nombre del usuario propietario |
idioma, moneda, pais | igual | Códigos |
creado_at, actualizado_at, ultima_actividad_at | igual, desde, hasta | Fecha (2026-01-31) o fecha y hora con zona |
Campos opcionales (solo los que estén activos en Configuración → Gestión de contactos): apellidos, tipo_documento (id o nombre), numero_documento (ignora puntos, guiones y espacios; igual, contiene, empieza_con), nacionalidad (código de país o nombre), departamento, ciudad (id o nombre), direccion, fecha_nacimiento. Si consultas uno desactivado, el error lo explica.
Campos personalizados (los que tú creaste): se envían como personalizado_ + la clave del campo, por ejemplo personalizado_origen_lead. Texto: igual, contiene, empieza_con; lista: igual; número: igual, desde, hasta; sí/no: si o no.
Qué devuelve#
{
"datos": [{
"id": 1520, "estado": "ACTIVO", "nombre": "Ana", "apellidos": "Pérez",
"email": "[email protected]", "emails": ["[email protected]"],
"telefono": "+57 300 123 4567", "telefonos": ["+57 300 123 4567"], "whatsapp": ["573001234567"],
"tipo_contacto": {"id": 1, "nombre": "CONTACTO"},
"propietario": {"id": 12, "nombre": "Luis Gómez"},
"idioma": "es", "moneda": "COP", "pais": "CO",
"campos_opcionales": {
"tipo_documento": {"id": 1, "nombre": "CEDULA DE CIUDADANIA"}, "numero_documento": "1020304050",
"nacionalidad": {"codigo": "CO", "nombre": "Colombia"},
"departamento": {"id": 5, "nombre": "Antioquia"}, "ciudad": {"id": 88, "nombre": "Medellín"}
},
"campos_personalizados": {"origen_lead": "Feria"},
"redes": [{
"canal": "whatsapp", "etiqueta": "WhatsApp", "cuentas": ["573001234567"],
"conversaciones": 4, "ultima_actividad_at": "2026-10-14T16:20:00-05:00",
"canales_conectados": [{"canal_id": 3, "nombre": "Línea ventas", "conversaciones": 4, "conversacion_abierta": true, "ultima_actividad_at": "2026-10-14T16:20:00-05:00"}]
}],
"creado_at": "2026-01-10T09:00:00-05:00", "actualizado_at": "2026-10-14T16:20:00-05:00", "ultima_actividad_at": "2026-10-14T16:20:00-05:00"
}],
"total": 1, "pagina": 1, "limite": 25, "hay_mas": false,
"coincidencia": "todos", "filtros_aplicados": {"numero_documento": "igual"}
}redes: una entrada por canal (WhatsApp, Messenger, Instagram, Telegram, TikTok, YouTube, chat web).cuentasson las cuentas o identificadores del contacto en esa red;canales_conectadosson los canales de tu empresa por los que ha conversado, con cuántas conversaciones tiene y si hay una abierta.totales el número de contactos que cumplen los filtros (aunque la página traiga menos).- Si no hay coincidencias,
datosviene vacío ytotales 0 (no es un error).
Ejemplo: saber si una cédula está registrada (desde el servidor de la web)#
$ch = curl_init("https://crm.tuempresa.com/api/v1/contactos/consultar");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("CONNECTO_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["filtros" => ["numero_documento" => $cedula], "limite" => 1]),
]);
$r = json_decode(curl_exec($ch), true);
$existe = ($r["total"] ?? 0) > 0;Importante: haz la llamada desde el servidor de la web, nunca desde el JavaScript de la página (la llave quedaría a la vista). Y a quien visita la página muéstrale solo «sí está registrado» o «no», no los datos del contacto: cualquiera que conozca una cédula ajena podría verlos. Protege el formulario con un captcha y un límite de intentos por IP.
Errores#
| HTTP | Código | Qué significa |
|---|---|---|
| 401 | no_autorizado | Falta la llave o no es válida |
| 403 | sin_permiso | La llave no tiene contactos:consultar |
| 403 | llave_expirada, llave_pausada, ip_no_permitida | La credencial venció, está pausada o se usa desde una IP no permitida |
| 422 | filtros_requeridos | No enviaste ningún filtro |
| 422 | campo_desconocido | El campo no existe o está desactivado (la respuesta trae campos_validos) |
| 422 | operador_invalido, valor_invalido | El operador o el valor no sirven para ese campo |
| 422 | paginacion_excedida | Demasiados resultados para paginar tan lejos: afina los filtros |
| 429 | limite_excedido, demasiados_intentos | Superaste el límite por minuto o hiciste muchos intentos con llaves inválidas |
| 503 | api_deshabilitada | La API está apagada en Configuración |
Rendimiento y seguridad#
- Las búsquedas por cédula, correo, teléfono (9 dígitos o más) y nombre responden en milisegundos aunque haya cientos de miles de contactos, porque usan índices propios que se mantienen solos.
- Los valores se envían siempre como parámetros (no hay forma de inyectar SQL) y el registro de la API no guarda los valores consultados, solo qué campos se usaron.
- No devuelve contactos eliminados salvo que pidas
estado = ELIMINADO, ni los fusionados en otro contacto.