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…",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

Campos da Requisição

Campos da Resposta

Prefill

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

Todo campo de prefill é uma string de no máximo 255 caracteres. Envie um campo apenas quando tiver um valor para ele: um valor em branco ou só com espaços é rejeitado em vez de ignorado, para que um campo que você não forneceu nunca seja reportado como um com o qual o documento divergiu.

{
  "userRef": "user-123",
  "prefill": {
    "documentType": "drivers_license",
    "issuingCountry": "USA",
    "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 uma regra consegue refutar — um dígito verificador que falha, ou um valor que nenhuma jurisdição poderia emitir — é rejeitado com 422 em vez de ser aceito e reprovado depois. Um número que apenas não corresponde a nenhuma das formas que mantemos para sua jurisdição não é recusado; ele é levado adiante, e o resultado publica document_number_valid como undetermined. 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 checagem document_data_match reprovada e é reportada no resultado.

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 errorCode: "validation_error"; errors[] nomeia o campo e a causa:

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 sessão de widget. Leia-o quando você precisar de uma garantia em vez de um push, para recuperar um webhook que você pode ter perdido, ou para ler o resultado de uma sessão que foi para revisão manual.

Uma verificação criada com POST /v1/verifications não é servida aqui — ela tem uma leitura própria em GET /v1/verifications/{verificationId}, acessível com o scope verifications. Passar uma delas aqui retorna 404.

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": "completed",
  "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",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

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

Expiração da Sessão

Uma sessão que o cliente não termina a tempo termina em expired. O prazo dela é fixado quando você a cria: as 48 horas do link mais a hora que um cliente que abriu o link no fim tem para terminar — 49 horas após a criação por padrão, devolvido como expiresAt na resposta de criação e na leitura. Uma mudança posterior na vida útil do link nunca move o prazo de uma sessão que já existe.

Tudo o que ainda não foi enviado expira: um link que nunca foi aberto, ou um cliente que parou no meio. Uma sessão expirada não carrega decision nem avaliação, e é entregue a você como qualquer outro desfecho — por webhook no modo webhook. Um cliente num link expirado vê a mensagem de link expirado em vez da sua redirectUrl, então no modo redirect ela chega até você como uma notificação de resultado quando você tem um webhookUrl, e pela leitura em qualquer caso. Depois que uma sessão termina, nenhuma captura adicional é aceita.

Verificações server-to-server não têm prazo e nunca expiram.

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
• Sandbox e Dados de Teste — números de documento reservados que ditam todo o resultado de uma verificação