発信者名を照会する
電話番号について、取得可能な発信者名の照会結果を取得します。これは本番環境での照会であり、サービスのキャッシュから結果が返される場合も含め、アカウントに料金が発生することがあります。所有する電話番号の発信時に表示される名前は変更されません。
返された名前は、本人であること、番号の所有権、電話をかける許可が確認されたことを意味しません。名前は欠落していたり、古かったり、省略されていたりする場合があります。また、地理的な名称や、代替値として電話番号が返される場合もあります。
リクエスト
有効化された API アカウントを使用し、そのアカウントで許可された送信元 IP アドレスからアクセスしてください。認証情報はサーバー側のシークレットストレージに保管してください。この例では環境変数と架空の北米の電話番号を使用しています。認証情報を URL や公開されるブラウザー側のコードに含めないでください。
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
https://api.multitel.net/v3/cnam/12025550123国番号を含む完全な電話番号を数字のみで指定してください。たとえば、北米では 1 で始まる十一桁の番号です。区切り記号やプラス記号がハンドラーによって正規化されることを前提にしないでください。リクエスト本文や地域の指定は不要です。予定する用途でサポートされる対象範囲を MultiTEL に確認してください。
レスポンス
値はあくまで例です。費用の値は料金の見積もりではありません。
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"number": "12025550123",
"name": "EXAMPLE NAME",
"cost": 0.0037,
"balance": 9.9963
}
}| フィールド | 意味 |
|---|---|
| number | 照会対象の電話番号。 |
| name | 取得可能な名前、または代替のテキスト。本人確認を意味するものではありません。 |
| cost | この処理経路で返される、アカウントまたはサービスに設定された照会料金。例示された値ではなく、アカウントの現在の料金を使用してください。 |
| balance | レスポンス用に計算された残高。トランザクション処理によってアカウント残高を新たに照会した結果ではありません。 |
課金と照合
名前が返された結果には、アカウントに設定された CNAM 料金が課金されます。同じ照会の繰り返しやキャッシュを利用した照会でも、追加の料金が発生することがあります。冪等性キーは提供されていません。自動照会を有効にする前に、アカウントの現在の料金を確認してください。
キャッシュされた名前が空の場合、レスポンスに既知の制限があります。この分岐ではアカウントから残高を差し引かないにもかかわらず、ハンドラーが空の名前、ゼロではない費用、差し引き後として計算された残高とともに API コード 200 を返すことがあります。このレスポンスだけを課金の証拠としないでください。アカウントの請求記録と、新たに実行する残高照会の結果を照合し、判断がつかない結果についてはサポートにお問い合わせください。
現在の前払い残高チェックでは、設定された照会単価にかかわらず、照会前に少なくとも 0.004 の残高が必要です。購入が無効になっているアカウントも拒否されます。これらのチェックがあるからといって、このエンドポイントが料金見積もりや支出制限のための API になるわけではありません。
エラーと再試行
HTTP ステータスと、JSON の status.code/status.msg の両方を確認してください。API コード 403 は、前払い残高の不足、購入の禁止、アカウントの認可の問題、または発信者名が見つからなかったことを意味する場合があります。名前が見つからない処理経路では、コードが文字列として返されることがあります。すべての 403 を認証情報の不備とみなさず、メッセージを確認してください。設定の競合では API コード 500 が返される場合があります。
課金対象の照会が行われた後にタイムアウトすることがあります。アプリケーションに適している場合に限り、回数を制限し、待機時間を延ばしながら再試行してください。その前に、結果が不明な試行について照合してください。拒否された番号や、アカウントの権限または残高に起因する失敗に対して、再試行を繰り返さないでください。契約条件と精度要件の範囲内で、アプリケーションにレスポンスキャッシュを設けると、リクエストの繰り返しを減らせます。
その他の電話番号操作
この読み取り操作は、発信時の表示名／LIDB の更新、電話帳への掲載、発信者登録とは別のものです。それらの操作には、それぞれ必要なフィールド、認可、料金があります。番号割り当ての対象範囲でプレフィックステーブルを確認するか、電話番号検索で注文可能な番号の在庫を確認してください。いずれの操作も、発信者が名乗っている本人であることを証明するものではありません。