Fetch phone number

GET /v2/PhoneNumbers/{PhoneNumber}
Account sid auth token

Query information on a phone number so that you can make a trusted interaction with your user

Path parameters

  • PhoneNumber string Required

    The phone number to lookup in E.164 or national format. Default country code is +1 (North America).

Query parameters

  • Fields string

    A comma-separated list of fields to return. Possible values are validation, caller_name, sim_swap, call_forwarding, line_status, line_type_intelligence, identity_match, reassigned_number, sms_pumping_risk, phone_number_quality_score, pre_fill.

  • CountryCode string

    The country code used if the phone number provided is in national format.

  • FirstName string

    User’s first name. This query parameter is only used (optionally) for identity_match package requests.

  • LastName string

    User’s last name. This query parameter is only used (optionally) for identity_match package requests.

  • AddressLine1 string

    User’s first address line. This query parameter is only used (optionally) for identity_match package requests.

  • AddressLine2 string

    User’s second address line. This query parameter is only used (optionally) for identity_match package requests.

  • City string

    User’s city. This query parameter is only used (optionally) for identity_match package requests.

  • State string

    User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests.

  • PostalCode string

    User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests.

  • AddressCountryCode string(iso-country-code)

    User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests.

  • NationalId string

    User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests.

  • DateOfBirth string

    User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests.

  • LastVerifiedDate string

    The date you obtained consent to call or text the end-user of the phone number or a date on which you are reasonably certain that the end-user could still be reached at that number. This query parameter is only used (optionally) for reassigned_number package requests.

  • VerificationSid string

    The unique identifier associated with a verification process through verify API. This query parameter is only used (optionally) for pre_fill package requests.

  • PartnerSubId string

    The optional partnerSubId parameter to provide context for your sub-accounts, tenantIDs, sender IDs or other segmentation, enhancing the accuracy of the risk analysis.

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
    • calling_country_code string | null

      International dialing prefix of the phone number defined in the E.164 standard.

    • country_code string | null

      The phone number's ISO country code.

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

    • valid boolean | null

      Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user.

    • validation_errors array[string] | null

      Contains reasons why a phone number is invalid. Possible values: TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER.

      Values are TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, or NOT_A_NUMBER.

    • caller_name object | null

      An object that contains caller name information based on CNAM.

    • sim_swap object | null

      An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number.

    • call_forwarding object | null

      An object that contains information on the unconditional call forwarding status of mobile phone number.

    • line_status object | null

      An object that contains line status information for a mobile phone number.

    • line_type_intelligence object | null

      An object that contains line type information including the carrier name, mobile country code, and mobile network code.

    • identity_match object | null

      An object that contains identity match information. The result of comparing user-provided information including name, address, date of birth, national ID, against authoritative phone-based data sources

    • reassigned_number object | null

      An object that contains reassigned number information. Reassigned Numbers will return a phone number's reassignment status given a phone number and date

    • sms_pumping_risk object | null

      An object that contains information on if a phone number has been currently or previously blocked by Verify Fraud Guard for receiving malicious SMS pumping traffic as well as other signals associated with risky carriers and low conversion rates.

    • phone_number_quality_score object | null

      An object that contains information of a mobile phone number quality score. Quality score will return a risk score about the phone number.

    • pre_fill object | null

      An object that contains pre fill information. pre_fill will return PII information associated with the phone number like first name, last name, address line, country code, state and postal code.

    • url string(uri) | null

      The absolute URL of the resource.
GET /v2/PhoneNumbers/{PhoneNumber} 
curl \
 --request GET 'https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}' \
 --user "username:password"
