Leer resultados KYC de verificaciones de identidad

Una Verification representa el ciclo completo de verificación de un usuario. Desde que se crea el Link hasta que el usuario finaliza o abandona el proceso, la Verification atraviesa diferentes estados y pasos. Cuando concluye, puedes consultar los datos extraídos del documento, la geolocalización y el resultado de la prueba de vida.

Ciclo de vida de una Verification

La Verification avanza por estados y pasos que reflejan el progreso del usuario en el flujo.

Estados posibles

Estado	Significado
`pending`	El Link fue creado pero el usuario aún no ha iniciado el flujo
`started`	El usuario abrió el enlace y comenzó la verificación
`expired`	El Link superó el tiempo de expiración configurado sin completarse
`success`	La verificación finalizó correctamente, todos los controles pasaron
`failed`	La verificación falló en algún paso (documento inválido, prueba de vida no superada, etc.)

Pasos del flujo

Paso	Descripción
`NEW_OPERATION`	Inicio de una nueva operación de verificación
`ADD_FRONT`	Captura del frente del documento
`ADD_BACK`	Captura del reverso del documento
`END_OPERATION`	Finalización de la operación

Obtener detalles completos de una Verification

Usa GET /verifications/{id} para recuperar todos los datos extraídos, geolocalización y metadatos.

curl -X GET https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8 \
  -H "Authorization: Bearer <token>"

Respuesta de ejemplo

{
  "_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "linkId": "550e8400-e29b-41d4-a716-446655440000",
  "companyId": "9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "userName": "maria.gomez@ejemplo.com",
  "termsAndConditions": true,
  "images": {
    "addFront": "1f2e3d4c-5b6a-7980-9102-a3b4c5d6e7f8",
    "addBack": "2a3b4c5d-6e7f-8091-a2b3-c4d5e6f70819",
    "register": ["3b4c5d6e-7f80-91a2-b3c4-d5e6f7081920"]
  },
  "errorMessage": null,
  "step": "END_OPERATION",
  "detectedDocumentCountry": "ARG",
  "status": "success",
  "data": {
    "firstNames": "MARIA BELEN",
    "lastNames": "GOMEZ",
    "name": "GOMEZ, MARIA BELEN",
    "adult": true,
    "nationality": "ARG",
    "gender": "F",
    "birthDate": "1990-05-15",
    "dateOfIssue": "2015-03-10",
    "dateOfExpiry": "2025-03-10",
    "idNumber": "12345678",
    "ocrRaw": "...",
    "barcodeRaw": "..."
  },
  "expiresAt": "2026-08-23T14:00:00Z",
  "createdAt": "2026-08-22T14:00:00Z",
  "updatedAt": "2026-08-22T14:35:22Z",
  "geolocation": {
    "ip": "190.191.192.193",
    "accuracyRadius": 5,
    "latitude": "-34.6037",
    "longitude": "-58.3816",
    "country": "AR",
    "city": "Buenos Aires",
    "subdivisions": "CABA",
    "accuracy": 10,
    "source": "gps",
    "tier": "precise",
    "permission": "granted",
    "sample": "best_of_session",
    "capturedAt": "2026-08-22T14:32:00Z",
    "deviceLatitude": -34.6037,
    "deviceLongitude": -58.3816,
    "policy": "optional",
    "ipDistanceKm": 0.2,
    "serverIp": "52.84.123.45"
  }
}

El identificador de la verificación viaja en _id. Los datos documentales extraídos por OCR viven dentro del objeto data, no en la raíz de la respuesta.

Polling ligero de estado

GET /verifications/{id}/status es un endpoint público: no lleva token Bearer. En su lugar exige el query param linkId, que demuestra que quien consulta es el usuario final previsto y no alguien que adivinó el verificationId.

curl -X GET "https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8/status?linkId=550e8400-e29b-41d4-a716-446655440000"

Respuesta básica

"success"

