Reverse Phone API

Overview

Identify, enhance, and update records from a single data attribute. Leverage over 30+ years of address history, 600M+ phone-to-person matches, 275M unique person-to-address matches, and more. A Reverse Phone request allows you to find all the locations, persons, or businesses associated with a phone number. Using a RESTful GET API request, you’ll receive every detail related to the number given.

Get a Free API Key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.0/phone?phone=2069735100&api_key=API_KEY

All parameters are case sensitive.

Request Parameters

ParametersDescriptionExamples
api_keySee here to acquire an API key. REQUIRED
phoneContains a raw unparsed or a formatted phone number. The best way to provide phone number is E.164 format. REQUIRED

+12069735184
2069735184 or 12069735184 or 206-601-3561

country_hintOptional. 2 digit country code. To be used when you provide the phone number in local format

BR or MX

Response

A Reverse Phone response is formatted as follows:

Click the # to see that field used within the example JSON response.

Reverse Phone Response

1phone_numberString

Copy
"phone_number": "2069735100"
Complete undecorated phone number without extension or country code. Example: “2065551212”

2is_validBoolean

Copy
"is_valid": true
If false, this is an invalid phone number. Reasons include invalid or missing area code, invalid country code, too short or too long number.
If true, indicates a valid phone number.
If null, current validity of this number is not known.

3country_calling_codeString

Copy
"country_calling_code": "1"
International country code (Spec: ITU-T E.164). Example: “1” for USA & Canada

4line_typeString

Copy
"line_type": "NonFixedVOIP"
Line type can be any of the following:

  • Landline: Traditional wired phone line
  • FixedVOIP: VOIP based fixed line phones
  • Mobile: Wireless phone line
  • Voicemail: Voicemail-only service
  • TollFree: Callee pays for call
  • Premium: Caller pays a premium for the call–e.g. 976 area code
  • NonFixedVOIP: Skype, for example
  • Other: Anything that does not match the previous categories
5carrierString

Copy
"carrier": "tw telecom"
The company that provides voice and/or data services for this phone number. Example: “AT&T Wireless”

6is_prepaidBoolean

Copy
"is_prepaid": false
If true, phone number is associated to a prepaid phone account
If false, phone number is not associated with a prepaid phone account.
If null, the prepaid status of the phone is not known.

7is_commercialBoolean

Copy
"is_commercial": false
If true, phone number is associated to a business. Possible values are true, false, null.

8belongs_toArray

Copy
"belongs_to":[
{
"name": "Whitepages",
"age_range": null,
"gender": null,
"type": "Business"
}
]
A list of people and/or business entities associated with this phone number.

9current_addressesArray

A list of unique current locations associated with people and businesses in belongs_to array. This will include:

  • Location type - String - Address, ZipPlus4, CityPostalCode, PostalCode, State, Country
  • Full Address including City, State, Postal Code
  • Lat/Long of the location
    • latitude - String - Decimal latitude
    • longitude - String - Decimal longitude
    • accuracy - Set - Represents the qualitative accuracy of the lat-long for the location. RoofTop, Street, PostalCode, City, State, Country.
  • Single/Multi-Unit, Is address active, etc.
10associated_peopleArray

A list of related and associated people to people and businesses in belongs_to array.

This will include

  • id
  • name of the associated person
  • relation: how this person related to phone owner
11alternate_phonesArray

This will include an array of alternate phone numbers for people and businesses in belongs_to array.

12warningsArray

An array of strings with validation warnings. Possible values are

  • Invalid Input
  • Missing Input
  • Invalid phone.county_hint value. Only Alpha-2 and Alpha-3 supported

Example

Request

Copy
https://proapi.whitepages.com/3.0/phone?phone=2069735100&api_key=API_KEY

Response

Copy
{
"phone_number": "2069735100",
"is_valid": true,
"country_calling_code": "1",
"line_type": "NonFixedVOIP",
"carrier": "Level 3 Communications",
"is_prepaid": false,
"is_commercial": true,
"belongs_to": [
{
"name": "Whitepages",
"age_range": null,
"gender": null,
"type": "Business"
},
{
"name": "Whitepages Inc",
"age_range": null,
"gender": null,
"type": "Business"
}
],
"current_addresses": [
{
"location_type": "Address",
"street_line_1": "1301 5th Ave Ste 1600",
"street_line_2": null,
"city": "Seattle",
"postal_code": "98101",
"zip4": "2625",
"state_code": "WA",
"country_code": "US",
"lat_long": {
"latitude": 47.608624,
"longitude": -122.334442,
"accuracy": "RoofTop"
},
"is_active": true,
"delivery_point": "MultiUnit"
}
],
"associated_people": [],
"alternate_phones": [
"8003361327"
],
"warnings": []
}