Menu

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

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
  • Carrier Information
  • Caller Name
  • Fraud Information

Fraud Lookup is currently in preview, click here to request access.

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.

http://www.lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber}

The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

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

Authentication

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.

Query Parameters

The following basic GET query string parameters allow you to specify the phone number you want information about and the types of information you’d like:

AddOns
Optional
get string[] Not PII

Indicates the particular Add-on you would like to use to get more information. Possible values are the Add-on Unique Names of Add-ons installed on your account. You can specify multiple instances of this parameter to invoke different Add-ons. See Add-ons documentation for information on installing Add-ons. Add-on pricing is available in your list of Installed Add-ons in the Console.

CountryCode
Optional
get string Not PII

Optional ISO country code of the phone number. This is used to specify the country when the number is provided in a national format.

Type
Optional
get string[] Not PII

Indicates the type of information you would like returned with your request. Possible values are carrier or caller-name. If not specified, the default is null. Carrier information costs $0.005 per phone number looked up. Caller Name information costs $0.01 per phone number looked up, and is currently ONLY available in the US. You can retrieve both types of information by including two Type arguments or making two separate requests.

PREVIEW The Fraud data is currently in preview, click here to request access.

Name Description
Type Indicates the type of data you would like returned with your request. Possible value is fraud. If not specified, the default is null. Fraud costs $0.03 per phone number looked up, and is currently ONLY available in the US.

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

Name Description
AddOns.add_on_unique_name.parameter_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. Note that this Add-on must be invoked in this request using the AddOns parameter above.

Resource Properties

The following properties are always returned:

Loading Code Sample...
      
      
          
          
          
          
        
      Look up a phone number in the E.164 format

      Lookup with E.164 Formatted Number

      Look up a phone number in the E.164 format
      add_ons

      Results of any Add-ons you have specified using the AddOn parameter in the request, as a JSON dictionary. For the format of the dictionary, refer to Using Add-ons 6 section in the Add-ons documentation.

      caller_name
      string_map PII MTL: 60 DAYS

      String indicating the name of the owner of the phone number. If not available, this will return null.

      country_code

      The ISO country code for the phone number.

      national_format

      The phone number, in national format.

      phone_number
      phone_number PII MTL: 60 DAYS

      The phone number, in E.164 format (i.e. "+1").

      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 cannot exist, you will receive an HTTP 404 error.

      Carrier Information

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

      The following additional properties are returned if you requested carrier information in your GET request:

      Name Description
      MobileCountryCode The mobile country code of the carrier (for mobile numbers only).
      MobileNetworkCode The mobile network code of the carrier (for mobile numbers only).
      Name The name of the carrier. Please bear in mind that carriers rebrand themselves constantly and that the names used for carriers will likely change over time.
      Type The phone number type. Possible values are landline, mobile, or voip. See 'Phone Number Type' below for more information.
      ErrorCode The error code, if any, associated with your request.
      Phone Number Types

      The following are the possible values for the 'Type' property.

      Type Description
      landline The phone number is a landline number generally not capable of receiving SMS messages.
      mobile 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.

      Caller Name

      The following additional properties are returned if you requested caller name in your GET request:

      Name Description
      CallerName String indicating the name of the owner of the phone number. If not available, this will return null.
      CallerType String indicating whether this caller is a business or consumer. Possible values are business, consumer. If not available, this will return unavailable.
      ErrorCode The error code, if any, associated with your request.

      Note that Caller Name lookups for US numbers are billed per lookup, even if data may not be available. Currently, requesting Caller Name Lookup for international numbers will return null values, but will not be billed.

      Fraud Information

      The Fraud data is currently in preview, click here to request access.

      The following additional properties are returned if you requested fraud information in your GET request:

      Name Description
      AdvancedLineType The phone number type. Possible values are mobile, landline, fixed_voip, non_fixed_voip, voicemail, toll_free, premium, other and unknown. See 'Phone Number Advance Types' below for more information.
      MobileCountryCode The mobile country code of the carrier (for mobile numbers only).
      MobileNetworkCode The mobile network code of the carrier (for mobile numbers only).
      CallerName String indicating the name of the owner of the phone number. If not available, this will return null.
      IsPorted Boolean indicating if the phone number is ported.
      LastPortedDate The date on which the phone number was ported.
      ErrorCode The error code, if any, associated with your request.
      Phone Number Advance Line Types

      The following are the possible values for the 'AdvanceLineType' property.

      Type Description
      mobile The phone number is a mobile number generally capable of receiving SMS messages.
      landline The phone number is a landline number generally not capable of receiving SMS messages.
      fixed_voip An internet based phone number tied to addresses that may not be capable of receiving SMS messages. For example, Comcast for instance.
      non_fixed_voip An internet based phone number that may or may not be capable of receiving SMS messages. For example, Google Voice.
      voicemail An phone number with Voicemail-only service, not capable of receiving SMS messages.
      toll_free The phone number only capable of receiving Phone calls and the call recipient pays for call.
      premium The caller to the phone number will pay a premium for the call–e.g. 976 area code
      other The phone number type does not match with the previous types described.
      unknown The line type for the phone number cannot be determined.
      Loading Code Sample...
          
          
              
              
              
              
            
          Loading Code Sample...
              
              
                  
                  
                  
                  
                
              Loading Code Sample...
                  
                  
                      
                      
                      
                      
                    
                  Loading Code 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.

                      Loading Code Sample...
                          
                          
                              
                              
                              
                              
                            
                          Loading Code Sample...
                              
                              
                                  
                                  
                                  
                                  
                                
                              Look up a phone number including the Payfone TCPA Compliance Add-on results.

                              Lookup with Add-on enabled

                              Look up a phone number including the Payfone TCPA Compliance Add-on results.

                              Need some help?

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

                              Loading Code Sample...