Find Person 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 Find Person request allows you to identify a single person and find details including demographics, location and phones associated with that person. Using a RESTful GET API request, you’ll receive every record related to the name given. Of course, the more complete the information given the more specific the results.

Get a Free API Key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.0/person?name=Drama+Number&address.city=Ashland&address.state_code=MT&api_key=KEYVAL

All parameters are case sensitive. api_key, name, and at least one address parameter is required for a Find Person Request. It is recommended to include name and address.posta_code or name, address.city and address.state_code at minimum.

REQUEST PARAMETERS

ParametersDescriptionExamples
api_keySee here to acquire an API key. REQUIRED
namePerson name as a single parameter

Jane Smith

address.street_line_1Number and street name

2808 Nero Blvd

address.street_line_2Apartment or other additional address information

Apt 265
Box 34Rs

address.cityCity name

Seattle

address.postal_code5 or 9 digit US or 6 digit Canadian zip code

92019 or S3D 3F3

address.state_code2 character state code

WA

address.country_codeNormalized country code

CA or US

search_metrobooleanParameter to control search area. When partial address is provided you can request to expand search area to include the metropolitan area. When paramter is not in the request default value is true.

true or false

search_historicalbooleanParameter to control which addresses should be considered a match. works with partial and full addresses. Used to include person historical locations in the search. When parameter is not in the request default value is true.

true or false

Response

A Find Person response is formatted as follows.

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

Find Person Response

1count_personInteger

Copy
"count_person":2
Total number of people found.

2personArray of objects

Each object defined in the table below.

Copy
{
"id": "Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable",
"name": "Drama Number",
"firstname": "Drama",
"middlename": null,
"lastname": "Number",
"age_range": "55-59",
"gender": null,
"found_at_address": null,
"current_addresses": [
{
"id": "Location.1c6c0b7e-fd4b-4d98-ae4a-9fbdfea3f2a4.Durable",
"location_type": "Address",
"street_line_1": "",
"street_line_2": null,
"city": "Ashland",
"postal_code": "59004",
"zip4": null,
"state_code": "MT",
"country_code": "US",
"lat_long": {
"latitude": 37.27268,
"longitude": -115.808601,
"accuracy": "RoofTop"
},
"is_active": true,
"delivery_point": null,
"link_to_person_start_date": null
}
],
"historical_addresses": [],
"phones": [
{
"id": "Phone.8bcb6fef-a2df-4b08-cfe3-bc7128b6f5e7.Durable",
"phone_number": "+12062796261"
}
],
"associated_people": [],
}

3warningsArray

Copy
"warnings":["Partial Address"]
Array o warnings messages describing search and input address validation. Possible values are:

  • Missing Input Name
  • Missing Input Address
  • Invalid Country Code
  • International Address
  • Partial Address
4errorObject
Copy
"error": null

Person Object

1idString
Copy
"id": "Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable"

Id of the person.

2nameString
Copy
"name": "Drama Number"

Full name of the person.

3firstnameString
Copy
"firstname": "Drama"

First name of the person.

4middlenameString
Copy
"middlename": null

Middle name of the person.

5lastnameString
Copy
"lastname": "Number"

Last name of the person.

6age_rangeString
Copy
"age_range": "55-59"

Age range of the person.

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

7genderString
Copy
"gender": null

Gender of the person.
Possible returns include: Male, Female, null

8current_addressesArray of objects

A list of unique current locations associated with person

idString
Copy
"id": "Location.1c6c0b7e-fd4b-4d98-ae4a-9fbdfea3f2a4.Durable"

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

location_typeString
Copy
"location_type": "Address"

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

street_line_1String
Copy
"street_line_1": ""

Street line 1 of the current address, person is associated with. Value includes building number and street name. Can include secondary address if applicable.

street_line_2String
Copy
"street_line_2": null

Street line 2 reserved. Always null.

cityString
Copy
"city": "Ashland"

City of the current address person is associated with.

postal_codeString
Copy
"postal_code": "59004"

Postal code of the current address person is associated with.

zip4String
Copy
"zip4": null

zip4 of the current address person is associated with.

state_codeString
Copy
"state_code": "MT"

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

country_codeString
Copy
"country_code": "US"

Alpha-2 country code of the current address person 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:

  • Commercial mail drop
  • Multi unit
  • Single unit
  • PO box
  • PO box throwback
  • Unknown address type
9historical_addressesArray of objects

A list of unique historical locations associated with person. Format is the same as current_addresses

10phonesArray
Copy
"phones": [
{
"id": "Phone.8bcb6fef-a2df-4b08-cfe3-bc7128b6f5e7.Durable",
"phone_number": "+12062796261"
}
]

Includes id of the phone and phone number in E.164 which belongs to the person.

11associated_peopleArray

A list of related and associated people to person.

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 the found person
Possible relation values include:

  • Sibling
  • Parent_Child
  • Grandparent_Grandchild
  • Spouse
  • SiblingInLaw
  • ParentInLaw_ChildInLaw
  • AuntOrUncle_NieceOrNephew
  • Associate
  • Relative
  • Household

Response

Copy
{
"count_person": 2,
"person": [
{
"id": "Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable",
"name": "Drama Number",
"firstname": "Drama",
"middlename": null,
"lastname": "Number",
"age_range": "55-59",
"gender": null,
"current_addresses": [
{
"id": "Location.1c6c0b7e-fd4b-4d98-ae4a-9fbdfea3f2a4.Durable",
"location_type": "Address",
"street_line_1": "",
"street_line_2": null,
"city": "Ashland",
"postal_code": "59004",
"zip4": null,
"state_code": "MT",
"country_code": "US",
"lat_long": {
"latitude": 37.27268,
"longitude": -115.808601,
"accuracy": "RoofTop"
},
"is_active": true,
"delivery_point": null
}
],
"historical_addresses": [],
"phones": [
{
"id": "Phone.8bcb6fef-a2df-4b08-cfe3-bc7128b6f5e7.Durable",
"phone_number": "+12062796261"
}
],
"associated_people": []
},
{
"id": "Person.28a0966a-dab2-4663-8e23-bfff63974ff6.Durable",
"name": "Drama Number",
"firstname": "Drama",
"middlename": null,
"lastname": "Number",
"age_range": "65+",
"gender": null,
"current_addresses": [
{
"id": "Location.827f919b-0f58-4f72-a09a-5542470ed4c0.Durable",
"location_type": "Address",
"street_line_1": "",
"street_line_2": null,
"city": "Ashland",
"postal_code": "59004",
"zip4": null,
"state_code": "MT",
"country_code": "US",
"lat_long": {
"latitude": 37.27268,
"longitude": -115.808601,
"accuracy": "RoofTop"
},
"is_active": true,
"delivery_point": null
}
],
"historical_addresses": [],
"phones": [
{
"id": "Phone.15416fef-a2e0-4b08-cfe3-bc7128b7fb4d.Durable",
"phone_number": "+14255550112"
},
{
"id": "Phone.3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable",
"phone_number": "+16464806649"
}
],
"associated_people": []
}
],
"warnings": [
"Partial Address"
],
"error": null
}