メインコンテンツへスキップ
POST
curl
POST /v3/phone/risk/は、OTPフローの前に、OTPフローの代わりに、またはOTPフローとは別に電話番号のインテリジェンスが必要な場合に使用します。 ユーザーにコードは送信しません。APIセッションを作成して電話番号情報を拡充し、電話番号リスクのルールを適用したうえで、電話番号検証で使われるものと同じ正規化された電話番号ブロックを1回の同期レスポンスで返します。 リクエストが保存されると、Diditはスコアリングされた電話番号をNetworksの集約されたエビデンスとしても利用できます。ネットワークグラフには、共有されている電話番号シグナルについて、高リスクの電話番号インテリジェンス、番号ポータビリティ、回線種別のコンテキストが表示されることがあります。ただし、生の電話番号が他の組織に開示されることはありません。

レスポンスの解釈

  • statusはこのAPIセッションの最終判定です。通常はApprovedですが、リスク評価によってIn ReviewまたはDeclinedになることもあります。
  • phone.full_numberはE.164形式に正規化された番号です。phone.phone_number_prefixとphone.phone_numberは、この番号を国際プレフィックスと国内番号に分割したものです。
  • phone.is_disposableとphone.is_virtualは、アプリケーションのロジックで使える安定したyes/noシグナルです。通信事業者の照会により、carrier.nameとcarrier.type(mobile、voipなど)が追加されます。
  • phone.phone_intelligence.scoreは0~100のリスクスケールで、数値が高いほどリスクが高いことを示します。phone_type_risk(Low、Medium、High)とphone_trust_index(スコアを反転した値)は、このスコアから派生した指標です。
  • phone.phone_intelligenceとphone.enrichmentは、同じ正規化オブジェクトを指す互換性のためのエイリアスです。新しい連携ではphone.enrichmentを参照できます。
  • phone.matchesには、同じ番号が別のユーザーによって使われた、自社アプリケーションの他のセッションが一覧表示されます。重複アカウントの検出に使用してください。
  • request_idはAPIセッションIDです。後続のWebhookやコンソール上のアクティビティと結果を照合する必要がある場合は、vendor_dataとともに保存してください。
phone.phone_intelligenceとphone.enrichmentはベストエフォートのフィールドです。照会が完了しても、その番号、国、またはプランについて利用可能なインテリジェンスデータが返されなかった場合は、両方とも省略されることがあります。ルールはまず安定した正規化フィールドに基づいて構築し、インテリジェンスが欠けている場合は「安全」ではなく「不明」として扱ってください。

ソーシャルフットプリントアドオン

enable_socialをtrueに設定すると、レスポンスのphoneの下にphone_socialブロックが追加されます。このブロックには、この電話番号が登録されているオンラインプラットフォームがカテゴリ別に含まれ、集計値と、データパートナーが返すプロフィールの詳細も含まれます。
  • phone.phone_social.profiles_registeredとphone.phone_social.profiles_checkedは主要な数値で、評価したプラットフォームのうち、電話番号の登録が確認されたプラットフォームの数を示します。
  • phone.phone_social.registered_platformsとphone.phone_social.not_registered_platformsは、各プラットフォームをそのcategoryとscope(global、または地域限定のプラットフォームの場合はlocal)とともに一覧表示します。
  • phone.phone_social.categoriesはカテゴリごとの登録数と比率を示します。phone.phone_social.profilesには、プラットフォームから提供される場合に、プラットフォームごとのプロフィールの詳細(名前、写真のURL、自己紹介文、プライバシー設定、ビジネスアカウントのフラグ)が含まれます。
  • 集計指標(digital_footprint_diversity、digital_sophistication_index、engagement_depth_index、subscription_affordability_index)は0~10の複合指標です。チェックでデータが返されなかった項目については、どの数値もnullになる場合があります。
profiles_registered: 0は失敗ではなく、実際の結果です。プラットフォームのチェックは行われたものの、どのプラットフォームでもその電話番号が見つからなかったことを意味し、合成IDによく見られるシグナルです。このエンドポイント自体は、この結果に基づいてアクションを実行しません。レビューまたは却下の判定につなげるには、ワークフローでphone_no_social_presence_actionを使用してください。 このブロックは、enable_socialが設定されていない場合に加え、ソーシャルチェックを完了できなかった場合にも含まれません。後者の場合は請求されません。

サンドボックスでの動作

サンドボックスキーはリクエストを検証し、決定論的な承認済みデータを返します。OTPの送信、クレジットの消費、セッションの作成、ネットワークへの寄与は行いません。enable_socialを設定した場合は、決定論的なphone_socialブロックも返します。

請求

Phone Risk APIの呼び出しは定価で$0.04です。OTPを送信しないため、完全な電話番号検証より安価です。本番環境のリクエストは、一部のベストエフォートのフィールドが利用できない場合でも、照会が開始された時点で課金対象となります。 ソーシャルフットプリントアドオンは別途請求されます。チェックが完了するたびに、Phone Risk APIの料金に加えて、リクエスト1件につきphone_social1単位が請求されます。照会前のクレジットチェックは、両方をカバーします。

承認

x-api-key
string
header
必須

お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権(なし、読み取り、書き込み)、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys

ボディ

application/json
phone_number
string
必須

スコアリング対象の電話番号。検証されたうえでE.164形式に正規化されます。

Maximum string length: 20
例:

"+14155552671"

country_code
string

インテリジェンスのカバレッジ向けの任意のISO 3166-1 alpha-2またはalpha-3の国ヒントです。

Maximum string length: 3
例:

"US"

signals
object

アプリケーションが観測したデバイスおよびネットワークのコンテキストで、任意指定です。すべてのフィールドは任意です。これらを渡すと、Networksにおけるセッション横断の一致検出に活用されます。

vendor_data
string

このリクエストに対する固定の参照値です。APIセッションに保存され、レスポンスでそのまま返されます。

metadata
object | null

機密性のないJSONメタデータです。APIセッションに保存され、レスポンスでそのまま返されます。

enable_social
boolean
デフォルト:false

trueの場合、番号のソーシャルフットプリント(その番号が登録されているメッセージング、ソーシャル、EC、ビジネスの各プラットフォーム)も検索します。このエンドポイント自体の料金に加えて、リクエスト1件ごとにphone_social1ユニット分が請求されます。

例:

true

レスポンス

リスク評価が完了しました。判定はstatusで確認してください。完了したルックアップでは、HTTPは常に200です。

request_id
string<uuid>
必須

このリクエストで作成されたAPIセッションのID。結果を後続のWebhookやコンソール上のアクティビティと関連付ける必要がある場合は、vendor_dataとともに保存してください。

status
enum<string>
必須

このAPIセッションの最終判定です。通常はApprovedですが、リスク評価によってIn ReviewまたはDeclinedになる場合があります。

利用可能なオプション:
Approved,
In Review,
Declined
created_at
string<date-time>
必須

このレスポンスの日時。

vendor_data
string | null

送信したvendor_dataのエコー。送信しなかった場合はnullです。

metadata
object | null

送信したmetadataのエコー。送信しなかった場合はnullです。

phone
object

正規化された電話番号レポート。電話番号検証のレスポンスで使われるものと同じブロックです。

最終更新日 2026年11月1日