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/2.2/person.json?name=Drama+Number&city=ashland&state_code=mt&api_key=KEYVAL

All parameters are case sensitive. api_key and at least one name parameter is required for a Find Person Request.

REQUEST PARAMETERS

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

Jane Smith

first_namePerson’s first name

Jane

middle_nameCould be name or initial

R

last_namePerson’s surname

Smith

street_line_1Number and street name

2808 Nero Blvd

street_line_2Apartment or other additional address information

Apt 265
Box 34Rs

cityCity name

Seattle

postal_code5 or 9 digit US or 6 digit Canadian zip code

92019 or S3D 3F3

state_code2 character state code

WA

country_codeNormalized country code

CA or US

use_historicalSearch person using historical address match

true

use_metroExpand search to metro/suburban area of a given city/state or zip

true

Response

A Find Person response is formatted as follows.

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

Find Person Response

1idID

Copy
"id":{
"key":"Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable",
"type":"Person"
}
The Whitepages entity id.

2namesObject

Name and alias data for this person. The names could include any of the following optional fields:

salutationString

Copy
salutation: null

eg: Mr. Mrs, Dr.

first_nameString

Copy
first_name: "Drama"

First name

middle_nameString

Copy
middle_name: null

Middle Initial

last_nameString

Copy
last_name: "Number"

Last name

suffixString

Copy
suffix: null

e.g.:Sr, Jr

3age_rangeString

Copy
"age_range":{
"start":55
"end":59

A string describing the person’s age in a 5 year range, e.g. 30-34

4genderString

Copy
gender: null

Either “Male” or “Female”

5locationsArray

Current and prior physical addresses for this entity. More details on the Location ID data structure can be found here.

6phonesArray

Current and historical land-line phones for this person. More details on the Phone Id data structure referenced can be found here.

Example

Request

Copy
https://proapi.whitepages.com/2.2/person.json?name=Drama+Number&city=ashland&state_code=mt&api_key=KEYVAL

Response

Copy
{
"results":[
{
"id":{
"key":"Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable",
"type":"Person"
},
"names":[
{
"salutation":null,
"first_name":"Drama",
"middle_name":null,
"last_name":"Number",
"suffix":null,
"valid_for":null
}
],
"age_range":{
"start":55,
"end":59
},
"gender":null,
"locations":[
{
"id":{
"key":"Location.1c6c0b7e-fd4b-4d98-ae4a-9fbdfea3f2a4.Durable",
"type":"Location"
},
"type":"Address",
"valid_for":null,
"legal_entities_at":[
{
"id":{
"key":"Person.f9640101-4157-41f5-a48b-86372e9c2acd.Durable",
"type":"Person"
},
"names":[
{
"salutation":null,
"first_name":"Drama",
"middle_name":null,
"last_name":"Number",
"suffix":null,
"valid_for":null
}
],
"age_range":{
"start":55,
"end":59
},
"gender":null,
"locations":null,
"phones":null
}
],
"city":"Ashland",
"postal_code":"59004",
"zip4":null,
"state_code":"MT",
"country_code":"US",
"is_receiving_mail":true,
"not_receiving_mail_reason":null,
"usage":null,
"delivery_point":null,
"address_type":null,
"lat_long":{
"latitude":37.27268,
"longitude":-115.808601,
"accuracy":"RoofTop"
},
"is_deliverable":true,
"standard_address_line1":"",
"standard_address_line2":"",
"is_historical":false,
"contact_creation_date":1363219200
}
],
"phones":[
{
"id":{
"key":"Phone.8bcb6fef-a2df-4b08-cfe3-bc7128b6f5e7.Durable",
"type":"Phone"
},
"line_type":null,
"belongs_to":null,
"associated_locations":null,
"is_valid":true,
"phone_number":"2062796261",
"country_calling_code":"1",
"extension":null,
"carrier":null,
"do_not_call":false,
"reputation":null,
"is_prepaid":null,
"is_connected":null,
"valid_for":null,
"contact_type":"Home",
"contact_creation_date":1363219200
}
]
},
{
"id":{
"key":"Person.28a0966a-dab2-4663-8e23-bfff63974ff6.Durable",
"type":"Person"
},
"names":[
{
"salutation":null,
"first_name":"Drama",
"middle_name":null,
"last_name":"Number",
"suffix":null,
"valid_for":null
}
],
"age_range":{
"start":65,
"end":200
},
"gender":null,
"locations":[
{
"id":{
"key":"Location.827f919b-0f58-4f72-a09a-5542470ed4c0.Durable",
"type":"Location"
},
"type":"Address",
"valid_for":null,
"legal_entities_at":[
{
"id":{
"key":"Person.28a0966a-dab2-4663-8e23-bfff63974ff6.Durable",
"type":"Person"
},
"names":[
{
"salutation":null,
"first_name":"Drama",
"middle_name":null,
"last_name":"Number",
"suffix":null,
"valid_for":null
}
],
"age_range":{
"start":65,
"end":200
},
"gender":null,
"locations":null,
"phones":null
}
],
"city":"Ashland",
"postal_code":"59004",
"zip4":null,
"state_code":"MT",
"country_code":"US",
"is_receiving_mail":true,
"not_receiving_mail_reason":null,
"usage":null,
"delivery_point":null,
"address_type":null,
"lat_long":{
"latitude":37.27268,
"longitude":-115.808601,
"accuracy":"RoofTop"
},
"is_deliverable":true,
"standard_address_line1":"",
"standard_address_line2":"",
"is_historical":false,
"contact_creation_date":1363219200
}
],
"phones":[
{
"id":{
"key":"Phone.3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable",
"type":"Phone"
},
"line_type":null,
"belongs_to":null,
"associated_locations":null,
"is_valid":true,
"phone_number":"6464806649",
"country_calling_code":"1",
"extension":null,
"carrier":null,
"do_not_call":false,
"reputation":null,
"is_prepaid":null,
"is_connected":null,
"valid_for":null,
"contact_type":"Home",
"contact_creation_date":1363219200
},
{
"id":{
"key":"Phone.15416fef-a2e0-4b08-cfe3-bc7128b7fb4d.Durable",
"type":"Phone"
},
"line_type":null,
"belongs_to":null,
"associated_locations":null,
"is_valid":true,
"phone_number":"4255550112",
"country_calling_code":"1",
"extension":null,
"carrier":null,
"do_not_call":false,
"reputation":null,
"is_prepaid":null,
"is_connected":null,
"valid_for":null,
"contact_type":"Home",
"contact_creation_date":1363219200
}
]
}
],
"messages":[]
}