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

# Ler Resultados KYC de Verificações de Identidade

> Consulte o status e os dados documentais extraídos por OCR após a conclusão de uma verificação de identidade com Identity Link.

Após o usuário final concluir o fluxo no link de verificação, a API processa os dados do documento por OCR e, no caso de `FULL FLOW`, executa a prova de vida. Você consulta os resultados pelo `verificationId` para obter o status, os campos extraídos e a geolocalização.

## Ciclo de vida de uma verificação

Uma verificação passa pelos seguintes status:

| Status | Significado |
| - | - |
| `pending` | Criada, aguardando o usuário acessar o link |
| `started` | Usuário iniciou o fluxo no navegador |
| `expired` | Link ou sessão expirou antes da conclusão |
| `success` | Verificação concluída com sucesso |
| `failed` | Verificação concluída, mas com falha (documento inválido, spoofing, etc.) |

## Etapas do fluxo

A propriedade `step` indica em qual ponto do processo a verificação está:

| Step | Descrição |
| - | - |
| `NEW_OPERATION` | Início de uma nova operação |
| `ADD_FRONT` | Captura da frente do documento |
| `ADD_BACK` | Captura do verso do documento |
| `END_OPERATION` | Finalização da operação |

## Consultar status (polling leve)

`GET /verifications/{id}/status` é um endpoint **público**: não leva token Bearer. Em vez disso, exige o parâmetro de consulta `linkId`, que comprova que quem consulta é o usuário final pretendido e não alguém que adivinhou o `verificationId`.

```bash theme={null}
curl "https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef/status?linkId=a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

### Resposta

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

Para obter também o `operationGuid` e a ramificação resolvida, adicione `include=operationGuid`. O `linkId` continua obrigatório:

```bash theme={null}
curl "https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef/status?linkId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&include=operationGuid"
```

```json theme={null}
{
  "status": "success",
  "operationGuid": "op-12345678-1234-1234-1234-123456789abc",
  "method": "DOCUMENT"
}
```

| Campo | Descrição |
| - | - |
| `status` | Status atual da verificação |
| `operationGuid` | Identificador da operação no OM, para correlacionar telemetria. `null` enquanto não atribuído |
| `method` | Ramificação resolvida no servidor e persistida uma única vez: `FACE` (apenas selfie, adaptativa) ou `DOCUMENT` (fluxo completo). `null` enquanto não resolvida |

<Warning>
  Omitir o `linkId`, ou enviar um que não corresponda a esta verificação, retorna **403**. Esse parâmetro passou a ser obrigatório na versão 2.2.0.
</Warning>

## Consultar detalhes completos

Este endpoint retorna todos os dados da verificação, incluindo os campos extraídos por OCR e a geolocalização.

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef
```

### Resposta de exemplo

```json theme={null}
{
  "_id": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
  "linkId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "companyId": "9f1c2b3a-4d5e-6f70-8192-a3b4c5d6e7f8",
  "userName": "maria.silva@exemplo.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": "BRA",
  "status": "success",
  "data": {
    "firstNames": "MARIA",
    "lastNames": "SILVA",
    "name": "MARIA SILVA",
    "adult": true,
    "nationality": "BRA",
    "gender": "F",
    "birthDate": "1990-05-15",
    "dateOfIssue": "2015-03-10",
    "dateOfExpiry": "2025-03-10",
    "idNumber": "12345678901",
    "ocrRaw": "...",
    "barcodeRaw": "..."
  },
  "expiresAt": "2026-08-23T14:00:00Z",
  "createdAt": "2026-08-22T14:00:00Z",
  "updatedAt": "2026-08-22T14:35:22Z",
  "geolocation": {
    "ip": "200.123.45.67",
    "accuracyRadius": 50,
    "latitude": "-23.5505",
    "longitude": "-46.6333",
    "country": "BR",
    "city": "Sao Paulo",
    "subdivisions": "SP",
    "accuracy": 10,
    "source": "gps",
    "tier": "precise",
    "permission": "granted",
    "sample": "best_of_session",
    "capturedAt": "2026-08-22T14:32:00Z",
    "deviceLatitude": -23.5505,
    "deviceLongitude": -46.6333,
    "policy": "optional",
    "ipDistanceKm": 0.5,
    "serverIp": "203.0.113.1"
  }
}
```

