전화번호 인증 코드 확인 API: SMS OTP 검증

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"
}

제공업체 장애 처리

전화번호 제공업체를 일시적으로 사용할 수 없으면 이 엔드포인트는 안정적인 기계 판독용 코드와 함께 502를 반환합니다:

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

이 응답은 재시도 가능한 것으로 취급하십시오. 짧은 백오프를 적용하고, 유효한 전화번호나 코드를 바꾸라고 요청하는 대신 사용자에게 일시적인 서비스 장애 메시지를 표시하십시오.

인텔리전스 부가 기능

enable_enrichment를 true로 설정하면 해당 번호에 대한 전화번호 인텔리전스도 함께 실행됩니다. 위험 점수, 회선 유형, 최근 번호 이동 여부, 신뢰 지수를 확인할 수 있습니다. 이 부가 기능은 정가 기준으로 요청당 $0.05가 청구되며, 확인 요청 비용에 추가로 부과됩니다. 잔액이 이 비용을 감당할 수 없으면 요청은 403을 반환합니다. 네 가지 필드가 각 신호에 따라 어떤 조치를 취할지 결정합니다. 각 필드는 NO_ACTION(기본값) 또는 DECLINE으로 설정하며, 각 필드는 enable_enrichment가 true일 때만 적용됩니다.

필드	거부되는 경우
`phone_intelligence_score_action`	위험 점수가 임계값을 초과하는 경우입니다.
`phone_type_risk_action`	번호가 고위험 회선 유형인 경우입니다.
`recent_port_action`	번호가 최근 다른 통신사로 이동된 경우입니다.
`low_phone_trust_action`	신뢰 지수가 임계값 이하인 경우입니다.

NO_ACTION으로 설정하면 해당 신호는 여전히 phone.phone_intelligence에 반환되므로, 자체 규칙을 적용할 수 있습니다.

인증

x-api-key

string

header

필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

본문

application/json

phone_number

string

필수

일치하는 POST /v3/phone/send/ 호출에 사용된 것과 동일한 E.164 형식의 전화번호입니다. 이를 통해 검증과 전송이 연결됩니다.

Maximum string length: 20

예시:

"+14155552671"

code

string

필수

최종 사용자가 수신한 OTP입니다. 4~8자리 숫자여야 하며, 그 외의 경우 시도 횟수를 차감하지 않고 400을 반환합니다. 형식은 올바르지만 잘못된 코드는 200과 함께 status: "Failed"를 반환하고 3회의 시도 횟수 중 1회를 소진합니다.

Required string length: 4 - 8

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

예시:

"123456"

duplicated_phone_number_action

enum<string>

기본값:NO_ACTION

동일한 번호가 애플리케이션의 다른 사용자(다른 vendor_data)에 의해 이미 사용되었을 때 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하며, NO_ACTION은 위험을 phone.warnings에 기록하고 phone.matches를 채웁니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

disposable_number_action

enum<string>

기본값:NO_ACTION

통신사 조회를 통해 해당 번호가 일회용/임시 번호로 확인되었을 때(phone.is_disposable) 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하고, NO_ACTION은 해당 위험을 phone.warnings에 기록합니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

voip_number_action

enum<string>

기본값:NO_ACTION

통신사 조회에서 voip, isp 또는 vpn과 같은 가상 회선 유형으로 보고되었을 때(phone.is_virtual) 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하고, NO_ACTION은 해당 위험을 phone.warnings에 기록합니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

enable_enrichment

boolean

기본값:false

true인 경우 해당 번호에 대한 전화번호 인텔리전스(위험 점수, 회선 유형, 최근 통신사 변경 여부 및 신뢰 지수)도 실행합니다. 이 endpoint의 자체 가격 외에 요청당 하나의 phone_intelligence_api 단위(정가 기준 $0.05)로 청구됩니다. 잔액이 이를 충당하지 못하면 요청은 403을 반환합니다.

예시:

false

phone_intelligence_score_action

enum<string>

기본값:NO_ACTION

전화번호 인텔리전스 위험 점수가 임계값을 초과할 때 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하며, NO_ACTION은 거부하지 않고 신호를 기록합니다. enable_enrichment가 true일 때만 적용됩니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

phone_type_risk_action

enum<string>

기본값:NO_ACTION

전화번호가 고위험 회선 유형일 때 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하며, NO_ACTION은 거부하지 않고 신호를 기록합니다. enable_enrichment가 true일 때만 적용됩니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

recent_port_action

enum<string>

기본값:NO_ACTION

전화번호가 최근 다른 통신사로 번호 이동되었을 때 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하며, NO_ACTION은 거부하지 않고 신호를 기록합니다. enable_enrichment가 true일 때만 적용됩니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

low_phone_trust_action

enum<string>

기본값:NO_ACTION

전화번호 인텔리전스 신뢰 지수가 임계값 이하일 때 수행할 작업입니다. DECLINE은 최종 status를 Declined로 변경하며, NO_ACTION은 거부하지 않고 신호를 기록합니다. enable_enrichment가 true일 때만 적용됩니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

true인 경우, 전화번호의 소셜 발자국(등록된 메시징, 소셜, 전자상거래 및 전문 플랫폼)도 조회합니다. 이 endpoint 자체의 가격 외에 요청당 phone_social 1단위로 청구됩니다.

예시:

true

소셜 풋프린트 검사 결과 지원하는 플랫폼 중 어느 곳에도 해당 번호가 등록되어 있지 않을 때 수행할 작업입니다. 이 endpoint에서는 NO_ACTION 및 DECLINE만 허용되며, 동일한 이름의 워크플로 구성 키에서는 REVIEW를 사용할 수 있습니다.

사용 가능한 옵션:

NO_ACTION,

DECLINE

응답

확인 완료 — 잘못된 코드 및 누락된 인증도 200을 반환하므로 HTTP 코드가 아닌 status를 확인하십시오. phone은 최종 결과(Approved/Declined)에서만 채워지며, Failed에서는 null, Expired or Not Found에서는 제외됩니다.

request_id

string<uuid>

Approved/Declined인 경우: 일치하는 인증의 세션 ID — POST /v3/phone/send/에서 반환된 request_id와 동일합니다. Failed 및 Expired or Not Found인 경우: 나중에 조회할 수 없는 일회성 무작위 UUID입니다.

status

enum<string>

Approved — 올바른 코드이며 거부 위험이 없음. Declined — 최종 상태: 거부 위험이 일치했거나 시도 횟수 한도(3회)가 소진됨. Failed — 잘못된 코드이며 잔여 시도 횟수가 있음. Expired or Not Found — 지난 5분 동안 이 번호에 대한 보류 중인 인증이 없음.

사용 가능한 옵션:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

잘못된 코드 입력 후 남은 시도 횟수를 포함한 결과에 대한 사람이 읽기 쉬운 설명입니다.

phone

object | null

전체 전화번호 보고서입니다. 확정된 결과(Approved/Declined)에만 존재(null이 아님)하며, Failed인 경우 null, Expired or Not Found인 경우 생략됩니다.

Show child attributes

vendor_data

string | null

일치하는 인증 세션의 vendor_data입니다. Expired or Not Found인 경우 null입니다.

metadata

object | null

일치하는 인증 세션의 metadata입니다. Expired or Not Found인 경우 null입니다.

created_at

string<date-time>

이 검사 응답의 타임스탬프입니다.

마지막 수정일 2026년 11월 7일

​제공업체 장애 처리

​인텔리전스 부가 기능

인증

본문

응답

제공업체 장애 처리

인텔리전스 부가 기능