Incluir operationGuid y method

Agrega include=operationGuid para recibir un objeto con más contexto. Requiere linkId igualmente.

curl -X GET "https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8/status?linkId=550e8400-e29b-41d4-a716-446655440000&include=operationGuid"

{
  "status": "success",
  "operationGuid": "op_abc123",
  "method": "DOCUMENT"
}

Campo	Descripción
`status`	Estado actual de la verificación
`operationGuid`	Identificador de la operación en OM, para correlacionar telemetría. `null` si aún no existe
`method`	Rama resuelta y persistida para esta verificación: `FACE` (rama adaptativa solo selfie) o `DOCUMENT` (flujo completo documento + rostro). `null` mientras no se haya resuelto

Omitir linkId, o enviar uno que no corresponde a esta verificación, devuelve 403. Este parámetro pasó a ser obligatorio en la versión 2.2.0.

Listar verificaciones

Últimas 100 verificaciones

curl -X GET https://api.identity.vu-one.com/api/v1/verifications \
  -H "Authorization: Bearer <token>"

La respuesta es un objeto paginado:

{
  "total": 248,
  "page": 1,
  "data": [ /* objetos Verification */ ]
}

Verificaciones de la última hora

curl -X GET https://api.identity.vu-one.com/api/v1/verifications/last-hour \
  -H "Authorization: Bearer <token>"

Paginación

curl -X GET "https://api.identity.vu-one.com/api/v1/verifications/20/1" \
  -H "Authorization: Bearer <token>"

Donde 20 es el tamaño de página (máximo 100) y 1 es el número de página.

Verificaciones relacionadas del mismo cliente

GET /verifications/{id}/related devuelve todas las demás verificaciones del mismo cliente, es decir, de la misma compañía y con el mismo externalUserId en su Link, ordenadas de la más reciente a la más antigua.

curl -X GET https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8/related \
  -H "Authorization: Bearer <token>"

[
  {
    "_id": "8c9d0e1f-2a3b-4c5d-6e7f-8091a2b3c4d5",
    "createdAt": "2026-06-01T10:12:00Z",
    "status": "success",
    "dataExpired": false
  },
  {
    "_id": "7b8c9d0e-1f2a-3b4c-5d6e-7f8091a2b3c4",
    "createdAt": "2026-02-14T09:03:00Z",
    "status": "failed",
    "dataExpired": true
  }
]

Campo	Descripción
`_id`	Identificador de la verificación relacionada
`createdAt`	Fecha de creación
`status`	Estado final
`dataExpired`	`true` cuando la retención ya anonimizó esa fila. Muéstrala como DATA EXPIRED en lugar de los campos de identidad, que están hasheados

La lista está vacía cuando el Link de la verificación consultada no tiene externalUserId, porque no hay identificador con el que agrupar.

Imágenes asociadas

Listar imágenes de una verificación

curl -X GET https://api.identity.vu-one.com/api/v1/verifications/6ba7b810-9dad-11d1-80b4-00c04fd430c8/images \
  -H "Authorization: Bearer <token>"

Obtener una imagen por ID

curl -X GET https://api.identity.vu-one.com/api/v1/verifications/images/1f2e3d4c-5b6a-7980-9102-a3b4c5d6e7f8 \
  -H "Authorization: Bearer <token>"

Los identificadores están en el objeto images de la verificación: addFront, addBack y el array register con los frames de la selfie.

Endpoints públicos del flujo

Los tres endpoints siguientes los invoca el dispositivo del usuario durante el flujo, sin token. Todos exigen que la verificación siga asociada a un Link activo y esté en estado pending o started.

Reportar geolocalización

Todos los campos de ubicación viajan anidados dentro del objeto geolocation.

curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "geolocation": {
      "ip": "190.191.192.193",
      "accuracyRadius": 5,
      "city": "Buenos Aires",
      "country": "AR",
      "latitude": -34.6037,
      "longitude": -58.3816,
      "subdivisions": "CABA",
      "accuracy": 10,
      "source": "gps",
      "permission": "granted",
      "sample": "best_of_session",
      "capturedAt": "2026-08-22T14:32:00Z",
      "deviceLatitude": -34.6037,
      "deviceLongitude": -58.3816
    }
  }'

tier, policy, ipDistanceKm y serverIp no son propiedades aceptadas: se derivan en el servidor y la petición se rechaza con 400 si el cliente envía cualquiera de ellas.

Otras dos validaciones devuelven 400:

Declarar un source de dispositivo (gps, wifi o cell) sin deviceLatitude y deviceLongitude.
Un capturedAt que se aparte más de 24 horas del reloj del servidor.

Reportar errores

curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications/error \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "errorCode": "CAMERA_PERMISSION_DENIED",
    "errorMessage": "El usuario denegó el acceso a la cámara"
  }'

Identificar a un usuario en curso

PATCH /verifications/identify cubre el caso de un Link adaptativo creado sin externalUserId. Rellena el externalUserId del Link a partir del email indicado y vuelve a resolver la rama adaptativa.

curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications/identify \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "email": "maria.gomez@ejemplo.com"
  }'

{
  "status": "started",
  "operationGuid": "op_abc123",
  "method": "FACE"
}

Reglas de este endpoint:

Repetir el mismo email siempre es una operación sin efecto y responde 200.
Un identificador que la API fijó al crear el Link no se puede sobrescribir: un email distinto responde 409 con identifierAlreadyBound.
Un identificador que fijó este mismo endpoint (es decir, tecleado por la persona) sí es corregible: un email distinto se acepta y la rama se vuelve a resolver.
Un email inválido o ausente responde 400.

Retroalimentación manual

Si necesitas anular o corregir el resultado de una verificación, usa POST /verifications/feedback.

curl -X POST https://api.identity.vu-one.com/api/v1/verifications/feedback \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "overrideStatus": "success",
    "reasonId": "4c5d6e7f-8091-a2b3-c4d5-e6f708192021"
  }'

Campo	Tipo	Descripción
`verificationId`	uuid	Verificación a corregir
`overrideStatus`	string	Estado con el que quieres anular el resultado automático
`reasonId`	uuid	Identificador del motivo, obtenido del listado de razones

Razones de feedback disponibles

curl -X GET https://api.identity.vu-one.com/api/v1/verification-feedback/reasons \
  -H "Authorization: Bearer <token>"

Cada razón devuelve _id y reason. Usa ese _id como reasonId al enviar el feedback.

Referencia del objeto geolocation

geolocation combina una posición reportada con una medida de cuánto confiar en ella. No aparece hasta que se ha reportado una ubicación, y tier siempre acompaña a las coordenadas: nunca hay una latitud y longitud sueltas.

Campo	Tipo	Descripción
`ip`	string	IP que el servicio de fingerprint atribuyó al cliente. Declarada por el cliente
`accuracyRadius`	number	Radio del área de confianza derivada de IP, en kilómetros
`latitude`	string	Latitud derivada de IP. Se serializa como string
`longitude`	string	Longitud derivada de IP. Se serializa como string
`country`	string	País
`city`	string	Ciudad
`subdivisions`	string	Subdivisión administrativa
`accuracy`	number	`coords.accuracy` del W3C: radio de confianza del 95 % que reporta el navegador, en metros. Solo presente si hubo fix de dispositivo
`source`	string	Mecanismo que produjo el fix: `gps`, `wifi`, `cell`, `ip` o `none`
`tier`	string	Precisión real de la posición, derivada en el servidor a partir de `accuracy`: `precise` (≤100 m), `approximate` (≤5 km), `coarse` (>5 km o derivada de IP), `unknown` (sin posición que calificar)
`permission`	string	Estado del permiso del navegador durante la captura: `granted`, `denied` o `prompt`
`sample`	string	Muestra reportada. `best_of_session` es el fix más ajustado visto antes de iniciar el flujo
`capturedAt`	date-time	Momento en que el dispositivo tomó la muestra. Declarado por el cliente
`deviceLatitude`	number	Latitud del fix de dispositivo. Se serializa como número, a diferencia del par derivado de IP
`deviceLongitude`	number	Longitud del fix de dispositivo. Se serializa como número
`policy`	string	Solo en GET autenticado. Política `locationPermission` vigente cuando se capturó este resultado: `never`, `optional` o `required`
`ipDistanceKm`	number	Solo en GET autenticado. Distancia entre el fix del dispositivo y la posición derivada de IP, calculada en el servidor. `null` si no hay fix de dispositivo que comparar
`serverIp`	string	Solo en GET autenticado. IP de la petición que observó el servidor en el PATCH de geolocalización, distinta de la `ip` declarada por el cliente