<Note>
  O identificador da verificação vem em `_id`. Os campos documentais extraídos por OCR ficam dentro do objeto `data`, não na raiz da resposta. Os campos retornados dependem do tipo de documento enviado: documentos de países diferentes podem trazer conjuntos distintos.
</Note>

## Listar verificações

### Últimas 100 verificações

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

A resposta é um objeto paginado:

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

### Verificações da última hora

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

### Paginado

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

O formato é `GET /verifications/{size}/{page}`, onde `size` é o tamanho da página (máximo `100`) e `page` é o número da página.

## Verificações relacionadas do mesmo cliente

`GET /verifications/{id}/related` retorna todas as demais verificações do mesmo cliente, ou seja, da mesma empresa e com o mesmo `externalUserId` no link, da mais recente para a mais antiga.

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef/related
```

```json theme={null}
[
  {
    "_id": "8c9d0e1f-2a3b-4c5d-6e7f-8091a2b3c4d5",
    "createdAt": "2026-06-01T10:12:00Z",
    "status": "success",
    "dataExpired": false
  }
]
```

| Campo | Descrição |
| - | - |
| `_id` | Identificador da verificação relacionada |
| `createdAt` | Data de criação |
| `status` | Status final |
| `dataExpired` | `true` quando a retenção já anonimizou essa linha. Exiba como DATA EXPIRED em vez dos campos de identidade, que estão hasheados |

<Note>
  A lista fica vazia quando o link da verificação consultada não tem `externalUserId` para agrupar.
</Note>

## Imagens da verificação

```bash theme={null}
# Listar todas as imagens de uma verificação
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef/images

# Obter uma imagem pelo id
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verifications/images/1f2e3d4c-5b6a-7980-9102-a3b4c5d6e7f8
```

Os ids vêm do objeto `images` da verificação: `addFront`, `addBack` e o array `register` com os frames da selfie.

## Endpoints públicos do fluxo

Os três endpoints abaixo são chamados pelo dispositivo do usuário durante o fluxo, sem token. Todos exigem que a verificação continue vinculada a um link ativo e esteja em status `pending` ou `started`.

### Reportar geolocalização

Todos os campos de localização viajam **aninhados dentro do objeto `geolocation`**.

```bash theme={null}
curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "geolocation": {
      "ip": "200.123.45.67",
      "accuracyRadius": 50,
      "city": "Sao Paulo",
      "country": "BR",
      "latitude": -23.5505,
      "longitude": -46.6333,
      "subdivisions": "SP",
      "accuracy": 10,
      "source": "gps",
      "permission": "granted",
      "sample": "best_of_session",
      "capturedAt": "2026-08-22T14:32:00Z",
      "deviceLatitude": -23.5505,
      "deviceLongitude": -46.6333
    }
  }'
```

<Warning>
  `tier`, `policy`, `ipDistanceKm` e `serverIp` **não** são propriedades aceitas: os quatro são derivados no servidor e a requisição é rejeitada com **400** se o cliente enviar qualquer um deles.
</Warning>

Outras duas validações retornam **400**:

* Declarar um `source` de dispositivo (`gps`, `wifi` ou `cell`) sem `deviceLatitude` e `deviceLongitude`.
* Um `capturedAt` que se afaste mais de 24 horas do relógio do servidor.

### Reportar erro

```bash theme={null}
curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications/error \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "errorCode": "CAMERA_PERMISSION_DENIED",
    "errorMessage": "O usuario negou o acesso a camera"
  }'
```

### Identificar a pessoa durante o fluxo

`PATCH /verifications/identify` atende ao caso de um link adaptativo criado sem `externalUserId`. Ele preenche o `externalUserId` do link a partir do e-mail informado e resolve novamente a ramificação adaptativa.

```bash theme={null}
curl -X PATCH https://api.identity.vu-one.com/api/v1/verifications/identify \
  -H "Content-Type: application/json" \
  -d '{
    "verificationId": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "email": "maria.silva@exemplo.com"
  }'
```

```json theme={null}
{
  "status": "started",
  "operationGuid": "op-12345678-1234-1234-1234-123456789abc",
  "method": "FACE"
}
```

Regras deste endpoint:

* Repetir o mesmo e-mail é sempre uma operação sem efeito e responde **200**.
* Um identificador que a API fixou na criação do link **não** pode ser sobrescrito: um e-mail diferente responde **409** com `identifierAlreadyBound`.
* Um identificador definido por este mesmo endpoint, ou seja, digitado pela pessoa, é corrigível: um e-mail diferente é aceito e a ramificação é resolvida novamente.
* Um e-mail inválido ou ausente responde **400**.

## Feedback manual

Use `POST /verifications/feedback` para sobrepor ou corrigir o resultado de uma verificação:

```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": "f1e2d3c4-b5a6-7890-1234-567890abcdef",
    "overrideStatus": "success",
    "reasonId": "4c5d6e7f-8091-a2b3-c4d5-e6f708192021"
  }'
