メニュー

Expand
ページを評価:

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.

認証

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.

Phone number lookup

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クエリーは電話番号の情報のタイプを特定します。

Parameters in REST API format
phone_number
Path
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.

country_code
オプション
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.

add_ons
オプション
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.

add_ons_data
オプション
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.

リソースのプロパティ

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

  • Only possible numbers (for a given region, using length and prefix information) will return formatting results. If you attempt to lookup a phone number which is not valid, you will receive an HTTP 404 error.
  • Machine to machine (M2M) phone numbers are not supported in Lookup and will return an HTTP 404 error.
Resource Properties in REST API format
caller_name
オブジェクト PII MTL: 60 DAYS

The name of the phone number's owner. If null, that information was not available.

country_code
文字列 PII MTL: 60 DAYS

この電話番号のISO 国コードです。

phone_number
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.

national_format
文字列 PII MTL: 60 DAYS

国内番号フォーマットでの電話番号。

carrier
オブジェクト Not PII

The telecom company that provides the phone number.

add_ons
オブジェクト 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.

  • Access to Canada carrier information requires special approval. Please read this support article to learn more. Querying a Canada phone number without access will return a 60101 error.
  • Toll free numbers do not return carrier data, but will return a valid HTTP response.

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

名前 概要
MobileCountryCode The three digit mobile country code of the carrier, used with the mobile network code to identify a mobile network operator.
MobileNetworkCode The two-three digit mobile network code of the carrier, used with the mobile country code to identify a mobile network operator (only returned for mobile numbers).
名前 The name of the carrier; often subject to change.
Type The phone number type. Possible values are landline, mobile, or voip. See 'Phone Number Types' below for more information.
ErrorCode このリクエストに関連するエラーコード
電話番号タイプ

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

Type 概要
landline The phone number is a landline number; generally not capable of receiving SMS messages.
携帯電話 The phone number is a mobile number; generally capable of receiving SMS messages.
voip An internet based phone number that may or may not be capable of receiving SMS messages. For example, Google Voice. Returned for U.S. numbers only.
null The phone number is valid but no information was returned from our data providers (see limitation for Canada numbers).

Caller name information

Caller name information is sourced through CNAM and only available for phone numbers owned by carriers in the US. We recommend testing the coverage rate of this lookup with your specific dataset of phone numbers.

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

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

Caller name lookups for US numbers are billed per lookup, even if data is not be available. Requesting Caller name lookups for non-US will return null values and will not be billed.

        
        
        
              
              
              
                    
                    
                    

                    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.

                    You can add Lookup-supported add-ons by visiting the Twilio console to enabling the add-on, making sure you have 'Lookups' selected:

                    Enable Lookups to use your whitepages pro add-on

                    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.

                    Examples with Add-ons

                          
                          
                          

                          Whitepages Pro Caller ID geographic restrictions

                          Please note that the Whitepages add-on only works with phone numbers with the +1 country code: U.S., Canada, Puerto Rico. If you need to check numbers in all countries, consider using our Lookup API without add-ons, which you can try out in the console.

                                
                                
                                
                                      
                                      
                                      
                                      ページを評価:

                                      ヘルプが必要ですか?

                                      We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                            
                                            
                                            

                                            フィードバックくださりありがとうございます!

                                            Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                            Sending your feedback...
                                            🎉 Thank you for your feedback!
                                            Something went wrong. Please try again.

                                            Thanks for your feedback!

                                            Refer us and get $10 in 3 simple steps!

                                            ステップ1

                                            Get link

                                            Get a free personal referral link here

                                            ステップ2:

                                            Give $10

                                            Your user signs up and upgrade using link

                                            ステップ3

                                            Get $10

                                            1,250 free SMSes
                                            OR 1,000 free voice mins
                                            OR 12,000 chats
                                            OR more