Response examples (200) 
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+141599299600",
  "valid": false,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": null,
  "phone_number": "+141599299600",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": null,
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": [
    "TOO_LONG"
  ],
  "calling_country_code": null,
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": {
    "error_code": null,
    "caller_name": "Sergio Suarez",
    "caller_type": "CONSUMER"
  },
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": {
    "error_code": null,
    "carrier_name": "Vodafone UK",
    "last_sim_swap": {
      "swapped_period": "PT48H",
      "swapped_in_period": true,
      "last_sim_swap_date": "2020-04-27T10:18:50Z"
    },
    "mobile_country_code": "276",
    "mobile_network_code": "02"
  },
  "caller_name": null,
  "line_status": null,
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": {
    "error_code": null,
    "carrier_name": "Vodafone UK",
    "last_sim_swap": {
      "swapped_period": "PT24H",
      "swapped_in_period": true,
      "last_sim_swap_date": null
    },
    "mobile_country_code": "276",
    "mobile_network_code": "02"
  },
  "caller_name": null,
  "line_status": null,
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": {
    "error_code": null,
    "carrier_name": "Vodafone UK",
    "last_sim_swap": {
      "swapped_period": "PT24H",
      "swapped_in_period": false,
      "last_sim_swap_date": null
    },
    "mobile_country_code": "276",
    "mobile_network_code": "02"
  },
  "caller_name": null,
  "line_status": null,
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": {
    "error_code": null,
    "call_forwarding_status": true
  },
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": {
    "error_code": null,
    "carrier_name": "Vodafone UK",
    "last_sim_swap": {
      "swapped_period": "PT24H",
      "swapped_in_period": true,
      "last_sim_swap_date": "2020-11-05T20:52:09.322Z"
    },
    "mobile_country_code": "276",
    "mobile_network_code": "02"
  },
  "caller_name": null,
  "line_status": null,
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": {
    "error_code": null,
    "call_forwarding_status": true
  },
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": {
    "status": "active",
    "error_code": null
  },
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": {
    "status": "inactive",
    "error_code": null
  },
  "country_code": "GB",
  "phone_number": "+447772000001",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "07772 000001",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "44",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": null,
  "calling_country_code": "1",
  "line_type_intelligence": {
    "type": "nonFixedVoip",
    "error_code": null,
    "carrier_name": "Twilio - SMS/MMS-SVR",
    "mobile_country_code": "240",
    "mobile_network_code": "38"
  },
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": {
    "city_match": "no_match",
    "error_code": null,
    "state_match": "high_partial_match",
    "error_message": null,
    "summary_score": 90,
    "last_name_match": "high_partial_match",
    "first_name_match": "exact_match",
    "national_id_match": "exact_match",
    "postal_code_match": "no_data_available",
    "address_lines_match": "no_match",
    "date_of_birth_match": "exact_match",
    "address_country_match": "exact_match"
  },
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": {
    "error_code": null,
    "number_blocked": false,
    "number_blocked_date": null,
    "carrier_risk_category": "moderate",
    "sms_pumping_risk_score": 61,
    "number_blocked_last_3_months": null
  },
  "reassigned_number": null,
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": {
    "error_code": null,
    "last_verified_date": "2020-12-27",
    "is_number_reassigned": "yes"
  },
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": {
    "error_code": null,
    "last_verified_date": "2019-09-24",
    "is_number_reassigned": "no"
  },
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": {
    "error_code": null,
    "last_verified_date": "2021-12-24",
    "is_number_reassigned": "no_data_available"
  },
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": {
    "error_code": null,
    "quality_score": 0,
    "quality_category": "low",
    "carrier_risk_score": 17,
    "velocity_risk_score": 0,
    "carrier_risk_category": "low",
    "velocity_risk_category": "low",
    "disposable_phone_risk_score": 13,
    "disposable_phone_risk_category": "low"
  }
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": {
    "state": "WA",
    "last_name": "Doe",
    "error_code": null,
    "first_name": "John",
    "postal_code": "98117",
    "address_line": "321 Main Street",
    "country_code": "US"
  },
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": null,
  "reassigned_number": null,
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}
{
  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+14159929960",
  "valid": true,
  "pre_fill": null,
  "sim_swap": null,
  "caller_name": null,
  "line_status": null,
  "country_code": "US",
  "phone_number": "+14159929960",
  "identity_match": null,
  "call_forwarding": null,
  "national_format": "(415) 992-9960",
  "sms_pumping_risk": {
    "error_code": null,
    "number_blocked": false,
    "number_blocked_date": null,
    "carrier_risk_category": "moderate",
    "sms_pumping_risk_score": 61,
    "number_blocked_last_3_months": null
  },
  "reassigned_number": null,
  "validation_errors": [],
  "calling_country_code": "1",
  "line_type_intelligence": null,
  "phone_number_quality_score": null
}