```

| Campo | Tipo | Descrição |
| - | - | - |
| `verificationId` | uuid | Verificação a corrigir |
| `overrideStatus` | string | Status que sobrepõe o resultado automático |
| `reasonId` | uuid | Identificador do motivo, obtido na lista de motivos |

Para listar os motivos de feedback disponíveis, cada um com `_id` e `reason`. Use esse `_id` como `reasonId`:

```bash theme={null}
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verification-feedback/reasons
```

## Referência do objeto geolocation

`geolocation` combina uma posição reportada com uma medida de quanto confiar nela. Só aparece depois que uma localização foi reportada, e `tier` sempre acompanha as coordenadas: nunca há uma latitude e longitude soltas.

| Campo | Tipo | Descrição |
| - | - | - |
| `ip` | string | IP que o serviço de fingerprint atribuiu ao cliente. Declarado pelo cliente |
| `accuracyRadius` | number | Raio da área de confiança derivada de IP, em **quilômetros** |
| `latitude` | string | Latitude derivada de IP, serializada como string |
| `longitude` | string | Longitude derivada de IP, serializada como string |
| `country` | string | País |
| `city` | string | Cidade |
| `subdivisions` | string | Subdivisão administrativa |
| `accuracy` | number | `coords.accuracy` do W3C: raio de confiança de 95% do próprio dispositivo, em **metros**. Presente apenas quando há fix de dispositivo |
| `source` | string | Mecanismo que produziu o fix: `gps`, `wifi`, `cell`, `ip` ou `none` |
| `tier` | string | Precisão real da posição, derivada no servidor a partir de `accuracy`: `precise` (≤100 m), `approximate` (≤5 km), `coarse` (>5 km ou derivada de IP), `unknown` (sem posição a classificar) |
| `permission` | string | Estado da permissão do navegador durante a captura: `granted`, `denied` ou `prompt` |
| `sample` | string | Amostra reportada. `best_of_session` é o fix mais preciso visto antes do início do fluxo |
| `capturedAt` | date-time | Momento em que o dispositivo tirou a amostra. Declarado pelo cliente |
| `deviceLatitude` | number | Latitude do fix de dispositivo, serializada como **número**, ao contrário do par derivado de IP |
| `deviceLongitude` | number | Longitude do fix de dispositivo, serializada como **número** |
| `policy` | string | Apenas no GET autenticado. Política `locationPermission` vigente quando este resultado foi capturado: `never`, `optional` ou `required` |
| `ipDistanceKm` | number | Apenas no GET autenticado. Distância entre o fix do dispositivo e a posição derivada de IP, calculada no servidor. `null` quando não há fix de dispositivo para comparar |
| `serverIp` | string | Apenas no GET autenticado. IP da requisição observado pelo servidor no PATCH de geolocalização, distinto do `ip` declarado pelo cliente |

<Warning>
  `policy`, `ipDistanceKm` e `serverIp` são retornados **apenas** pelos GET autenticados. Não aparecem nas respostas do PATCH público nem nos webhooks. Devolver esses sinais antifraude a um chamador não autenticado permitiria calibrar uma localização falsificada contra a própria checagem criada para detectá-la.
</Warning>

<Note>
  `source` é um valor **inferido**, não medido: a Geolocation API do W3C não expõe seu provedor, então `gps`, `wifi` e `cell` são deduzidos no cliente a partir de faixas de altitude, velocidade e precisão. Apenas `ip` e `none` são certos. Por serem declarados pelo cliente, todos os valores são falsificáveis: o `ipDistanceKm` calculado no servidor é o contraponto.
</Note>


## Related topics

- [Documentação técnica da VU](/pt/index.md)
- [Início rápido: sua primeira verificação de identidade](/pt/quickstart.md)
- [Changelog da Identity Link API](/pt/identity-link/changelog.md)
- [Ler a resposta](/pt/vucs/antispoofing-facial/respostas.md)
- [Identity Link API: Guia de Integração Completo](/pt/identity-link/introducao.md)


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