Skip to main content
POST
Confirma o código que a pessoa recebeu.

O código que a pessoa digitou

Quando você criou a validação em posse de telefone por WhatsApp, a pessoa recebeu um código no WhatsApp. Peça esse código na sua tela e mande aqui o que ela digitou, com o id daquela validação no path. Ela tem 3 tentativas e 10 minutos. Toda resposta traz attempts_remaining e expires_at, então leia esses campos em vez de contar do seu lado. Só validações de posse de telefone se confirmam por código. Qualquer outro tipo responde 422 validation_not_verifiable.

Como ler o desfecho

Um código errado também responde 200. O que aconteceu está no corpo: Sobre uma validação já resolvida, a resposta repete o estado atual.

O que não gasta tentativa

Um code que não seja só dígitos é recusado antes de chegar ao provedor, com 400 invalid_param_value. Um erro de digitação não custa uma tentativa da pessoa. Um 500 é erro nosso, não resposta da pessoa. Repita a chamada com o mesmo Idempotency-Key e o mesmo código.

Authorizations

Authorization
string
header
required

Sua chave de API no cabeçalho Authorization: Bearer sk_.... Crie e revogue chaves no painel ou pelos endpoints de Chaves de API.

Headers

Idempotency-Key
string

Torna a operação segura para retentativa. Reenviar a mesma chave repete a resposta original em vez de executar a operação de novo.

Required string length: 1 - 256
Pattern: ^[A-Za-z0-9_-]{1,256}$

Path Parameters

id
string
required

Identificador da validação.

Body

application/json

Código que a pessoa recebeu, para confirmar uma validação.

code
string
required

Código recebido, apenas dígitos.

Pattern: ^[0-9]+$
Example:

"483920"

Response

Recurso da validação depois da tentativa, em qualquer desfecho.

Resultado de uma validação.

object
enum<string>
required

Sempre validation.

Available options:
validation
id
string
required

Identificador único da validação.

Example:

"val_0NQW3MVYJYQ453E95V3V1T76AV"

type
enum<string>
required

Tipo da validação.

Os quatro primeiros têm endpoint de criação. Os outros dois podem aparecer em consultas e listagens de contas que os usam por outros canais.

Available options:
liveness_document_match,
liveness_cpf_match,
cpf_phone_match,
sim_swap,
telco_financial_capacity,
phone_ownership
status
enum<string>
required

Estado atual.

Available options:
pending,
completed,
failed,
expired
result
enum<string> | null
required

Resultado de negócio. É null enquanto status for pending.

Available options:
passed,
not_passed,
match,
no_match,
recent_swap,
no_recent_swap,
high_capacity,
moderate_capacity,
low_capacity,
unknown
reason_code
enum<string> | null
required

Por que o resultado foi o que foi. É null quando o resultado não precisa de explicação. Acompanha unknown na maioria dos casos, e também not_passed quando a validação foi recusada por um motivo específico.

Available options:
liveness_failed,
face_mismatch,
spoof_detected,
document_tampered,
document_invalid,
document_unreadable,
cpf_reference_not_found,
data_unavailable,
phone_not_covered,
invalid_code
external_id
string | null
required

A referência de correlação que você enviou na criação.

created_at
string<date-time>
required

Data de criação em ISO-8601.

resolved_at
string<date-time> | null
required

Data de resolução em ISO-8601. É null enquanto não resolvida.

validation_url
string | null
required

URL para onde redirecionar o titular. Preenchida nas validações hospedadas; null nas síncronas.

expires_at
string<date-time> | null
required

Quando a validação vence, em ISO-8601. Preenchida nas validações hospedadas e nas que enviam um código; null nas síncronas.

attempts_remaining
integer | null
required

Quantas chamadas de verificação ainda serão aceitas. Preenchida nos tipos que enviam um código para a pessoa devolver (hoje só phone_ownership) e null nos demais.

Vale 0 assim que a validação é resolvida, em qualquer desfecho, porque nenhuma outra tentativa será aceita.

details
object | null
required

Dados extraídos, agrupados pela chave do type. Hoje só liveness_document_match produz detalhes, e só com status igual a completed. Nos demais casos é null.