API de codi OTP de telèfon: validar codi 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"
}

Gestió de les interrupcions del proveïdor

Si el proveïdor de telefonia no està disponible temporalment, aquest endpoint retorna 502 amb un codi estable i llegible per màquines:

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

Tracta aquesta resposta com a reintentable. Fes servir una espera curta abans de reintentar i mostra a l’usuari un missatge de servei temporalment no disponible, en lloc de demanar-li que canviï un número de telèfon o un codi vàlids.

Complement d’intel·ligència

Estableix enable_enrichment a true per executar també la intel·ligència de telefonia sobre el número: una puntuació de risc, el tipus de línia, si el número s’ha portat recentment a un altre operador i un índex de confiança. El complement es factura a $0.05 per sol·licitud al preu de llista, a sobre del preu de la verificació. La sol·licitud retorna 403 quan el teu saldo no és suficient per cobrir-lo. Quatre camps determinen què fan els senyals. Cadascun és NO_ACTION (el valor per defecte) o DECLINE, i cadascun només té efecte quan enable_enrichment és true.

Camp	Rebutja quan
`phone_intelligence_score_action`	La puntuació de risc és superior al llindar.
`phone_type_risk_action`	El número és d’un tipus de línia d’alt risc.
`recent_port_action`	El número s’ha transferit recentment a un altre operador.
`low_phone_trust_action`	L’índex de confiança és igual o inferior al llindar.

Amb NO_ACTION, el senyal es retorna igualment a phone.phone_intelligence, perquè puguis aplicar la teva pròpia regla.

Autoritzacions

x-api-key

string

header

requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

application/json

phone_number

string

requerit

El mateix número de telèfon utilitzat a la crida POST /v3/phone/send/ coincident, en format E.164. Això és el que enllaça la comprovació amb l'enviament.

Maximum string length: 20

Exemple:

"+14155552671"

code

string

requerit

L'OTP que ha rebut l'usuari final. Ha de tenir entre 4 i 8 dígits numèrics; qualsevol altra cosa retorna 400 sense consumir cap intent. Un codi ben format però incorrecte retorna 200 amb status: "Failed" i consumeix un dels 3 intents.

Required string length: 4 - 8

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

Exemple:

"123456"

duplicated_phone_number_action

enum<string>

predeterminat:NO_ACTION

Què fer quan el mateix número ja ha estat utilitzat per un usuari diferent (diferent vendor_data) de la teva aplicació. DECLINE canvia el status final a Declined; NO_ACTION registra el risc a phone.warnings i emplena phone.matches.

Opcions disponibles:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

predeterminat:NO_ACTION

Què fer quan la cerca de l'operador marca el número com a línia temporal/d'un sol ús (phone.is_disposable). DECLINE canvia el status final a Declined; NO_ACTION registra el risc a phone.warnings.

Opcions disponibles:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

predeterminat:NO_ACTION

Què fer quan la cerca de l'operador indica un tipus de línia virtual — voip, isp o vpn (phone.is_virtual). DECLINE canvia el status final a Declined; NO_ACTION registra el risc a phone.warnings.

Opcions disponibles:

NO_ACTION,

DECLINE

enable_enrichment

boolean

predeterminat:false

Quan és true, també executa intel·ligència telefònica al número: una puntuació de risc, el tipus de línia, si s'ha portat recentment i un índex de confiança. Es factura com una unitat de phone_intelligence_api per sol·licitud ($0.05 a preu de tarifa) a més del preu propi d'aquest endpoint. La sol·licitud retorna 403 quan el teu saldo no pot cobrir-ho.

Exemple:

false

phone_intelligence_score_action

enum<string>

predeterminat:NO_ACTION

Acció quan la puntuació de risc de la intel·ligència telefònica supera el llindar. DECLINE canvia l'status final a Declined; NO_ACTION registra el senyal sense rebutjar. Només té efecte quan enable_enrichment és true.

Opcions disponibles:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

predeterminat:NO_ACTION

Acció quan el número és d'un tipus de línia d'alt risc. DECLINE canvia l'status final a Declined; NO_ACTION registra el senyal sense rebutjar. Només té efecte quan enable_enrichment és true.

Opcions disponibles:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

predeterminat:NO_ACTION

Acció quan el número s'ha portat recentment a una altra operadora. DECLINE canvia l'status final a Declined; NO_ACTION registra el senyal sense rebutjar. Només té efecte quan enable_enrichment és true.

Opcions disponibles:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

predeterminat:NO_ACTION

Acció quan l'índex de confiança de la intel·ligència telefònica és igual o inferior al llindar. DECLINE canvia l'status final a Declined; NO_ACTION registra el senyal sense rebutjar. Només té efecte quan enable_enrichment és true.

Opcions disponibles:

NO_ACTION,

DECLINE

Quan és cert, també consulta la petjada social del número: les plataformes de missatgeria, socials, de comerç electrònic i professionals on està registrat. Es factura com una unitat de phone_social per sol·licitud a més del preu propi d'aquest endpoint.

Exemple:

true

Acció quan la comprovació de petjada social no troba el número registrat a cap de les plataformes que cobreix. En aquest endpoint només s'accepten NO_ACTION i DECLINE; REVIEW està disponible a la clau de configuració del flux de treball amb el mateix nom.

Opcions disponibles:

NO_ACTION,

DECLINE

Resposta

Comprovació completada: els codis incorrectes i les verificacions que falten també retornen 200; inspecciona status, no el codi HTTP. phone només s'emplena en resultats finalitzats (Approved/Declined), és null a Failed, i no apareix a Expired or Not Found.

request_id

string<uuid>

A Approved/Declined: l'identificador de sessió de la verificació coincident — idèntic al request_id retornat per POST /v3/phone/send/. A Failed i Expired or Not Found: un UUID aleatori d'un sol ús que no es podrà consultar posteriorment.

status

enum<string>

Approved — codi correcte, sense risc que provoqui rebuig. Declined — terminal: ha coincidit un risc que provoca rebuig o s'ha esgotat el pressupost d'intents (3). Failed — codi incorrecte, queden intents. Expired or Not Found — cap verificació pendent per a aquest número en els darrers 5 minuts.

Opcions disponibles:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Explicació fàcil de llegir del resultat, inclòs el nombre d'intents restants després d'un codi incorrecte.

phone

object | null

Informe telefònic complet. Present (no nul) només en resultats finalitzats (Approved/Declined); null a Failed i absent en Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data de la sessió de la verificació coincident. null a Expired or Not Found.

metadata

object | null

metadata de la sessió de la verificació coincident. null a Expired or Not Found.

created_at

string<date-time>

Marca de temps de la resposta d'aquesta comprovació.

Darrera modificació el 7 de novembre del 2026

​Gestió de les interrupcions del proveïdor

​Complement d’intel·ligència

Autoritzacions

Cos

Resposta

Gestió de les interrupcions del proveïdor

Complement d’intel·ligència