API de verificação de telefone: validar código SMS

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{
	PhoneNumber: "+14155552671",
	Code:        "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

POST

phone

check

curl

curl -X POST https://verification.didit.me/v3/phone/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "code": "123456",
    "voip_number_action": "DECLINE"
  }'

import Didit from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.phone.checkCode({
  phone_number: "+14155552671",
  code: "123456",
});
console.log(result);

ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{
	PhoneNumber: "+14155552671",
	Code:        "123456",
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)

import me.didit.Didit;
import me.didit.types.PhoneCheckCodeParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.phone().checkCode(PhoneCheckCodeParams.builder()
        .phoneNumber("+14155552671")
        .code("123456")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->phone->checkCode([
    'phone_number' => '+14155552671',
    'code' => '123456',
]);
print_r($result->toArray());

using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams
{
    PhoneNumber = "+14155552671",
    Code = "123456",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "AT&T",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "whatsapp",
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "PHONE_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null,
          "channel": "whatsapp",
          "actual_channel": "whatsapp"
        },
        "fee": 0.0509
      },
      {
        "type": "PHONE_DELIVERY_DELIVERED",
        "timestamp": "2026-06-12T01:23:43.118220+00:00",
        "details": {
          "channel": "whatsapp",
          "status": "delivered"
        },
        "fee": 0
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "PHONE_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

Lidar com interrupções do fornecedor

Se o fornecedor de telefonia estiver temporariamente indisponível, este endpoint devolve 502 com um código estável legível por máquina:

{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}

Trate esta resposta como passível de nova tentativa. Use um intervalo de espera progressivo curto e mostre ao utilizador uma mensagem de indisponibilidade temporária do serviço, em vez de lhe pedir que altere um número de telefone ou um código válidos.

Complemento de inteligência

Defina enable_enrichment como true para executar também a inteligência telefónica sobre o número: uma pontuação de risco, o tipo de linha, se o número foi portado recentemente e um índice de confiança. O complemento é faturado a $0.05 por pedido ao preço de tabela, além do preço da verificação. O pedido devolve 403 quando o seu saldo não cobre esse valor. Quatro campos determinam o efeito dos sinais. Cada um pode ser NO_ACTION (o valor predefinido) ou DECLINE, e cada um só tem efeito quando enable_enrichment é true.

Campo	Recusa quando
`phone_intelligence_score_action`	A pontuação de risco está acima do limiar.
`phone_type_risk_action`	O número é de um tipo de linha de alto risco.
`recent_port_action`	O número foi portado para outra operadora recentemente.
`low_phone_trust_action`	O índice de confiança é igual ou inferior ao limiar.

Com NO_ACTION, o sinal continua a ser devolvido em phone.phone_intelligence, para que possa aplicar a sua própria regra.

Autorizações

x-api-key

string

header

obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

phone_number

string

obrigatório

O mesmo número de telefone utilizado na chamada POST /v3/phone/send/ correspondente, no formato E.164. É isto que associa a verificação ao envio.

Maximum string length: 20

Exemplo:

"+14155552671"

code

string

obrigatório

O OTP que o utilizador final recebeu. Deve ter entre 4 e 8 dígitos numéricos — qualquer outro valor devolve 400 sem consumir uma tentativa. Um código bem formatado mas incorreto devolve 200 com status: "Failed" e consome uma das 3 tentativas.

Required string length: 4 - 8

Pattern: ^[0-9]{4,8}$

Exemplo:

"123456"

duplicated_phone_number_action

enum<string>

padrão:NO_ACTION

O que fazer quando o mesmo número já foi utilizado por um utilizador diferente (com um vendor_data diferente) da sua aplicação. DECLINE altera o status final para Declined; NO_ACTION regista o risco em phone.warnings e preenche phone.matches.

Opções disponíveis:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

padrão:NO_ACTION

O que fazer quando a consulta de operadora sinalizar o número como uma linha temporária/descartável (phone.is_disposable). DECLINE altera o status final para Declined; NO_ACTION regista o risco em phone.warnings.

Opções disponíveis:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

padrão:NO_ACTION

O que fazer quando a consulta de operadora indicar um tipo de linha virtual — voip, isp ou vpn (phone.is_virtual). DECLINE altera o status final para Declined; NO_ACTION regista o risco em phone.warnings.

Opções disponíveis:

NO_ACTION,

DECLINE

enable_enrichment

boolean

padrão:false

Quando true, executa também inteligência telefónica sobre o número: uma pontuação de risco, o tipo de linha, se foi recentemente portado e um índice de confiança. Faturado como uma unidade phone_intelligence_api por pedido ($0.05 ao preço de tabela), além do próprio preço deste endpoint. O pedido devolve 403 quando o seu saldo não for suficiente para cobri-lo.

Exemplo:

false

phone_intelligence_score_action

enum<string>

padrão:NO_ACTION

Ação quando a pontuação de risco da inteligência de telefone está acima do limiar. DECLINE altera o status final para Declined; NO_ACTION regista o sinal sem recusar. Apenas tem efeito quando enable_enrichment é true.

Opções disponíveis:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

padrão:NO_ACTION

Ação quando o número é de um tipo de linha de alto risco. DECLINE altera o status final para Declined; NO_ACTION regista o sinal sem recusar. Apenas tem efeito quando enable_enrichment é true.

Opções disponíveis:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

padrão:NO_ACTION

Ação quando o número foi recentemente portado para outra operadora. DECLINE altera o status final para Declined; NO_ACTION regista o sinal sem recusar. Apenas tem efeito quando enable_enrichment é true.

Opções disponíveis:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

padrão:NO_ACTION

Ação quando o índice de confiança da inteligência de telefone está no limiar ou abaixo dele. DECLINE altera o status final para Declined; NO_ACTION regista o sinal sem recusar. Apenas tem efeito quando enable_enrichment é true.

Opções disponíveis:

NO_ACTION,

DECLINE

Quando for true, consulta também a pegada social do número: as plataformas de mensagens, redes sociais, de comércio eletrónico e profissionais nas quais está registado. Faturado como uma unidade phone_social por pedido, além do preço do próprio endpoint.

Exemplo:

true

Ação quando a verificação da pegada social deteta que o número não está registado em nenhuma das plataformas abrangidas. Apenas NO_ACTION e DECLINE são aceites neste endpoint; REVIEW está disponível na chave de configuração do fluxo com o mesmo nome.

Opções disponíveis:

NO_ACTION,

DECLINE

Resposta

Verificação concluída — códigos errados e verificações em falta também devolvem 200; inspecione status, não o código HTTP. phone é preenchido apenas em resultados finalizados (Approved/Declined), null em Failed e ausente em Expired or Not Found.

request_id

string<uuid>

Em Approved/Declined: o id da sessão da verificação correspondente — idêntico ao request_id devolvido por POST /v3/phone/send/. Em Failed e Expired or Not Found: um UUID pontual aleatório que não pode ser consultado mais tarde.

status

enum<string>

Approved — código correto, sem risco de recusa. Declined — terminal: um risco de recusa correspondeu ou o limite de tentativas (3) esgotou-se. Failed — código incorreto, tentativas restantes. Expired or Not Found — nenhuma verificação pendente para este número nos últimos 5 minutos.

Opções disponíveis:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Explicação legível do resultado, incluindo o número de tentativas restantes após um código incorreto.

phone

object | null

Relatório telefónico completo. Presente (não nulo) apenas em resultados finalizados (Approved/Declined); null em Failed e ausente em Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data da sessão da verificação correspondente. null em Expired or Not Found.

metadata

object | null

metadata da sessão da verificação correspondente. null em Expired or Not Found.

created_at

string<date-time>

Carimbo de data/hora desta resposta de verificação.

Última modificação em 7 de novembro de 2026

​Lidar com interrupções do fornecedor

​Complemento de inteligência

Autorizações

Corpo

Resposta

Lidar com interrupções do fornecedor

Complemento de inteligência