Sessões de Verificação

Uma sessão representa uma verificação de identidade. Criá-la retorna uma widget_url que você entrega ao seu cliente e um session_id 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 '{
  "user_ref": "user-123",
  "language": "es",
  "delivery": { "mode": "webhook" }
}'

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widget_url": "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.

{
  "user_ref": "user-123",
  "prefill": {
    "document_type": "drivers_license",
    "issuing_state": "PA",
    "document_number": "31612967",
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

Campos de prefill diferentes de document_type não alteram a decisão a menos que você defina data_check: 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.document_number é 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 data_check: true para verificar que o documento pertence à pessoa que você esperava — não apenas que o documento é genuíno.

{
  "user_ref": "user-123",
  "data_check": true,
  "prefill": {
    "first_name": "Ana",
    "last_name": "Silva",
    "date_of_birth": "1988-03-04"
  }
}

Com data_check: true:

• Os dados extraídos são comparados campo a campo com o payload de prefill.
• O resultado carrega prefill_comparison (resultados por campo, incluindo pontuações de correspondência aproximada de nomes) e prefill_mismatches (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. data_check: true sem um payload de prefill é um 422 — não haveria nada com que comparar.

Entrega

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

Solicitar o modo webhook sem uma webhook_url 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/{session_id}
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"

{
  "session_id": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "user_ref": "user-123",
  "status": "in_review",
  "step": "done",
  "delivery_mode": "webhook",
  "result": { "…": "the normalized result, updated in place" },
  "created_at": "2026-07-31T14:02:11.481Z",
  "updated_at": "2026-07-31T14:04:57.902Z"
}

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

Validar um Número de Documento

Endpoint: POST /v1/validators/document-number
Autenticação: nenhuma necessária

Uma verificação de formato sem estado (stateless) contra o mesmo registro que o pipeline de verificação usa: formatos de carteira de motorista dos EUA para todos os 50 estados e DC, formatos de passaporte por país e formatos de carteira de identidade onde a jurisdição define um. Nada é armazenado e nenhuma verificação é consumida. Útil para validar a entrada no seu próprio formulário antes de criar uma sessão.

curl --request POST \
  --url https://{FQDN}/v1/validators/document-number \
  --header 'Content-Type: application/json' \
  --data '{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA"
}'

{
  "document_type": "drivers_license",
  "number": "31612967",
  "issuing_state": "PA",
  "valid": true,
  "rule": "us_dl:PA",
  "detail": "document number matches the PA license format"
}

valid é deliberadamente trivalorado:

rule identifica qual regra foi aplicada — us_dl:PA, passport:USA, passport:generic, ou us_dl:unknown_state quando uma carteira de motorista foi enviada sem um estado resolvível (o que resulta em valid: null). issuing_state é um código ou nome de estado dos EUA para carteiras de motorista, e um código de país ISO 3166-1 alpha-3 para passaportes e carteiras de identidade.

Próximos Passos

• Entrega do Widget — conduzindo o cliente pelo fluxo
• Recebendo Resultados — tratamento de webhook e redirect
• Configuração do Tenant — quais tipos de documento e jurisdições você aceita