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

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

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

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, Longitude, and location accuracy of the current address, person 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
9phonesArray
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.

10associated_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 phone owner.
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
}
],
"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
}
],
"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
}