Ir al contenido
Documentación de Connecto
connecto.lat
Guía de usuarioConfiguración general e IA

API: Consulta de contactos

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étodoRutaPara qué
POST/api/v1/contactos/consultarConsulta con los filtros en el cuerpo (JSON)
GET/api/v1/contactos/consultar?filtro[campo]=valorLa misma consulta con los filtros en la dirección
GET/api/v1/contactos/camposLista 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.

Texto
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
}
DatoQué hace
filtrosObjeto {campo: valor}. Máximo 10 campos.
coincidenciatodos (por defecto: se deben cumplir todos los filtros) o alguno (basta con uno).
pagina, limitePaginació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

CampoOperadoresNotas
idigual, desde, hastaNúmero interno del contacto
nombreigual, contiene, empieza_con, vacio, no_vacioSin importar mayúsculas ni tildes
emailigual, contiene, vacio, no_vacioCualquiera de los correos del contacto (el principal o los adicionales)
telefonoigual, contiene, vacio, no_vacioCualquiera 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).
estadoigualACTIVO, INACTIVO, BANEADO, ELIMINADO. Por defecto no se devuelven los eliminados; pídelos con este filtro.
tipo_contactoigual, contieneId o nombre
propietarioigual, contiene, vacio, no_vacioId o nombre del usuario propietario
idioma, moneda, paisigualCódigos
creado_at, actualizado_at, ultima_actividad_atigual, desde, hastaFecha (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#

JSON
{
  "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). cuentas son las cuentas o identificadores del contacto en esa red; canales_conectados son los canales de tu empresa por los que ha conversado, con cuántas conversaciones tiene y si hay una abierta.
  • total es el número de contactos que cumplen los filtros (aunque la página traiga menos).
  • Si no hay coincidencias, datos viene vacío y total es 0 (no es un error).

Ejemplo: saber si una cédula está registrada (desde el servidor de la web)#

PHP
$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#

HTTPCódigoQué significa
401no_autorizadoFalta la llave o no es válida
403sin_permisoLa llave no tiene contactos:consultar
403llave_expirada, llave_pausada, ip_no_permitidaLa credencial venció, está pausada o se usa desde una IP no permitida
422filtros_requeridosNo enviaste ningún filtro
422campo_desconocidoEl campo no existe o está desactivado (la respuesta trae campos_validos)
422operador_invalido, valor_invalidoEl operador o el valor no sirven para ese campo
422paginacion_excedidaDemasiados resultados para paginar tan lejos: afina los filtros
429limite_excedido, demasiados_intentosSuperaste el límite por minuto o hiciste muchos intentos con llaves inválidas
503api_deshabilitadaLa 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.
¿Te fue útil esta página?
Última actualización: 14/11/2026