Sessões de Verificação

Uma sessão representa uma verificação de identidade. Criá-la retorna uma widgetUrl que você entrega ao seu cliente e um sessionId que você usa para correlacionar o resultado.

Criar uma Sessão

Endpoint: POST /v1/sessions
Autenticação: Token Bearer com o escopo sessions

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "userRef": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ…"
}

Campos da Requisição

Campos da Resposta

Prefill

O prefill carrega o que você já sabe sobre a pessoa. Ele tem dois efeitos distintos.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingState": "PA",
    "documentNumber": "31612967",
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

Campos de prefill diferentes de documentType não alteram a decisão a menos que você defina dataCheck: true. Sem isso, os valores são carregados para comparação e reportados no resultado, mas uma divergência não encaminha a sessão para lugar nenhum.

O prefill.documentNumber é validado nesta chamada, no entanto: um número que viola o formato conhecido de sua jurisdição é rejeitado com 422 em vez de ser aceito e reprovado depois. Verifique um número antes de chegar aqui com o endpoint validador.

Verificações de Dados

Defina dataCheck: true para verificar que o documento pertence à pessoa que você esperava — não apenas que o documento é genuíno.

{
  "userRef": "user-123",
  "dataCheck": true,
  "prefill": {
    "firstName": "Ana",
    "lastName": "Silva",
    "dateOfBirth": "1988-03-04"
  }
}

Com dataCheck: true:

• Os dados extraídos são comparados campo a campo com o payload de prefill.
• O resultado carrega prefillComparison (resultados por campo, incluindo pontuações de correspondência aproximada de nomes) e prefillMismatches (os nomes dos campos que divergiram).
• Uma divergência adiciona uma verificação branda (soft check) reprovada, encaminhando a sessão para in_review em vez de recusá-la.

Nomes são comparados com correspondência aproximada (fuzzy) contra um limiar de similaridade configurável, então variações comuns de grafia e transliteração não criam falsas divergências. dataCheck: true sem um payload de prefill é um 422 — não haveria nada com que comparar.

Entrega

{ "delivery": { "mode": "redirect", "redirectUrl": "https://you.example/kyc-done" } }

Solicitar o modo webhook sem uma webhookUrl configurada para o seu tenant é um 422. Veja Recebendo Resultados para a verificação de assinatura em ambos os modos.

Respostas de Erro

Todas estas retornam 422 com um detail explicando a causa específica:

Falhas de autenticação e autorização retornam 401 ou 403 — veja Autenticação.

Recuperar uma Sessão

Endpoint: GET /v1/sessions/{sessionId}
Autenticação: Token Bearer com o escopo sessions

Este é o registro autoritativo de uma verificação. Consulte-o quando você precisar de uma garantia em vez de um push, para reconciliar um webhook que você pode ter perdido, ou para ler o resultado de uma sessão que foi para revisão manual.

curl --request GET \
  --url https://{FQDN}/v1/sessions/$SESSION_ID \
  --header "Authorization: Bearer $ACCESS_TOKEN"

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "userRef": "user-123",
  "status": "in_review",
  "step": "done",
  "deliveryMode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "createdAt": "2026-07-31T14:02:11.481Z",
  "updatedAt": "2026-07-31T14:04:57.902Z"
}

As sessões são estritamente limitadas ao tenant. O sessionId de outro tenant retorna 404 — nunca uma divulgação parcial.

Próximos Passos

• Validador de Número de Documento — verifique um número antes de chegar aqui
• Entrega do Widget — conduzindo o cliente pelo fluxo
• Recebendo Resultados — tratamento de webhook e redirect