Entity Shapes by Context
The same entity comes back in different shapes depending on the endpoint. Do not assume one shape.
The same entity does not come back the same way everywhere. A person from one endpoint and a person from another are different shapes — and so are addresses. This page exists to make that one caveat unmistakable; for the exact fields, read the type document for the endpoint you are calling.
Do not assume one shape. A type you build from one endpoint's response will not fit another's. Always read the endpoint's type document for the shape it actually returns.
A person comes back in three kinds
- Fetched by id —
GET /v2/person/{id}returns the full person record. - As a search result —
GET /v2/person/returns persons as scored, paginated results. Same entity, presented with relevance and list context. - Embedded in a property — owners and residents inside a property response are a reduced form of a person, not the full record.
These are not interchangeable. The embedded form in particular carries far less than the full record.
Reduced forms carry an id. When you get a person embedded in a property
response and need the full record, hydrate it with GET /v2/person/{id}. Each
embedded person also carries a metadata block naming how many phones and
emails were held back and a details_url pointing at that same record, so you
can tell whether hydrating is worth a request.
Addresses also differ by context
An address is not one shape either: a person's address and a property's own address carry different fields. As with persons, do not reuse one address type across endpoints — check the type document for the endpoint you are calling.
Related
Capability Map
Map a user's intent to the exact endpoint and parameters that answer it.
Integration Guide
The workflow to follow when integrating the Whitepages Pro API, by hand or with an agent.
Gets person details by id
Retrieve detailed person information by Whitepages person ID.
Get property details by ID or APN
Retrieve a property by property ID, address ID, or APN. Returns the full record, including tax assessment, mortgage history, and current residents. A Whitepages identifier is 11 characters; anything else is read as an APN. An APN is unique only within a county, so one naming several properties returns a `409` listing the candidates.
Find the Owner
Get the owners of a single property and see which parcel the answer came from