Búsqueda Facial 1:N: Encontrando Todas las Cuentas Controladas por una Persona (ES)

Un operador que maneja cuarenta cuentas en tu plataforma tiene cuarenta direcciones de correo electrónico, probablemente cuarenta instrumentos de pago y posiblemente cuarenta dispositivos. Lo que no tiene son cuarenta rostros.

Si alguna parte de tu flujo de acceso captura una selfie, ya estás guardando el único identificador que es genuinamente costoso de multiplicar. La Búsqueda Facial 1:N es la llamada que lo utiliza: una solicitud, un rostro, y de vuelta recibes cada cuenta en tu propio sistema que la misma persona verificó.

Es gratuito con la verificación de identidad de Didit, se devuelve en menos de dos segundos y se ejecuta automáticamente durante la prueba de vida dentro de una sesión de verificación.

Puntos clave

• POST /v3/face-search/ busca un rostro contra los rostros que tu propia aplicación ha registrado — sesiones ejecutadas con save_api_request=true — no un índice global compartido.
• Las coincidencias se devuelven con tu propio vendor_data en cada una, por lo que los resultados se asignan directamente a tus IDs de cuenta.
• Dos modos: most_similar para deduplicación y usuarios recurrentes, blocklisted_or_approved para el cribado de listas negras.
• El status es "Declined" solo en caso de coincidencia con una lista negra. Los duplicados devuelven "Approved" con una advertencia DUPLICATED_FACE — informativa por diseño, porque la política de deduplicación es tuya.
• La respuesta es un objeto face_search singular, no un array. Esto confunde a la gente.
• Gratuito con la verificación de Didit. Respuesta en menos de dos segundos. Se ejecuta automáticamente durante la prueba de vida.

Qué significa 1:N y por qué es la herramienta adecuada

Una coincidencia facial 1:1 responde "¿es esta la persona de este documento?". Esa es una pregunta de verificación, y es lo que se ejecuta durante la incorporación.

Una búsqueda 1:N responde a una pregunta diferente: "de todas las personas que ya he verificado, ¿es esta una de ellas?". Una imagen entra y cada coincidencia en tu índice sale.

Para el abuso de cuentas coordinado, la segunda pregunta es la que importa. El informe de Anthropic sobre campañas de destilación describía la atribución construida a partir de señales relacionales: métodos de pago compartidos, sincronización coordinada, infraestructura compartida. Una búsqueda biométrica 1:N es la misma clase de señal, obtenida del identificador más costoso que un operador tiene que multiplicar.

El índice es tuyo. La Búsqueda Facial se ejecuta contra los rostros que tu propia aplicación registró a través de verificaciones previas — sesiones con save_api_request=true, o Prueba de Vida Pasiva con save_api_request=true. No es una búsqueda entre los usuarios de otros clientes de Didit. Si no has registrado rostros, no hay nada que buscar.

La API

Solicitud

curl -X POST 'https://verification.didit.me/v3/face-search/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'search_type=most_similar' \
  -F 'save_api_request=true' \
  -F 'vendor_data=acct_8842'

multipart/form-data, autenticado con x-api-key.

Obligatorio: user_image — jpg, jpeg, png, tiff o webp, máximo 5 MB. No se aceptan PDFs. La imagen debe contener al menos un rostro detectable; cuando hay varios, la caja delimitadora más grande es la que gana.

Opcional:

• search_type — most_similar (por defecto) para deduplicación y detección de usuarios recurrentes, o blocklisted_or_approved para el cribado de listas negras.
• save_api_request — inscribe esta imagen en tu índice.
• vendor_data — tu propio identificador para el sujeto.

Respuesta

La respuesta contiene un objeto face_search singular. La mayoría de las funciones de Didit devuelven arrays plurales, por lo que esta es la única forma que vale la pena leer cuidadosamente antes de escribir el analizador.

