Criar validação de posse de telefone por código no WhatsApp

curl --request POST \
  --url https://api.id.zapsign.com.br/v1/validations/phone-ownership \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+5511999998888",
  "consent": true
}
'

{
  "object": "validation",
  "id": "val_2W7HJ9RC4XKQ0ZB58NDT3PMFY6",
  "type": "phone_ownership",
  "status": "pending",
  "result": null,
  "reason_code": null,
  "external_id": "pedido_12345",
  "created_at": "2026-08-07T14:00:00Z",
  "resolved_at": null,
  "validation_url": null,
  "expires_at": "2026-08-07T14:10:00Z",
  "attempts_remaining": 3,
  "details": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_param",
    "message": "A required parameter is missing.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_api_key",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "payment_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance for this validation.",
    "doc_url": "https://docs.id.zapsign.com.br/insufficient_balance",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_progress",
    "message": "A request with the same Idempotency-Key is still in progress.",
    "doc_url": "https://docs.id.zapsign.com.br/idempotency_in_progress",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "request_too_large",
    "message": "The request body is too large.",
    "doc_url": "https://docs.id.zapsign.com.br/request_too_large",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cpf",
    "message": "The value provided is invalid.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_cpf",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the indicated delay.",
    "doc_url": "https://docs.id.zapsign.com.br/rate_limit_exceeded",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An internal error occurred.",
    "doc_url": "https://docs.id.zapsign.com.br/api_error",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

POST

validations

phone-ownership

curl --request POST \
  --url https://api.id.zapsign.com.br/v1/validations/phone-ownership \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "phone": "+5511999998888",
  "consent": true
}
'

{
  "object": "validation",
  "id": "val_2W7HJ9RC4XKQ0ZB58NDT3PMFY6",
  "type": "phone_ownership",
  "status": "pending",
  "result": null,
  "reason_code": null,
  "external_id": "pedido_12345",
  "created_at": "2026-08-07T14:00:00Z",
  "resolved_at": null,
  "validation_url": null,
  "expires_at": "2026-08-07T14:10:00Z",
  "attempts_remaining": 3,
  "details": null
}

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_param",
    "message": "A required parameter is missing.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_api_key",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "payment_error",
    "code": "insufficient_balance",
    "message": "Insufficient balance for this validation.",
    "doc_url": "https://docs.id.zapsign.com.br/insufficient_balance",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_in_progress",
    "message": "A request with the same Idempotency-Key is still in progress.",
    "doc_url": "https://docs.id.zapsign.com.br/idempotency_in_progress",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "request_too_large",
    "message": "The request body is too large.",
    "doc_url": "https://docs.id.zapsign.com.br/request_too_large",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "invalid_request",
    "code": "invalid_cpf",
    "message": "The value provided is invalid.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/invalid_cpf",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after the indicated delay.",
    "doc_url": "https://docs.id.zapsign.com.br/rate_limit_exceeded",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An internal error occurred.",
    "doc_url": "https://docs.id.zapsign.com.br/api_error",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

Ciclo de dois momentos

Você cria a validação

O código sai por WhatsApp para o telefone informado.

A pessoa devolve o código

Colete na sua interface o código que chegou.

Você confirma o código

Chame POST /validations/{id}/verify com o id desta resposta.

Prazo e tentativas

O código vale 10 minutos e a pessoa tem 3 tentativas. Um dígito errado gasta uma tentativa, não a validação inteira. Passado o prazo, a validação vira expired. Não fixe o tamanho do código na sua interface: o número de dígitos é política do provedor.

Número fora de alcance

Um celular brasileiro válido nem sempre consegue receber o código pelo WhatsApp, e aí a resposta é 422 phone_not_reachable.

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

Body

application/json

Dados para criar uma validação de posse de telefone.

phone

string

required

Telefone celular brasileiro que recebe o código, em formato E.164.

Example:

"+5511999998888"

Confirma que o titular consentiu com a consulta. Precisa ser true.

external_id

string

Sua referência de correlação. Volta em todas as respostas desta validação.

Required string length: 1 - 256

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

Example:

"pedido_12345"

Response

Código enviado e validação criada em estado pending.

Resultado de uma validação.

object

enum<string>

required

Sempre validation.

Available options:

validation

string

required

Identificador único da validação.

Example:

"val_0NQW3MVYJYQ453E95V3V1T76AV"

type

enum<string>

required

Tipo da validação.

Valor	O que é
`cpf_phone_match`	Vínculo entre CPF e telefone
`sim_swap`	Troca de chip
`liveness_document_match`	Prova de vida + documento
`phone_ownership`	Posse do telefone, por código no WhatsApp
`liveness_cpf_match`	Prova de vida + CPF
`telco_financial_capacity`	Capacidade financeira via operadora

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.

Valor	O que é
`pending`	Criada, aguardando o titular concluir o fluxo hospedado ou devolver o código
`completed`	Resolvida; veja `result`
`failed`	Não foi possível concluir
`expired`	O prazo venceu sem conclusão

Available options:

pending,

completed,

failed,

expired

result

enum<string> | null

required

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

Valor	Aparece em
`match` / `no_match`	`cpf_phone_match`
`recent_swap` / `no_recent_swap`	`sim_swap`
`passed` / `not_passed`	`liveness_document_match`, `liveness_cpf_match`, `phone_ownership`
`high_capacity` / `moderate_capacity` / `low_capacity`	`telco_financial_capacity`
`unknown`	Qualquer tipo, quando a fonte não deu uma resposta conclusiva. O motivo vem em `reason_code`.

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.

Valor	O que é
`liveness_failed`	Prova de vida não confirmada
`face_mismatch`	O rosto não corresponde ao documento
`spoof_detected`	Suspeita de fraude na captura
`document_tampered`	Indícios de adulteração no documento
`document_invalid`	Documento inválido ou não aceito
`document_unreadable`	O documento não pôde ser lido
`cpf_reference_not_found`	CPF não encontrado na base de referência
`data_unavailable`	Dados indisponíveis na fonte consultada
`phone_not_covered`	Telefone sem cobertura para a consulta
`invalid_code`	O código enviado não confere, e as tentativas acabaram

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.

Show child attributes

Referência da API

Validações

Chaves de API

Criar validação de posse de telefone por código no WhatsApp

Ciclo de dois momentos

Prazo e tentativas

Número fora de alcance

Authorizations

Headers

Body

Response

​Ciclo de dois momentos

​Prazo e tentativas

​Número fora de alcance

Authorizations

Headers

Body

Response

Ciclo de dois momentos

Prazo e tentativas

Número fora de alcance