API de risco de telefone: operadora e sinais de fraude

curl

curl -X POST https://verification.didit.me/v3/phone/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

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

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

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

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

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

import me.didit.Didit;
import me.didit.types.PhoneRiskRequest;

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

var result = client.phone().assessRisk(PhoneRiskRequest.builder()
        .phoneNumber("+14155552671")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->phone->assessRisk([
    'phone_number' => '+14155552671',
]);
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.AssessRiskAsync(new PhoneRiskRequest
{
    PhoneNumber = "+14155552671",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62",
  "status": "Approved",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "Example Mobile",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": null,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "phone_intelligence": {
      "score": 3,
      "phone_type_risk": "Low",
      "phone_trust_index": 97,
      "network_stability_index": 95,
      "is_disposable": false,
      "is_ported": false,
      "is_recently_ported": false,
      "carrier_type": "mobile",
      "reason_codes": []
    },
    "enrichment": {
      "score": 3,
      "phone_type_risk": "Low",
      "phone_trust_index": 97,
      "network_stability_index": 95,
      "is_disposable": false,
      "is_ported": false,
      "is_recently_ported": false,
      "carrier_type": "mobile",
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

POST

phone

risk

curl

curl -X POST https://verification.didit.me/v3/phone/risk/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+14155552671",
    "country_code": "US",
    "vendor_data": "lead-123",
    "metadata": {"source": "signup_prescreen"}
  }'

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

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

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

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

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

import me.didit.Didit;
import me.didit.types.PhoneRiskRequest;

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

var result = client.phone().assessRisk(PhoneRiskRequest.builder()
        .phoneNumber("+14155552671")
        .build());
System.out.println(result);

<?php

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->phone->assessRisk([
    'phone_number' => '+14155552671',
]);
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.AssessRiskAsync(new PhoneRiskRequest
{
    PhoneNumber = "+14155552671",
});
Console.WriteLine(JsonSerializer.Serialize(result));

{
  "request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62",
  "status": "Approved",
  "phone": {
    "status": "Approved",
    "phone_number_prefix": "+1",
    "phone_number": "4155552671",
    "full_number": "+14155552671",
    "country_code": "US",
    "country_name": "United States",
    "carrier": {
      "name": "Example Mobile",
      "type": "mobile"
    },
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": null,
    "verification_attempts": 0,
    "verified_at": null,
    "warnings": [],
    "lifecycle": [],
    "matches": [],
    "phone_intelligence": {
      "score": 3,
      "phone_type_risk": "Low",
      "phone_trust_index": 97,
      "network_stability_index": 95,
      "is_disposable": false,
      "is_ported": false,
      "is_recently_ported": false,
      "carrier_type": "mobile",
      "reason_codes": []
    },
    "enrichment": {
      "score": 3,
      "phone_type_risk": "Low",
      "phone_trust_index": 97,
      "network_stability_index": 95,
      "is_disposable": false,
      "is_ported": false,
      "is_recently_ported": false,
      "carrier_type": "mobile",
      "reason_codes": []
    }
  },
  "vendor_data": "lead-123",
  "metadata": {
    "source": "signup_prescreen"
  },
  "created_at": "2026-09-01T10:30:00.123456+00:00"
}

Use POST /v3/phone/risk/ quando precisar de informação sobre o telefone antes, em vez de, ou fora de um fluxo OTP. Não envia nenhum código ao utilizador. Cria uma sessão de API, enriquece o número, aplica as suas regras de risco de telefone e devolve, numa única resposta síncrona, o mesmo bloco de telefone normalizado usado pela Verificação de telefone. Quando o pedido é guardado, a Didit também pode usar o número de telefone ao qual foi atribuída uma pontuação como prova agregada em Networks. Os grafos de rede podem mostrar informação de risco elevado sobre o telefone, portabilidade e contexto do tipo de linha em sinais telefónicos partilhados, mas não revelam o número de telefone em bruto a outras organizações.

Interpretar a resposta

status é a decisão final para esta sessão de API. Normalmente é Approved; a avaliação de risco pode resultar em In Review ou Declined.
phone.full_number é o número E.164 normalizado. phone.phone_number_prefix e phone.phone_number separam-no no prefixo internacional e no número nacional.
phone.is_disposable e phone.is_virtual são os sinais estáveis de sim/não para a lógica da aplicação. A consulta à operadora acrescenta carrier.name e carrier.type (mobile, voip e semelhantes).
phone.phone_intelligence.score usa uma escala de risco de 0 a 100, em que um valor mais alto significa um risco maior. phone_type_risk (Low, Medium, High) e phone_trust_index (o inverso da pontuação) são vistas derivadas.
phone.phone_intelligence e phone.enrichment são aliases de compatibilidade com o mesmo objeto normalizado. As novas integrações podem ler phone.enrichment.
phone.matches lista outras sessões da sua aplicação em que o mesmo número foi usado por um utilizador diferente. Use-o para a deteção de contas duplicadas.
request_id é o ID da sessão de API. Guarde-o juntamente com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou com a atividade na consola.

phone.phone_intelligence e phone.enrichment são campos não garantidos. Uma consulta concluída pode omitir ambos quando não é devolvida nenhuma informação útil para esse número, país ou plano. Construa as regras primeiro sobre os campos normalizados estáveis e trate a informação em falta como “desconhecida”, e não como “segura”.

Defina enable_social como true para acrescentar um bloco phone_social à resposta, em phone: as plataformas online onde este número de telefone está registado, agrupadas por categoria, com os totais resumidos e quaisquer detalhes de perfil devolvidos pelos nossos parceiros de dados.

phone.phone_social.profiles_registered e phone.phone_social.profiles_checked são os números principais: as plataformas em que o número de telefone está confirmado como registado, do total de plataformas avaliadas.
phone.phone_social.registered_platforms e phone.phone_social.not_registered_platforms listam cada plataforma com a sua category e scope (global, ou local para plataformas específicas de uma região).
phone.phone_social.categories apresenta a contagem de registos e a proporção por categoria, e phone.phone_social.profiles contém os detalhes de perfil por plataforma quando uma plataforma os disponibiliza (nome, URL da fotografia, texto “sobre”, estado de privacidade, indicador de conta empresarial).
Os índices de resumo (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) são índices compostos numa escala de 0 a 10. Qualquer contagem pode ser null quando a verificação não devolveu dados para essa contagem.

profiles_registered: 0 é uma resposta real, não uma falha: as plataformas foram verificadas e o número de telefone não foi encontrado em nenhuma delas, o que é um sinal comum de identidade sintética. Este endpoint não atua sozinho com base nisto; use phone_no_social_presence_action num fluxo para o transformar num veredicto Review ou Decline. O bloco está ausente quando enable_social não está definido, e também quando a verificação social não pôde ser concluída, caso em que não é faturada.

Ambiente sandbox

As chaves do sandbox validam o pedido e devolvem dados aprovados e determinísticos. Não enviam nenhum OTP, não consomem créditos, não criam uma sessão e não contribuem para Networks. Com enable_social definido, devolvem também um bloco phone_social determinístico.

Faturação

As chamadas à Phone Risk API custam $0.04 ao preço de lista, menos do que a Verificação de telefone completa, porque não é enviado nenhum OTP. Um pedido em produção é faturável assim que a consulta é iniciada, mesmo quando alguns campos não garantidos não estão disponíveis. O complemento de pegada social é faturado à parte: uma unidade phone_social por pedido, para além do preço da Phone Risk API, sempre que a verificação é concluída. A verificação de créditos feita antes da consulta cobre ambos.

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

Número de telefone ao qual atribuir pontuação. É validado e normalizado para E.164.

Maximum string length: 20

Exemplo:

"+14155552671"

country_code

string

Sugestão opcional de país ISO 3166-1 alpha-2 ou alpha-3 para cobertura de inteligência.

Maximum string length: 3

Exemplo:

"US"

signals

object

Contexto opcional de dispositivo e rede observado pela sua aplicação. Todos os campos são opcionais. Passá-los alimenta a deteção de correspondências entre sessões em Redes.

Show child attributes

vendor_data

string

A sua referência estável para este pedido. Armazenada na sessão da API e refletida na resposta.

metadata

object | null

Os seus metadados JSON não sensíveis. Armazenados na sessão da API e devolvidos na resposta.

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

Resposta

A avaliação de risco foi concluída. Inspecione status para verificar a decisão; o código HTTP é sempre 200 para pesquisas concluídas.

request_id

string<uuid>

obrigatório

ID da sessão de API criada para este pedido. Guarde-o com vendor_data se precisar de correlacionar o resultado com webhooks posteriores ou atividade na consola.

status

enum<string>

obrigatório

Decisão final para esta sessão de API. Normalmente Approved; a avaliação de risco pode produzir In Review ou Declined.

Opções disponíveis:

Approved,

In Review,

Declined

created_at

string<date-time>

obrigatório

Carimbo de data/hora desta resposta.

vendor_data

string | null

Eco do vendor_data que enviou, null se não tiver enviado nenhum.

metadata

object | null

Eco do objeto metadata que enviou, null se não tiver enviado nenhum.

phone

object

Relatório de telefone normalizado, o mesmo bloco utilizado pelas respostas da Verificação de telefone.

Show child attributes

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

​Interpretar a resposta

​Complemento de pegada social

​Ambiente sandbox

​Faturação

Autorizações

Corpo

Resposta

Interpretar a resposta

Complemento de pegada social

Ambiente sandbox

Faturação