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"
}
]
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.

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
}
]

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"

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

Possible values: 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, Latitude, and location accuracy of the current address, person or business is associated with.

Accuracy string represents the qualitative accuracy of the lat-long for the location. Possible values are RoofTop, Street, PostalCode, City, State, Country.

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:

  • Commercial mail drop
  • Multi unit
  • Single unit
  • PO box
  • PO box throwback
  • Unknown address type
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.

13warningsArray

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"
}
],
"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
}
],
"associated_people": [],
"alternate_phones": [],
"warnings": []
}