Fetch phone number

GET /v1/PhoneNumbers/{PhoneNumber}

Account sid auth token

Detailed information on phone numbers

Path parameters

PhoneNumber string Required

The phone number to lookup in E.164 format, which consists of a + followed by the country code and subscriber number.

Query parameters

CountryCode string

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 array[string]

The type of information to return. Can be: carrier or caller-name. The default is null. To retrieve both types of information, specify this parameter twice; once with carrier and once with caller-name as the value.
AddOns array[string]

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 object(prefixed-collapsible-map-AddOns)

Data specific to the add-on you would like to invoke. The content and format of this value depends on the add-on.

Responses

200 application/json

OK
Hide headers attributes Show headers attributes
- Access-Control-Allow-Origin string
  
  Specify the origin(s) allowed to access the resource
- Access-Control-Allow-Methods string
  
  Specify the HTTP methods allowed when accessing the resource
- Access-Control-Allow-Headers string
  
  Specify the headers allowed when accessing the resource
- Access-Control-Allow-Credentials boolean
  
  Indicates whether the browser should include credentials
- Access-Control-Expose-Headers string
  
  Headers exposed to the client
Hide response attributes Show response attributes object
- caller_name object | null
  
  The name of the phone number's owner. If null, that information was not available.
- country_code string | null
  
  The ISO country code for the phone number.
- phone_number string(phone-number) | null
  
  The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.
- national_format string | null
  
  The phone number, in national format.
- carrier object | null
  
  The telecom company that provides the phone number.
- add_ons object | null
  
  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 string(uri) | null
  
  The absolute URL of the resource.

GET /v1/PhoneNumbers/{PhoneNumber}

curl \
 --request GET 'https://lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber}' \
 --user "username:password"

Response examples (200)

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310",
  "add_ons": null,
  "carrier": null,
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+15108675310",
  "national_format": "(510) 867-5310"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310",
  "add_ons": null,
  "carrier": {
    "name": "verizon",
    "type": "mobile",
    "error_code": null,
    "mobile_country_code": "310",
    "mobile_network_code": "456"
  },
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+15108675310",
  "national_format": "(510) 867-5310"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+4402077651182",
  "add_ons": null,
  "carrier": {
    "name": "Vodafone Business Solutions",
    "type": "landline",
    "error_code": null,
    "mobile_country_code": null,
    "mobile_network_code": null
  },
  "caller_name": null,
  "country_code": "GB",
  "phone_number": "+4402077651182",
  "national_format": "020 7765 1182"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310",
  "add_ons": null,
  "carrier": null,
  "caller_name": {
    "error_code": null,
    "caller_name": "Delicious Cheese Cake",
    "caller_type": "CONSUMER"
  },
  "country_code": "US",
  "phone_number": "+15108675310",
  "national_format": "(510) 867-5310"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310",
  "add_ons": {
    "code": null,
    "status": "successful",
    "message": null,
    "results": {}
  },
  "carrier": {
    "name": "verizon",
    "type": "mobile",
    "error_code": null,
    "mobile_country_code": "310",
    "mobile_network_code": "456"
  },
  "caller_name": {
    "error_code": null,
    "caller_name": "Delicious Cheese Cake",
    "caller_type": "CONSUMER"
  },
  "country_code": "US",
  "phone_number": "+15108675310",
  "national_format": "(510) 867-5310"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+12127363100",
  "add_ons": {
    "code": null,
    "status": "successful",
    "message": null,
    "results": {
      "whitepages_pro_caller_id": {
        "code": null,
        "result": {
          "id": "Phone.f8396fef-1234-5678-bc7128b6fd99",
          "error": null,
          "carrier": "Level 3 Communications",
          "is_valid": true,
          "warnings": [],
          "line_type": "NonFixedVOIP",
          "belongs_to": [],
          "is_prepaid": false,
          "phone_number": "2127363100",
          "is_commercial": true,
          "alternate_phones": [],
          "associated_people": [],
          "current_addresses": [
            {
              "id": "Location.4e81b857-1234-5678-31d29a3301e1",
              "city": "New York",
              "zip4": "0110",
              "lat_long": {
                "accuracy": "RoofTop",
                "latitude": 40.748731,
                "longitude": -73.986413
              },
              "is_active": null,
              "state_code": "NY",
              "postal_code": "10118",
              "country_code": "US",
              "location_type": "Address",
              "street_line_1": "350 5th Ave",
              "street_line_2": null,
              "delivery_point": "MultiUnit",
              "link_to_person_start_date": "2018-08-28"
            }
          ],
          "country_calling_code": "1",
          "historical_addresses": []
        },
        "status": "successful",
        "message": null,
        "request_sid": "XR28b8f152ae12345605b0b3cc34123456"
      }
    }
  },
  "carrier": null,
  "caller_name": {
    "error_code": null,
    "caller_name": "EMPIRE STATE BUILDING",
    "caller_type": "BUSINESS"
  },
  "country_code": "US",
  "phone_number": "+12127363100",
  "national_format": "(212) 736-3100"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+19892008374",
  "add_ons": {
    "code": null,
    "status": "successful",
    "message": null,
    "results": {
      "nomorobo_spamscore": {
        "code": null,
        "result": {
          "score": 1,
          "status": "success",
          "message": "success"
        },
        "status": "successful",
        "message": null,
        "request_sid": "XR763c8acc4c56d5e3e18d2f0f12345bc1"
      }
    }
  },
  "carrier": {
    "name": "Ytel/Blitz",
    "type": "mobile",
    "error_code": null,
    "mobile_country_code": "310",
    "mobile_network_code": null
  },
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+19892008374",
  "national_format": "(989) 200-8374"
}

{
  "url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000",
  "add_ons": {
    "code": null,
    "status": "successful",
    "message": null,
    "results": {
      "payfone_tcpa_compliance": {
        "code": null,
        "result": {
          "Status": 0,
          "Response": {
            "MSISDNType": "NonFixedVoIP",
            "NumberMatch": "I",
            "VerifyNumberTransactionId": "2019459819"
          },
          "RequestId": "XRd3a2991c9108bde3ca9589ed84d31463",
          "Description": "Success."
        },
        "status": "successful",
        "message": null,
        "request_sid": "XRd3a2991c9108bde3ca9589ed84d31463"
      }
    }
  },
  "carrier": {
    "name": "Level 3 Communications, LLC",
    "type": "landline",
    "error_code": null,
    "mobile_country_code": null,
    "mobile_network_code": null
  },
  "caller_name": null,
  "country_code": "US",
  "phone_number": "+16502530000",
  "national_format": "(650) 253-0000"
}