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

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

1idstring
Copy
"id": "Phone.4d796fef-a2df-4b08-cfe3-bc7128b6f6bb.Durable"

Phone number id.

2phone_numberString

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

3is_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.

4country_calling_codeString

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

5line_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
6carrierString

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

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

8is_commercialBoolean

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

9belongs_toArray

Copy
"belongs_to":[
{
"id": "Business.98cf25f3-96d0-4558-a5f5-7b9fb94ef805.Durable",
"name": "Whitepages",
"firstname": null,
"middlename": null,
"lastname": null,
"age_range": null,
"gender": null,
"type": "Business",
"link_to_phone_start_date": "1992-05-01"
}
]
Primary owner of the phone number. Person or Business. Firstname, middlenama, lastname, age_range, gender are available only for a Person entity.

idString
Copy
"id": "Business.98cf25f3-96d0-4558-a5f5-7b9fb94ef805.Durable"

Id of the Person or Business phone number belongs to.

nameString
Copy
"name": "Whitepages"

Full name of the Person or Business phone number belongs to.

firstnameString
Copy
"firstname": null

First name of the Person phone number belongs to. Always null for Business.

middlenameString
Copy
"middlename": null

Middle name of the Person phone number belongs to. Always null for Business.

lastnameString
Copy
"lastname": null

Last name of the Person phone number belongs to. Always null for Business.

age_rangeString
Copy
"age_range": null

Age range of the Person phone number belongs to. Always null for Business.

Possible returns include: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65+.

genderString
Copy
"gender": null

Gender of the Person phone number belongs to. Always null for Business.

Possible returns include: Male, Female, null

typeString
Copy
"type": "Business"

Type of the entity phone number belongs to

Possible returns include: Person, Business.

link_to_phone_start_datestring
Copy
"link_to_phone_start_date": "1992-05-01"

String with ISO format date when phone got linked to person or business.

10current_addressesArray

Copy
"current_addresses":
[
{
"id": "Location.f680d715-f932-4e68-9e64-9871113a6b81.Durable",
"location_type": "Address",
"street_line_1": "1301 5th Ave",
"street_line_2": null,
"city": "Seattle",
"postal_code": "98101",
"zip4": null,
"state_code": "WA",
"country_code": "US",
"lat_long": {
"latitude": 47.608624,
"longitude": -122.334442,
"accuracy": "RoofTop"
},
"is_active": null,
"delivery_point": null,
"link_to_person_start_date": "1992-05-01"
}
]

A list of unique current locations associated with Person or Business in belongs_to array.

idString
Copy
"id": "Location.f680d715-f932-4e68-9e64-9871113a6b81.Durable"

Location id of the current address, person or business is associated with.

 

location_typeString
Copy
"location_type": "Address"

Part of “current_addresses” string indicating the type of address returned as associated with the phone owner. The most precise address information available will be provided with levels decreasing in precision in the following order: Address, ZipPlus4, CityPostalCode, PostalCode, State, Country.

street_line_1String
Copy
"street_line_1": "1301 5th Ave"

Street line 1 of the current address, person or business is associated with. Value includes building number street name and secondary address

 

street_line_2String
Copy
"street_line_2": null

Street line 2 reserved. Always null

cityString
Copy
"city": "Seattle"

City of the current address, person or business is associated with.

postal_codeString
Copy
"postal_code": "98101"

Postal code of the current address, person or business is associated with.

zip4String
Copy
"zip4": null

zip4 of the current address, person or business is associated with.

state_codeString
Copy
"state_code": "WA"

2 digit state code of the current address, person or business is associated with.

country_codeString
Copy
"country_code": "US"

Alpha-2 country code of the current address, person or business is associated with.

lat_longObject
Copy
"lat_long": {
"latitude": 47.608624,
"longitude": -122.334442,
"accuracy": "RoofTop"
}

Latitude and longitude associated with the returned current address. Includes “accuracy” string that represents the accuracy of the latitude/longitude with levels decreasing in precision in the following order: RoofTop, Street, PostalCode, Neighborhood, City, State, Country.
It is possible for location_type and lat_long accuracy to have varying levels of precision. For example, the location_type may be “Address” while the lat_long provided is mapped only to the location of the “City” of the given address.

is_activeBoolean
Copy
"is_active": true

Indicates if the address is currently receiving mail. Possible values are true, false, or null.

delivery_pointString
Copy
"delivery_point": null

Indicates delivery point for the address. Possible values:

  • CommercialMailDrop
  • MultiUnit
  • SingleUnit
  • POBox
  • POBoxThrowback
  • UnknownAddressType
link_to_person_start_dateString
Copy
"link_to_person_start_date": "1992-05-01"

String with ISO format date when address got linked to person or business.

11associated_peopleArray

A list of related and associated people to person or business in belongs_to array.

Each object in the array will include:

idString

Id of the associated person.

nameString

Full name of the associated person.

relationString

Relation of the associated person to phone owner.
Possible relation values include:

  • Sibling
  • Parent_Child
  • Grandparent_Grandchild
  • Spouse
  • SiblingInLaw
  • ParentInLaw_ChildInLaw
  • AuntOrUncle_NieceOrNephew
  • Associate
  • Relative
  • Household
  • PotentialOwner
12alternate_phonesArray

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

13errorObject

Copy
"error": null

An error message for a phone check. Following error objects may be returned here.
Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}

Copy
{
"name": "AuthError",
"message": "International Phone Number Lookup not authorized"
}

14warningsArray

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
{
"id": "Phone.4d796fef-a2df-4b08-cfe3-bc7128b6f6bb.Durable",
"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": [
{
"id": "Business.98cf25f3-96d0-4558-a5f5-7b9fb94ef805.Durable",
"name": "Whitepages Inc",
"firstname": null,
"middlename": null,
"lastname": null,
"age_range": null,
"gender": null,
"type": "Business",
"link_to_phone_start_date": "1992-05-01"
}
],
"current_addresses": [
{
"id": "Location.f680d715-f932-4e68-9e64-9871113a6b81.Durable",
"location_type": "Address",
"street_line_1": "1301 5th Ave",
"street_line_2": null,
"city": "Seattle",
"postal_code": "98101",
"zip4": null,
"state_code": "WA",
"country_code": "US",
"lat_long": {
"latitude": 47.608624,
"longitude": -122.334442,
"accuracy": "RoofTop"
},
"is_active": null,
"delivery_point": null,
"link_to_person_start_date": "1992-05-01"
}
],
"associated_people": [],
"alternate_phones": [],
"error": null,
"warnings": []
}