Ler Resultados KYC de Verificações de Identidade

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.

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

Resposta

"success"

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

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

{
  "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

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.

Consultar detalhes completos

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

curl -H "Authorization: Bearer <TOKEN>" \
  https://api.identity.vu-one.com/api/v1/verifications/f1e2d3c4-b5a6-7890-1234-567890abcdef

Resposta de exemplo

{
  "_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"
  }
}

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.

Listar verificações

Últimas 100 verificações

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

A resposta é um objeto paginado:

{
  "total": 248,
  "page": 1,
  "data": []
}

Verificações da última hora

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

Paginado

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.

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

[
  {
    "_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

A lista fica vazia quando o link da verificação consultada não tem externalUserId para agrupar.

Imagens da verificação

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

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
    }
  }'

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.

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

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.

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"
  }'

{
  "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:

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:

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

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.

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.

Primeiros Passos

Conceitos-Chave

Referência

Ler Resultados KYC de Verificações de Identidade

Ciclo de vida de uma verificação

Etapas do fluxo

Consultar status (polling leve)

Resposta

Consultar detalhes completos

Resposta de exemplo

Listar verificações

Últimas 100 verificações

Verificações da última hora

Paginado

Verificações relacionadas do mesmo cliente

Imagens da verificação

Endpoints públicos do fluxo

Reportar geolocalização

Reportar erro

Identificar a pessoa durante o fluxo

Feedback manual

Referência do objeto geolocation

​Ciclo de vida de uma verificação

​Etapas do fluxo

​Consultar status (polling leve)

​Resposta

​Consultar detalhes completos

​Resposta de exemplo

​Listar verificações

​Últimas 100 verificações

​Verificações da última hora

​Paginado

​Verificações relacionadas do mesmo cliente

​Imagens da verificação

​Endpoints públicos do fluxo

​Reportar geolocalização

​Reportar erro

​Identificar a pessoa durante o fluxo

​Feedback manual

​Referência do objeto geolocation

Ciclo de vida de uma verificação

Etapas do fluxo

Consultar status (polling leve)

Resposta

Consultar detalhes completos

Resposta de exemplo

Listar verificações

Últimas 100 verificações

Verificações da última hora

Paginado

Verificações relacionadas do mesmo cliente

Imagens da verificação

Endpoints públicos do fluxo

Reportar geolocalização

Reportar erro

Identificar a pessoa durante o fluxo

Feedback manual

Referência do objeto geolocation