Whitepages Pro API allows direct access to the most comprehensive and accurate data for people and businesses in North America, including the best mobile data available anywhere. Using a RESTful interface, the Whitepages Pro API allows flexible integration into your business systems via JSON. This protocol is simple to use and accessible from any common web programming language on any machine with Internet access.
How Data is Organized: The Identity Graph
The Identity Graph is how Whitepages Pro API represents its dataset. The identity graph is made up of four primary Whitepages types: Person, Business, Phone and Location. Instances of these types are connected by links which describe the relationships between them.
For example, John Smith lives with Jane Smith at 456 Elm Street in Bellevue, WA 98005 and his land-line telephone number is 425-555-5555. This information is available to the API, regardless of whether you make a Find Person , Reverse Phone, or Reverse Location Request.
For example, if you make a Reverse Phone Request for the number 425-555-5555, Whitepages Pro returns the record for the phone number. From the phone number you will follow a link to the address 456 Elm Street, Bellevue, WA 98005. That address contains two links, one to the person information for John Smith and one for the person information for Jane Smith.
This identity graph is valid no matter how you enter it: from the telephone, address, or any of the people, you will observe the same relations between the data and be presented with a similar graph. Only the entry points into the graph – the roots where you begin traversing the graph – will change.
Whitepages controls access to the API and data via an API Key. The API key is the primary data authentication method for your account. Also your usage is recorded and reported via the API Key. You can sign up for an API key here.
We strongly recommend using HTTPS where possible to prevent third parties from acquiring your API key while in use.
The Whitepages ID is a unique value which identifies each record (entity) in the Whitepages dataset. Whitepages IDs can be used to facilitate traversal of the records within a Whitepages Pro API response as well as beyond that response.
Whitepages IDs are made of three parts. First the type of ID, be it Person, Location, Business, or Phone is listed. Next is a UUID for the record. Last is the durability type for this record. Here is a sample of a Whitepages ID:
Durable Whitepages IDs persist within Whitepages databases and can be queried anytime. Ephemeral instances do not exist in our core dataset but arise through calls to 3rd party real-time data services. Their properties and relations with other instances might change between requests.
Pagination and Response Length
As part of the Whitepages API responses, you can control the number of records returned, as well as which record the return starts with, in the original GET request. For example you could start the results with the 9th record found for a location on a busy street, and then only the three records that follow it.
There are 4 data structures within Whitepages dataset. Based on the request and the response schema, one or more ID structures is returned as part of the response.
Phone ID Data Structure
|id||ID||The entity id. REQUIRED|
|line_type||set||Line type can be any of the following:
|belongs_to||data||Entities (people or businesses) that share this phone number. More details on the Person or Business Id data structure can be found below.|
|associated_locations||data||Locations associated with this phone number. Landlines could be a physical address. Mobile numbers will give a less specific location. More details on the Location Id data structure can be found below.|
|is_valid||boolean||If false, this is an invalid phone number. Reasons include invalid or missing area code, invalid country code, invalid subscriber name, too short or too long number.|
|phone_number||string||Complete undecorated phone number without extension or country code. Example: “2065551212”|
|country_calling_code||string||International country code (Spec: ITU-T E.164). Example: “1” for USA & Canada|
|extension||string||The extension (numeric characters only) for the phone number. Example “143”|
|carrier||string||The company that provides voice and/or data services for this phone number. Example: “AT&T Wireless”|
|do_not_call||boolean||If true, for phone number is on the National Do Not Call Registry. Access to this data is restricted to customers who have signed an agreement agreeing to usage terms and conditions.|
|reputation||Reputation of this phone number in a data structure. Higher the level/score for a number, worse its reputation and likelihood of it being a spam/risky number (e.g. Telemarketer, Robocalls, Toll free pumping, Phishing, etc.).
|is_prepaid||boolean||If true, phone number is associated to a prepaid phone account.|
|best_location||ID||The Whitepages id of the best location for this phone_number. More details on the Location Id data structure referenced can be found below.|
Person ID Data Structure
|id||ID||The Whitepages entity id.|
|type||Set||Either “Full” or “LocationMember”. For “Full” all of the fields may be filled in. For “LocationMember”, the relations will be empty.|
|age_range||string||A string describing the persons age in a 5 year range, e.g. 30-34.|
|gender||string||Either “Male” or “Female”.|
|names||data||Name and alias data for this person. The names could include any of the following optional fields:
|locations||data||Current and prior physical addresses for this entity. More details on the Location Id data structure can be found below.|
|phones||data||Current and historical land-line phones for this person. More details on the Phone Id data structure referenced can be found below.|
|best_name||string||A string representing the best name for this person.|
|best_location||ID||The id of the best location for this person.|
|valid_for||data||Date range the Person has been associated with phone or location.
|is_historical||bool||If true, this number has been associated with phone or location in the past. Otherwise, the person-phone/location association is active.|
Address ID Data Structure
|id||ID||The Whitepages entity id.|
|legal_entities_at||data||Legal entities (people or businesses) that share this address. More details on the Person or Business Id data structure referenced can be found here.|
|city||string||Canonicalized city name. Example: “Olympia”.|
|postal_code||string||5-digit US or 6 digit Canadian zipcode. Example: “92019” or “S3D 3F3”.|
|zip4||string||4-digit US zipcode extension. Example: “1020”.|
|state_code||string||2 character US state/territory code (ISO 3166-2:US) or Canadian province code (ISO 3166-2:CA). Examples: “WA” for Washington State or “BC” for British Columbia.|
|country_code||string||Country code (ISO 3166-1 alpha-2), Example: “US”.|
|address||string||The complete street address, including both lines as appropriate. Example: “S 123 Huron Ave SE, Apt 1-A”.|
|house||string||House Number. Example: “123”.|
|street_name||string||Street Name. Example “Huron” in “135 NW Huron Ave”.|
|street_type||string||Canonical street type Example: “Ave” in “NW 45th Ave”.|
|pre_dir||string||Directional modifier preceding street name Example: “NW” in “NW 45th Str”.|
|post_dir||string||Directional modifier following a street type Example: “NW” in “3rd Ave NW”.|
|apt_number||string||Number of the apartment or suite Example: “1-A”.|
|apt_type||string||Canonical name of unit type Examples: “Ste”, “Apt”, “Unit”.|
|box_number||string||PO Box number. If this is not null, then the street_name will be “PO Box”. Example: “1231” in “PO Box 1231”.|
|standard_address_line1||string||Canonicalized and validated address_line1. Contains both primary and the optional secondary address data. Primary address data is either a primary street address data (house_number, pre_dir, street_name, suffix, post_dir) or PO Box line. Secondary address data is apt_type and apt_nnumber. Example: “1301 5th Ave Ste 1600”.|
|standard_address_line2||string||Not currently used. Intended to contain secondary address data.|
|standard_address_location||string||City/state/postal_code data. Example: “Seattle, WA 98101-2625”.|
|is_receiving_mail||bool||Only valid for US address LocationType. If true, then this indicates that the US Postal Service believes that mail delivered to that address will be collected. If false, then the not_receiving_mail_reason field will be set.|
|not_receiving_mail_reason||set||The reason why the is_receiving_mail field value is false. One of:
|usage||set||Only valid for US address LocationType. This indicates the US Postal Service opinion about whether this address is primarily a “Business” or “Residential”.|
|delivery_point||set||Only valid for US address LocationType. Indicates to the US Postal Service whether deliver of mail requires special handling. One of:
|box_type||set||Only valid for US address LocationType. In conjunction with the delivery_point field, this provides additional information to the US Postal Service on how mail is received at this address. One of:
|address_type||set||Only valid for US address LocationType. In conjunction with the delivery_point and box_type fields, this provides additional information about the receiving mail address. One of:
|lat_long||Data||Latitude, longitude and accuracy of this location in a data structure. For locations larger than addresses, this is the centroid of the location area.
|is_deliverable||bool||Only valid for a LocationType “address”. Indicates whether the Postal Service can deliver mail to this address.|
Business ID Data Structure
|id||ID||The Whitepages entity id.|
|name||string||Name for this business|
|locations||data||Current physical addresses for this entity. More details on the Location Id data structure referenced can be found below.|
|phones||data||Current phones for this person. More details on the Location Id data structure referenced can be found below.|