Lookup API

The Lookup API provides a way to retrieve additional information about a phone number. Lookup currently supports the following types of data.

Region-specific number formatting and validation
キャリア情報
発信者の名前

You can specify one or more types of information you would like to purchase in the request, check the Lookup Product Page for pricing information.

API URL

All URLs referenced in the documentation use the following URL.

https://lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber}

TwilioのREST APIはHTTPS経由で提供されます。データのプライバシーを確保するため、暗号化されていないHTTPはサポートされません。

{PhoneNumber} is the phone number you are requesting information about. Phone numbers can be specified either in national formatting or in standard E.164 format. If providing a number in local national format, please also specify the country as an optional parameter. If no country is provided, this will default to US. Twilio will use libphonenumber, Google’s open source phone number handling library, to properly format possible phone numbers for a given region, using length and prefix.

認証

HTTP requests to the REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please refer to our security documentation. In short, you will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.

curl -G https://lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber} \
    -u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'

You can find your account SID and auth token in your console.

To learn more about authentication and interaction with the Twilio REST API, check out our documentation for requests to the API and Twilio's response.

Lookup a Phone Number

HTTP GET

Returns phone number information matching the specified request. Formatting information is standard. Carrier, Caller Name, and phone number type information can be requested, in addition to using Add-ons to access 3rd party data sources.

クエリーパラメーター

下記の標準的なGETクエリーは電話番号の情報のタイプを特定します。

Names in PHP format
`phoneNumber` 必須	GET phone_number PII MTL: 60 DAYS The phone number to lookup in E.164 format, which consists of a + followed by the country code and subscriber number.
`countryCode` オプション	GET 文字列 PII MTL: 60 DAYS The ISO country code of the phone number to fetch. This is used to specify the country when the phone number is provided in a national format.
`type` オプション	GET string[] Not PII The type of information to return. Can be: `carrier` or `caller-name`. The default is null. Carrier information costs $0.005 per phone number looked up. Caller Name information is currently available only in the US and costs $0.01 per phone number looked up. To retrieve both types on information, specify this parameter twice; once with `carrier` and once with `caller-name` as the value.
`addOns` オプション	GET string[] PII MTL: 60 DAYS The `unique_name` of an Add-on you would like to invoke. Can be the `unique_name` of an Add-on that is installed on your account. You can specify multiple instances of this parameter to invoke multiple Add-ons. For more information about Add-ons, see the Add-ons documentation.
`addOnsData` オプション	GET prefixed_collapsible_map<AddOns> Not PII Data specific to the add-on you would like to invoke. The content and format of this value depends on the add-on.

リソースのプロパティ

下記のプロパティは常に返されます。

Names in PHP format
`callerName`	string_map PII MTL: 60 DAYS The name of the phone number's owner. If `null`, that information was not available.
`countryCode`	文字列 PII MTL: 60 DAYS この電話番号のISO 国コードです。
`phoneNumber`	phone_number PII MTL: 60 DAYS The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.
`nationalFormat`	文字列 PII MTL: 60 DAYS 国内番号フォーマットでの電話番号。
`carrier`	string_map Not PII The telecom company that provides the phone number.
`addOns`	オブジェクト PII MTL: 60 DAYS A JSON string with the results of the Add-ons you specified in the `add_ons` parameters. For the format of the object, see Using Add-ons.
`url`	url Not PII The absolute URL of the resource.

情報を持ちうるできる番号（地域、長さ、プレフィックスの情報）はフォーマット化された結果を返します。存在しない番号のルックアップを試みた場合、HTTP404 エラーを返します。

キャリア情報

NOTE: For some regions like Canada, we are unable to return carrier and cellphone data by default. Please contact our support team to switch on those regions. More information is available on our support site.

GETリクエスト中でキャリア情報をリクエストすると下記の追加情報が返却されます。

名前	概要
MobileCountryCode	キャリアのモバイル国コード（携帯電話番号のみ対象）
MobileNetworkCode	キャリアのモバイルネットワークコード（携帯電話のみ対応）
名前	キャリア名キャリア名は頻繁に変わります。そのため Name も同様に変わります。
Type	電話番号タイプ取りうる値は、`landline`、`mobile`もしくは`voip`です。詳しくは電話番号タイプをご覧ください。
ErrorCode	このリクエストに関連するエラーコード

電話番号タイプ

下記は'Type'プロパティで取りうる値です。

Type	概要
landline	この電話番号は固定電話で、一般的にSMSを受信することはできません。
携帯電話	この番号は携帯電話で、一般的にSMSを受信することができます。
voip	インターネットをベースにした電話番号でSMSの受信は番号によります。例としてはGoogle Voiceがこれにあたります。

発信者の名前

GET リクエストで発信者名を要求した場合は、以下の追加のプロパティが返されます。

名前	概要
CallerName	電話番号の所有者の名前を示す文字列。利用できない場合は、 `null` 返します。
CallerType	この発信者がビジネスなのか消費者なのかを示す文字列。取りうる値は `business` および `consumer` です。使用できない場合は、 `null` を返します。
ErrorCode	このリクエストに関連するエラーコード

米国の番号の発信者名ルックアップは、データがない場合でも、ルックアップごとに課金されます。現時点では、国際電話番号についての発信者名ルックアップをリクエストすると、値 null が返されますが、課金はされません。

サンプル

Loading Code Sample...

Next Sample

出力を表示

出力

E.164形式で電話番号を検索します

Carrier Lookup with E.164 Formatted Number

E.164形式で電話番号を検索します

Loading Code Sample...

Next Sample

出力を表示

出力

Carrier Lookup with National Formatted Number

Loading Code Sample...

Next Sample

出力を表示

出力

発信者検索

Using Add-ons with Lookup

Lookup also supports Twilio Add-ons, enabling you to retrieve information from a multitude of 3rd party data sources, available via the Twilio Marketplace.

When you use AddOns, you can pass additional parameters to the Add-on(s):

名前	概要
AddOns.addon_name.param_name	Optional. Passes additional data to the Add-on at request time. See Add-on documentation in Console to identify if the Add-on requires additional parameters.