Screening y listas

Además del screening que corre al enviar un caso, puedes consultar un nombre suelto, vigilar a tus clientes cuando cambian las listas y cargar listas propias.

Screening suelto

Consulta sin caso, contra todas las listas activas de tu cuenta o las que indiques. Tiene su propia cuota mensual.

curl -s -X POST "$KYC_BASE/v1/screening" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: scr-$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Nombre Apellido Ejemplo","tipo":"PERSONA","fechaNacimiento":"1970-01-01","pais":"VE"}'

{
  "id": "scr_01J9Z3K8Q2W7XPT4M6N5R0B1CG",
  "ejecutadoEn": "2026-10-15T13:00:00Z",
  "umbral": 0.8,
  "listasConsultadas": [ { "lista": "ONU", "version": "2026-10-14" }, { "lista": "PROPIA", "version": "12" } ],
  "coincidencias": [
    {
      "lista": "ONU",
      "entradaId": "QDi.000",
      "nombreEntrada": "NOMBRE APELLIDO EJEMPLO",
      "tipoEntrada": "PERSONA",
      "puntaje": 0.86,
      "desglose": { "nombre": 0.91, "fechaNacimiento": 1.0, "metodo": "jaro-winkler, token-set, fonetica-es" },
      "severidad": "ALTA",
      "veredicto": "DUDOSA",
      "categoria": "SANCION"
    }
  ]
}

Campo	Notas
nombre	Obligatorio, de 2 a 200 caracteres.
listas	Opcional. Códigos de lista; por defecto, todas las activas de tu cuenta.
umbral	Opcional, de 0,5 a 1. Por defecto el de tu cuenta (0,80).

Cada coincidencia trae la lista y su versión, el puntaje con su desglose, el veredicto (FUERTE desde 0,92 o DUDOSA desde el umbral, con los valores por defecto de tu cuenta) y la categoria (SANCION, PEP o INTERNA). El puntaje orienta al oficial; no es una decisión.

PEP básico

Las coincidencias PEP traen cargo, relación (TITULAR, FAMILIAR o ALLEGADO) y vigencia. La fuente básica es abierta y no exhaustiva: coberturaPep lo indica en cada respuesta, y una consulta sin coincidencias no significa que la persona no sea PEP. Complétala con tu lista propia de PEP.

Monitoreo continuo

Suscribe un caso o un solicitante suelto. Cuando se publica una versión nueva de una lista, se vuelve a revisar y las coincidencias nuevas llegan como alerta y por el webhook monitoreo.coincidencia_nueva.

curl -s -X POST "$KYC_BASE/v1/monitoreo" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: mon-1001" \
  -H "Content-Type: application/json" \
  -d '{"casoId":"cas_01J9Z3K8Q2W7XPT4M6N5R0B1CD","referenciaExterna":"cliente-1001"}'
# → 201 { "id": "mon_…", "estado": "ACTIVO", "creadoEn": "…" }

Listas propias

Fraude previo, oficios del regulador, empleados o tu propia lista de PEP. Entran en el screening igual que las listas oficiales.

curl -s -X POST "$KYC_BASE/v1/listas" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: lista-fraude" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Fraude previo","severidad":"ALTA","categoria":"INTERNA"}'

curl -s -X POST "$KYC_BASE/v1/listas/$LISTA/entradas" \
  -H "X-API-Key: $KYC_API_KEY" -H "Idempotency-Key: carga-2026-10" \
  -H "Content-Type: text/csv" --data-binary @fraude.csv
# → 201 { "aceptadas": 120, "rechazadas": 1, "errores": [ { "fila": 37, "mensaje": "…" } ] }

• CSV con las columnas nombre,tipo,fechaNacimiento,pais,documento,motivo,fuente.
• Para una lista de PEP ("categoria":"PEP") se suman cargo, institucion, relacion, parentesco, pep_vinculado, vigencia_desde y vigencia_hasta. La plantilla se descarga desde la consola de KYC.
• En JSON, hasta 1 000 entradas por carga.