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 você precisar de inteligência telefônica antes de um fluxo de OTP, no lugar dele ou fora dele. Esse endpoint não envia código ao usuário. Ele cria uma sessão de API, enriquece os dados do número, aplica suas regras de risco telefônico e retorna, em uma única resposta síncrona, o mesmo bloco de telefone normalizado usado pela Verificação de telefone. Quando a requisição é salva, a Didit também pode usar o número de número de telefone avaliado como evidência agregada em Networks. Os grafos de rede podem mostrar inteligência telefônica de alto risco, portabilidade e contexto do tipo de linha em sinais telefônicos compartilhados, mas não revelam o número de telefone bruto a outras organizações.

Interpretar a resposta

status é a decisão final dessa sessão de API. Normalmente é Approved; a avaliação de risco pode resultar em In Review ou Declined.
phone.full_number é o número normalizado no formato E.164. phone.phone_number_prefix e phone.phone_number o dividem em prefixo internacional e 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 similares).
phone.phone_intelligence.score usa uma escala de risco de 0 a 100, em que um número maior indica risco maior. phone_type_risk (Low, Medium, High) e phone_trust_index (o inverso da pontuação) são representações derivadas.
phone.phone_intelligence e phone.enrichment são aliases de compatibilidade com o mesmo objeto normalizado. 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 outro usuário. Use esse campo para detectar contas duplicadas.
request_id é o ID da sessão de API. Armazene-o com vendor_data se precisar correlacionar o resultado com webhooks posteriores ou com a atividade no console.

phone.phone_intelligence e phone.enrichment são campos sujeitos à disponibilidade de dados. Uma consulta concluída pode omitir ambos quando nenhum dado de inteligência utilizável é retornado para aquele número, país ou plano. Construa suas regras primeiro sobre os campos normalizados estáveis e trate a ausência de inteligência como “desconhecido”, não como “seguro”.

Defina enable_social como true para adicionar um bloco phone_social à resposta, dentro de phone: as plataformas online em que esse número de telefone está registrado, agrupadas por categoria, com as contagens resumidas e todos os detalhes de perfil que nossos parceiros de dados retornarem.

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 tem registro confirmado, do total de plataformas avaliadas.
phone.phone_social.registered_platforms e phone.phone_social.not_registered_platforms listam cada plataforma com sua category e seu scope (global, ou local para plataformas específicas de uma região).
phone.phone_social.categories informa a contagem de registros e a proporção por categoria, e phone.phone_social.profiles traz detalhes de perfil por plataforma quando a plataforma os expõe (nome, URL da foto, texto de apresentação, status de privacidade, indicador de conta comercial).
Os índices resumidos (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) são indicadores compostos de 0 a 10. Qualquer contagem pode ser null quando a verificação não retornou dados para ela.

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. Esse endpoint não age sobre isso por conta própria. Use phone_no_social_presence_action em um fluxo de verificação (workflow) para transformar esse resultado em um veredito Review ou Decline. O bloco não aparece quando enable_social não está definido e também quando a verificação social não pôde ser concluída. Nesse caso, ela não é cobrada.

Comportamento no sandbox

As chaves de sandbox validam a requisição e retornam dados aprovados predeterminados. Elas não enviam OTP, não consomem créditos, não criam sessão e não contribuem para Networks. Com enable_social definido, também retornam um bloco phone_social determinístico.

Faturamento

As chamadas à Phone Risk API custam $0.04 ao preço de tabela, menos do que a Verificação de telefone completa, porque nenhum OTP é enviado. Uma requisição no ambiente de produção é cobrada assim que a consulta começa, mesmo quando alguns campos fornecidos conforme disponibilidade não são retornados. O complemento de presença social é cobrado separadamente: uma unidade phone_social por requisição, 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 os dois.

Autorizações

x-api-key

string

header

obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, 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á errada, 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 a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

application/json

phone_number

string

obrigatório

Número de telefone a ser pontuado. Ele é validado e normalizado para E.164.

Maximum string length: 20

Exemplo:

"+14155552671"

country_code

string

Indicação opcional de país em ISO 3166-1 alfa-2 ou alfa-3 para a 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. Enviá-los alimenta a detecção de correspondências entre sessões em Networks.

Show child attributes

vendor_data

string

Sua referência estável para esta requisição. Armazenada na sessão da API e devolvida na resposta.

metadata

object | null

Seus metadados JSON não sensíveis. Armazenados na sessão da API e retornados na resposta.

Quando verdadeiro, também consulta a presença digital do número: as plataformas de mensagens, redes sociais, e-commerce e profissionais em que ele está cadastrado. Cobrado como uma unidade phone_social por requisição, além do preço deste endpoint.

Exemplo:

true

Resposta

A avaliação de risco foi concluída. Verifique status para ver a decisão; o HTTP é sempre 200 para consultas concluídas.

request_id

string<uuid>

obrigatório

Id da sessão de API criada para esta requisição. Armazene-o com vendor_data se precisar correlacionar o resultado com webhooks posteriores ou com a atividade no console.

status

enum<string>

obrigatório

Decisão final desta sessão de API. Normalmente Approved; a avaliação de risco pode resultar em In Review ou Declined.

Opções disponíveis:

Approved,

In Review,

Declined

created_at

string<date-time>

obrigatório

Data e hora desta resposta.

vendor_data

string | null

Eco do vendor_data que você enviou, null quando você não enviou nenhum.

metadata

object | null

Eco do metadata que você enviou, null quando você não enviou nenhum.

phone

object

Relatório de telefone normalizado, o mesmo bloco usado nas respostas de Verificação de telefone.

Show child attributes

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

​Interpretar a resposta

​Complemento de presença social

​Comportamento no sandbox

​Faturamento

Autorizações

Corpo

Resposta

Interpretar a resposta

Complemento de presença social

Comportamento no sandbox

Faturamento