{
  "request_id": "...",
  "face_search": {
    "status": "Approved",
    "total_matches": 12,
    "matches": [
      {
        "session_id": "...",
        "session_number": 4471,
        "similarity_percentage": 97.4,
        "vendor_data": "acct_3310",
        "verification_date": "2026-06-02T09:14:00Z",
        "user_details": { },
        "match_image_url": "...",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": { "entities": [] },
    "warnings": []
  }
}

Los campos que llevan la investigación:

• total_matches — cuántas cuentas comparten este rostro.
• vendor_data en cada coincidencia — tu identificador, por lo que una lista de coincidencias es inmediatamente una lista de cuentas.
• similarity_percentage — la fuerza de cada coincidencia individual.
• verification_date — la línea de tiempo. Doce cuentas verificadas a lo largo de once meses se leen de manera diferente a doce verificadas en una tarde.
• is_blocklisted — si esta coincidencia ya está en tu lista negra.
• session_id — el pivote hacia todo lo demás que esa sesión capturó, incluyendo sus advertencias de dispositivo y red.

Semántica de estado

Este es el comportamiento más importante de todo el endpoint:

El status es "Declined" solo cuando se encuentra al menos una coincidencia en la lista negra. Las coincidencias puramente duplicadas devuelven "Approved".

Un duplicado no es un rechazo. Es información. Didit se niega deliberadamente a tomar la decisión de deduplicación por ti, porque los duplicados tienen explicaciones legítimas y solo tú conoces las reglas de tu producto.

Advertencias

Advertencia	Significado
FACE_IN_BLOCKLIST	Coincidencia definitiva en lista negra — rechazar
POSSIBLE_FACE_IN_BLOCKLIST	Coincidencia límite por debajo del umbral estricto — enviar a revisión manual
DUPLICATED_FACE	Este rostro ya está verificado bajo un vendor_data diferente
POSSIBLE_DUPLICATED_FACE	Duplicado límite
MULTIPLE_FACES_DETECTED	Más de un rostro en la imagen enviada

Modos de fallo

• HTTP 400 — no se detectó ningún rostro en user_image. Solicitar una nueva toma.
• HTTP 403 — sin créditos.
• status: "Declined" con FACE_IN_BLOCKLIST — coincidencia definitiva. Rechazar.
• POSSIBLE_FACE_IN_BLOCKLIST — por debajo del umbral estricto. Revisión manual.
• DUPLICATED_FACE — ya verificado bajo un vendor_data diferente. Fusionar, bloquear o permitir según tu política.

La ruta automática

A menudo, no es necesario llamar al endpoint en absoluto. La Búsqueda Facial se ejecuta automáticamente durante la prueba de vida dentro de una sesión de verificación:

• Los datos biométricos faciales se comparan con todos los usuarios verificados previamente.
• Las cuentas duplicadas potenciales se identifican por similitud facial.
• Las coincidencias se marcan según los umbrales de similitud configurados.
• Los rostros se cotejan con tu lista negra, y una coincidencia en la lista negra rechaza automáticamente la verificación.

Así que, para cualquier nivel en el que ya ejecutes una verificación completa, la detección de duplicados se incluye sin coste adicional ni llamadas extra. El endpoint independiente es para los casos que el flujo de sesión no cubre — investigar una cuenta a posteriori, cribar una imagen obtenida de otra manera, o cambiar search_type para ejecutar una búsqueda centrada en la lista negra sobre una imagen que ya tienes.

Convirtiendo coincidencias en un mapa de actores

El flujo de trabajo práctico, comenzando desde una cuenta sospechosa:

1. Busca el rostro. total_matches: 12 — doce cuentas, una persona.
2. Lee el vendor_data. Doce de tus propios IDs de cuenta, sin necesidad de unión.
3. Lee la línea de tiempo. Agrupa los valores de verification_date. Las cuentas creadas en ráfagas son operativamente diferentes de las cuentas creadas a lo largo de años.
4. Pivota en session_id. Obtén las advertencias de dispositivo y red de cada sesión. Los rostros que comparten DUPLICATED_DEVICE_FINGERPRINT ajustan el grupo; las cuentas en dispositivos no relacionados pueden ser una disposición diferente.
5. Expande. Los dispositivos y rangos de IP que aparecen en el paso 4 atraerán cuentas que la búsqueda facial pasó por alto, porque una persona diferente completó esas verificaciones.
6. Decide una vez, aplica en todos los identificadores. Si se confirma el abuso del grupo, publica el reference_session_id confirmado en cada lista negra de tipo de entrada que te interese: rostro, dispositivo, IP, correo electrónico, teléfono, documento. Es una llamada por lista, y cada llamada extrae automáticamente el valor correcto de esa sesión, por lo que nada se vuelve a escribir a mano.

Seis pasos, un punto de partida y ninguna inspección de indicaciones en ningún lugar. La capa de tráfico te dice algo está mal con esta cuenta. Esto te dice cuántas cuentas son realmente.

Vale la pena decirlo claramente: una búsqueda facial 1:N no previene la extracción de modelos ni la detecta. La Búsqueda Facial no tiene visibilidad del tráfico de tu API. Resuelve cuentas a personas, lo que te permite actuar sobre una alerta en todo un grupo en lugar de una sola fila. Los controles de salida a nivel de modelo y la detección semántica de tráfico son capas separadas, y siguen siendo responsabilidad del proveedor del modelo.

Casos de uso

Plataformas de API de IA resolviendo una alerta de comportamiento en el conjunto completo de cuentas que controla un operador.

Abuso de niveles gratuitos y créditos — una persona, muchas cuentas de prueba, es el mismo problema de detección con menores riesgos.

Mercados y plataformas de servicios detectando a vendedores, conductores o repartidores prohibidos que se vuelven a registrar.

Juegos en línea (iGaming) aplicando reglas de cuenta única y autoexclusión, donde un jugador excluido que regresa es un fallo regulatorio, no solo un caso de abuso.

Servicios financieros identificando redes de identidad sintética donde un rostro real se distribuye entre muchas identidades fabricadas.

Preguntas frecuentes

¿Mi índice facial se comparte con otros clientes de Didit?

No. La Búsqueda Facial se ejecuta contra el índice que tu propia aplicación construyó a través de tus propias verificaciones. No es una búsqueda entre clientes.

¿Qué controla si un rostro entra en el índice?

save_api_request=true en una sesión de verificación o una llamada de prueba de vida pasiva. Tú decides qué se inscribe y controlas la retención, de acuerdo con tu propio aviso de privacidad y base legal para el procesamiento de datos biométricos.

¿Qué umbral de similitud debo usar?

Ten en cuenta dónde se aplica el ajuste. En el endpoint independiente, las bandas de similitud que separan las coincidencias confirmadas (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de las posibles coincidencias (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) están fijadas internamente — el ajuste del umbral por aplicación se aplica a la verificación de prueba de vida del flujo de trabajo, no a POST /v3/face-search/. Así que, en la ruta independiente, lee el similarity_percentage por coincidencia y aplica tu propio criterio en la lógica de la aplicación, y trata las advertencias POSSIBLE_* como tu cola de revisión en lugar de tu cola de rechazo.

¿Qué tan rápido es a escala?

Respuesta en menos de dos segundos.

¿Puedo buscar un rostro que nunca pasó por la verificación de Didit?

Sí. Cualquier user_image en un formato aceptado funciona. Si no se detecta ningún rostro, la llamada devuelve HTTP 400.

¿Es realmente gratis?

Sí, la Búsqueda Facial 1:N es gratuita con la verificación de identidad de Didit. No hay cargo por búsqueda. Estás pagando por las verificaciones que construyen el índice, a $0.33 por el paquete completo, con las primeras 500 gratuitas cada mes.

¿Qué pasa si la misma persona tiene legítimamente dos cuentas?

Entonces DUPLICATED_FACE es exactamente la señal informativa que está diseñada para ser, por lo que no declina. Fusiónalas, permítelas o pregunta al usuario, según las reglas de tu producto.

¿Listo para empezar?

La Búsqueda Facial está disponible en todas las cuentas de Didit, sin necesidad de comprar un producto aparte.

• Lee la documentación — Descripción general de la Búsqueda Facial 1:N y la API de Listas para listas negras faciales.
• Ver el producto — Verificación de Usuario.
• Consulta los precios — La Búsqueda Facial 1:N es gratuita; el paquete de verificación que construye el índice cuesta $0.33.
• Empieza gratis — business.didit.me, 500 verificaciones KYC al mes sin coste.