API de riesgo telefónico: operador y señales 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"
}

Usa POST /v3/phone/risk/ cuando necesites inteligencia telefónica antes de un flujo de OTP, en su lugar o fuera de él. No envía ningún código al usuario. Crea una sesión de API, enriquece el número, aplica tus reglas de riesgo telefónico y devuelve, en una única respuesta síncrona, el mismo bloque de teléfono normalizado que usa la Phone Verification. Cuando la solicitud se guarda, Didit también puede usar el número de teléfono evaluado como evidencia agregada en Networks. Los grafos de red pueden mostrar inteligencia telefónica de alto riesgo y contexto de portabilidad y tipo de línea en las señales telefónicas compartidas, pero no revelan el número de teléfono sin procesar a otras organizaciones.

Interpretar la respuesta

status es la decisión final de esta sesión de API. Normalmente es Approved; la evaluación de riesgo puede dar como resultado In Review o Declined.
phone.full_number es el número normalizado en formato E.164. phone.phone_number_prefix y phone.phone_number lo dividen en el prefijo internacional y el número nacional.
phone.is_disposable y phone.is_virtual son las señales estables de sí/no para la lógica de tu aplicación. La consulta del operador añade carrier.name y carrier.type (mobile, voip y similares).
phone.phone_intelligence.score usa una escala de riesgo de 0 a 100 en la que un número más alto significa mayor riesgo. phone_type_risk (Low, Medium, High) y phone_trust_index (el inverso de la puntuación) son vistas derivadas.
phone.phone_intelligence y phone.enrichment son alias de compatibilidad con el mismo objeto normalizado. Las nuevas integraciones pueden leer phone.enrichment.
phone.matches enumera otras sesiones de tu aplicación en las que un usuario distinto usó el mismo número. Úsalo para detectar cuentas duplicadas.
request_id es el id de la sesión de API. Guárdalo junto con vendor_data si necesitas correlacionar el resultado con webhooks posteriores o con la actividad en la consola.

phone.phone_intelligence y phone.enrichment son campos proporcionados en la medida de lo posible. Una consulta completada puede omitir ambos cuando no se devuelven datos de inteligencia utilizables para ese número, país o plan. Basa primero tus reglas en los campos normalizados estables y trata la ausencia de inteligencia como “desconocido”, no como “seguro”.

Establece enable_social en true para añadir un bloque phone_social a la respuesta dentro de phone: las plataformas en línea en las que está registrado este número de teléfono, agrupadas por categoría, con los recuentos resumidos y los detalles de perfil que devuelvan nuestros socios de datos.

phone.phone_social.profiles_registered y phone.phone_social.profiles_checked son las cifras principales: las plataformas en las que se ha confirmado que el número de teléfono está registrado, del total de plataformas evaluadas.
phone.phone_social.registered_platforms y phone.phone_social.not_registered_platforms enumeran cada plataforma con su category y su scope (global, o local para plataformas específicas de una región).
phone.phone_social.categories ofrece el recuento de registros y la proporción por categoría, y phone.phone_social.profiles incluye los detalles de perfil por plataforma cuando la plataforma los expone (nombre, URL de la foto, texto de presentación, estado de privacidad e indicador de cuenta de empresa).
Los índices resumidos (digital_footprint_diversity, digital_sophistication_index, engagement_depth_index, subscription_affordability_index) son indicadores compuestos de 0 a 10. Cualquier recuento puede ser null cuando la comprobación no devolvió datos para él.

profiles_registered: 0 es una respuesta real, no un fallo: las plataformas se comprobaron y el número de teléfono no se encontró en ninguna, lo que es una señal habitual de identidad sintética. Este endpoint no toma ninguna medida por sí solo: usa phone_no_social_presence_action en un flujo de verificación (workflow) para convertirlo en un veredicto de revisión o de rechazo. El bloque no aparece cuando enable_social no está establecido, ni tampoco cuando la comprobación social no pudo completarse, en cuyo caso no se factura.

Comportamiento en sandbox

Las claves de sandbox validan la solicitud y devuelven datos deterministas aprobados. No envían ningún OTP, no consumen créditos, no crean una sesión ni contribuyen a Networks. Con enable_social activado, también devuelven un bloque phone_social determinista.

Facturación

Las llamadas a la Phone Risk API cuestan $0.04 según el precio de lista, menos que la Verificación de teléfono completa porque no se envía ningún OTP. Una solicitud en producción es facturable en cuanto empieza la consulta, aunque algunos campos de disponibilidad no garantizada no estén disponibles. El complemento de huella social se factura por separado: una unidad de phone_social por solicitud, además del precio de la Phone Risk API, siempre que la comprobación se complete. La verificación de créditos previa a la consulta cubre ambos.

Autorizaciones

x-api-key

string

header

requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

application/json

phone_number

string

requerido

Número de teléfono que se va a puntuar. Se valida y se normaliza a E.164.

Maximum string length: 20

Ejemplo:

"+14155552671"

country_code

string

Indicación de país ISO 3166-1 alfa-2 o alfa-3 opcional para la cobertura de inteligencia.

Maximum string length: 3

Ejemplo:

"US"

signals

object

Contexto opcional de dispositivo y red observado por tu aplicación. Todos los campos son opcionales. Enviarlos alimenta la detección de coincidencias entre sesiones en Networks.

Show child attributes

vendor_data

string

Tu referencia estable para esta solicitud. Se guarda en la sesión de API y se devuelve en la respuesta.

metadata

object | null

Tus metadatos JSON no sensibles. Se almacenan en la sesión de API y se devuelven en la respuesta.

Si es true, también se consulta la huella social del número: las plataformas de mensajería, redes sociales, comercio electrónico y profesionales en las que está registrado. Se factura como una unidad phone_social por solicitud, además del precio propio de este endpoint.

Ejemplo:

true

Respuesta

La evaluación de riesgo se completó. Consulta status para ver la decisión; el código HTTP siempre es 200 en las consultas completadas.

request_id

string<uuid>

requerido

ID de la sesión de API creada para esta solicitud. Guárdalo junto con vendor_data si necesitas relacionar el resultado con webhooks posteriores o con la actividad en la consola.

status

enum<string>

requerido

Decisión final de esta sesión de API. Normalmente es Approved; la evaluación de riesgo puede producir In Review o Declined.

Opciones disponibles:

Approved,

In Review,

Declined

created_at

string<date-time>

requerido

Marca de tiempo de esta respuesta.

vendor_data

string | null

Devuelve el vendor_data que enviaste, o null si no enviaste ninguno.

metadata

object | null

Devuelve el metadata que enviaste, o null si no enviaste ninguno.

phone

object

Informe de teléfono normalizado, el mismo bloque que usan las respuestas de Verificación de teléfono.

Show child attributes

Última modificación el 1 de noviembre de 2026

​Interpretar la respuesta

​Complemento de huella social

​Comportamiento en sandbox

​Facturación

Autorizaciones

Cuerpo

Respuesta

Interpretar la respuesta

Complemento de huella social

Comportamiento en sandbox

Facturación