policy, ipDistanceKm y serverIp se devuelven únicamente en los GET autenticados. No aparecen en las respuestas del PATCH público ni en los webhooks. Devolver estas señales antifraude a un llamador no autenticado le permitiría calibrar una ubicación falsificada contra el control diseñado para detectarla.

source es un valor inferido, no medido: la Geolocation API del W3C no expone su proveedor, así que gps, wifi y cell se deducen en el cliente a partir de bandas de altitud, velocidad y precisión. Solo ip y none son certeros. Al ser declarado por el cliente, todo el conjunto es falsificable: el ipDistanceKm calculado en el servidor es el contraste.

Para aplicaciones en tiempo real, combina webhooks con polling ligero de GET /verifications/{id}/status. Los webhooks te notifican del cambio, y el polling te permite confirmar el estado si el webhook se demora.

Primeros Pasos

Conceptos Clave

Referencia

Leer resultados KYC de verificaciones de identidad

Ciclo de vida de una Verification

Estados posibles

Pasos del flujo

Obtener detalles completos de una Verification

Respuesta de ejemplo

Polling ligero de estado

Respuesta básica

Incluir operationGuid y method

Listar verificaciones

Últimas 100 verificaciones

Verificaciones de la última hora

Paginación

Verificaciones relacionadas del mismo cliente

Imágenes asociadas

Listar imágenes de una verificación

Obtener una imagen por ID

Endpoints públicos del flujo

Reportar geolocalización

Reportar errores

Identificar a un usuario en curso

Retroalimentación manual

Razones de feedback disponibles

Referencia del objeto geolocation

​Ciclo de vida de una Verification

​Estados posibles

​Pasos del flujo

​Obtener detalles completos de una Verification

​Respuesta de ejemplo

​Polling ligero de estado

​Respuesta básica

​Incluir operationGuid y method

​Listar verificaciones

​Últimas 100 verificaciones

​Verificaciones de la última hora

​Paginación

​Verificaciones relacionadas del mismo cliente

​Imágenes asociadas

​Listar imágenes de una verificación

​Obtener una imagen por ID

​Endpoints públicos del flujo

​Reportar geolocalización

​Reportar errores

​Identificar a un usuario en curso

​Retroalimentación manual

​Razones de feedback disponibles

​Referencia del objeto geolocation

Ciclo de vida de una Verification

Estados posibles

Pasos del flujo

Obtener detalles completos de una Verification

Respuesta de ejemplo

Polling ligero de estado

Respuesta básica

Incluir operationGuid y method

Listar verificaciones

Últimas 100 verificaciones

Verificaciones de la última hora

Paginación

Verificaciones relacionadas del mismo cliente

Imágenes asociadas

Listar imágenes de una verificación

Obtener una imagen por ID

Endpoints públicos del flujo

Reportar geolocalización

Reportar errores

Identificar a un usuario en curso

Retroalimentación manual

Razones de feedback disponibles

Referencia del objeto geolocation