> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leer resultados KYC de verificaciones de identidad

> Consulta el estado y los datos documentales extraídos por OCR tras completar una verificación de identidad con Identity Link.

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.

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

### Respuesta de ejemplo

```json theme={null}
{
  "_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"
  }
}
```

<Note>
  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.
</Note>

## 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`.

```bash theme={null}
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

```json theme={null}
"success"
```

### Incluir operationGuid y method

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

```bash theme={null}
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"
```

```json theme={null}
{
  "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 |

<Warning>
  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.
</Warning>

## Listar verificaciones

### Últimas 100 verificaciones

```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/verifications \
  -H "Authorization: Bearer <token>"
```

La respuesta es un objeto paginado:

```json theme={null}
{
  "total": 248,
  "page": 1,
  "data": [ /* objetos Verification */ ]
}
```

### Verificaciones de la última hora

```bash theme={null}
curl -X GET https://api.identity.vu-one.com/api/v1/verifications/last-hour \
  -H "Authorization: Bearer <token>"
```

### Paginación

```bash theme={null}
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.

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

```json theme={null}
[
  {
    "_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 |

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

## Imágenes asociadas

### Listar imágenes de una verificación

```bash theme={null}
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

```bash theme={null}
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`**.

```bash theme={null}
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
    }
  }'
```

<Warning>
  `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.
</Warning>

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

```bash theme={null}
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.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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`.

```bash theme={null}
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

```bash theme={null}
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 |

<Warning>
  `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.
</Warning>

<Note>
  `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.
</Note>

<Tip>
  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.
</Tip>


## Related topics

- [Documentación técnica de VU](/index.md)
- [Inicio rápido: tu primera verificación de identidad](/quickstart.md)
- [Identity Link API: guía de integración completa](/identity-link/introduccion.md)
- [Leer la respuesta](/vucs/antispoofing-facial/respuestas.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.