API para verificar OTP por teléfono: 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"
}

Gestionar caídas del proveedor

Si el proveedor de telefonía no está disponible temporalmente, este endpoint devuelve 502 con un código estable y legible por máquinas:

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

Considera que se puede reintentar esta respuesta. Usa un backoff corto y muestra al usuario un mensaje de servicio temporalmente no disponible en lugar de pedirle que cambie un número de teléfono o un código válidos.

Complemento de inteligencia

Establece enable_enrichment en true para ejecutar también la inteligencia telefónica del número: una puntuación de riesgo, el tipo de línea, si el número se portó recientemente y un índice de confianza. El complemento se factura a $0.05 por solicitud a precio de lista, además del precio de la verificación. La solicitud devuelve 403 cuando tu saldo no alcanza para cubrirlo. Cuatro campos determinan cómo se tratan las señales. Cada uno es NO_ACTION (el valor predeterminado) o DECLINE, y cada uno solo tiene efecto cuando enable_enrichment es true.

Campo	Rechaza cuando
`phone_intelligence_score_action`	La puntuación de riesgo supera el umbral.
`phone_type_risk_action`	El número es de un tipo de línea de alto riesgo.
`recent_port_action`	El número se portó a otro operador recientemente.
`low_phone_trust_action`	El índice de confianza es igual o inferior al umbral.

Con NO_ACTION, la señal se sigue devolviendo en phone.phone_intelligence, para que puedas aplicar tu propia regla.

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

El mismo número de teléfono usado en la llamada correspondiente a POST /v3/phone/send/, en formato E.164. Es lo que vincula la comprobación con el envío.

Maximum string length: 20

Ejemplo:

"+14155552671"

code

string

requerido

El OTP que recibió el usuario final. Debe tener entre 4 y 8 dígitos numéricos; cualquier otro valor devuelve 400 sin consumir un intento. Un código con formato correcto pero erróneo devuelve 200 con status: "Failed" y consume uno de los 3 intentos.

Required string length: 4 - 8

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

Ejemplo:

"123456"

duplicated_phone_number_action

enum<string>

predeterminado:NO_ACTION

Qué hacer cuando otro usuario de tu aplicación (con un vendor_data distinto) ya usó el mismo número. DECLINE cambia el status final a Declined; NO_ACTION registra el riesgo en phone.warnings y rellena phone.matches.

Opciones disponibles:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

predeterminado:NO_ACTION

Qué hacer cuando la consulta al operador marca el número como línea temporal o desechable (phone.is_disposable). DECLINE cambia el status final a Declined; NO_ACTION registra el riesgo en phone.warnings.

Opciones disponibles:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

predeterminado:NO_ACTION

Qué hacer cuando la consulta al operador indica un tipo de línea virtual: voip, isp o vpn (phone.is_virtual). DECLINE cambia el status final a Declined; NO_ACTION registra el riesgo en phone.warnings.

Opciones disponibles:

NO_ACTION,

DECLINE

enable_enrichment

boolean

predeterminado:false

Si es true, también ejecuta inteligencia de teléfono sobre el número: una puntuación de riesgo, el tipo de línea, si se portó recientemente y un índice de confianza. Se factura como una unidad phone_intelligence_api por solicitud ($0.05 a precio de lista), además del precio propio de este endpoint. La solicitud devuelve 403 cuando tu saldo no alcanza para cubrirlo.

Ejemplo:

false

phone_intelligence_score_action

enum<string>

predeterminado:NO_ACTION

Acción cuando la puntuación de riesgo de inteligencia del teléfono supera el umbral. DECLINE cambia el status final a Declined; NO_ACTION registra la señal sin rechazar. Solo tiene efecto cuando enable_enrichment es true.

Opciones disponibles:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

predeterminado:NO_ACTION

Acción cuando el número es de un tipo de línea de alto riesgo. DECLINE cambia el status final a Declined; NO_ACTION registra la señal sin rechazar. Solo tiene efecto cuando enable_enrichment es true.

Opciones disponibles:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

predeterminado:NO_ACTION

Acción cuando el número se portó recientemente a otro operador. DECLINE cambia el status final a Declined; NO_ACTION registra la señal sin rechazar. Solo tiene efecto cuando enable_enrichment es true.

Opciones disponibles:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

predeterminado:NO_ACTION

Acción cuando el índice de confianza de inteligencia del teléfono es igual o inferior al umbral. DECLINE cambia el status final a Declined; NO_ACTION registra la señal sin rechazar. Solo tiene efecto cuando enable_enrichment es true.

Opciones disponibles:

NO_ACTION,

DECLINE

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

Acción cuando la comprobación de huella social no encuentra el número registrado en ninguna de las plataformas que cubre. En este endpoint solo se aceptan NO_ACTION y DECLINE; REVIEW está disponible en la clave de configuración del flujo con el mismo nombre.

Opciones disponibles:

NO_ACTION,

DECLINE

Respuesta

Comprobación completada: los códigos incorrectos y las verificaciones inexistentes también devuelven 200; revisa status, no el código HTTP. phone solo se rellena en resultados finalizados (Approved/Declined), es null en Failed y no aparece en Expired or Not Found.

request_id

string<uuid>

Con Approved/Declined: el id de sesión de la verificación coincidente, idéntico al request_id que devuelve POST /v3/phone/send/. Con Failed y Expired or Not Found: un UUID aleatorio de un solo uso que no se puede consultar después.

status

enum<string>

Approved: código correcto, sin ningún riesgo que provoque rechazo. Declined: estado final; coincidió un riesgo que provoca rechazo o se agotó el número de intentos (3). Failed: código incorrecto, quedan intentos. Expired or Not Found: no hay ninguna verificación pendiente para este número en los últimos 5 minutos.

Opciones disponibles:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Explicación legible del resultado, incluido el número de intentos restantes tras un código incorrecto.

phone

object | null

Informe completo del teléfono. Presente (no nulo) solo en resultados finalizados (Approved/Declined); null en Failed y ausente en Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data de la sesión de la verificación coincidente. null en Expired or Not Found.

metadata

object | null

metadata de la sesión de la verificación coincidente. null en Expired or Not Found.

created_at

string<date-time>

Marca de tiempo de esta respuesta de comprobación.

Última modificación el 1 de noviembre de 2026

​Gestionar caídas del proveedor

​Complemento de inteligencia

Autorizaciones

Cuerpo

Respuesta

Gestionar caídas del proveedor

Complemento de inteligencia