Reverse Phone Lookup

Two endpoints take a phone number, and they answer different questions.

GET /v2/phone/{phone} answers what is this number — its line type and carrier, and the people and businesses associated with it. Use it when the number is the subject of your question.

GET /v2/person/ with phone= answers which people match this number, ranked, and lets you combine the number with a name or a location. Use it when a person is the subject and the number is one of your criteria.

Look up a number

Request

curl 'https://api.whitepages.com/v2/phone/12065550142' \
  --header 'X-Api-Key: YOUR_API_KEY'

Response

{
  "phone": {
    "e164": "+12065550142",
    "national_format": "(206) 555-0142",
    "line_type": "mobile",
    "carrier": "Example Wireless",
    "primary_owner": "person",
    "returned_people": 1,
    "people_limit": 10,
    "people_truncated": false,
    "returned_businesses": 0
  },
  "people": [
    {
      "id": "P1234567890",
      "name": "John Smith",
      "aliases": ["Jonathan Smith", "Jon Smith"],
      "is_dead": false,
      "age": 40,
      "date_of_birth": "1985-03-00",
      "linkedin_url": "https://www.linkedin.com/in/example-john-smith",
      "company_name": "Acme Corp",
      "job_title": "Software Engineer",
      "match_score": null,
      "matched_by": ["phone"],
      "phones": [
        { "number": "(206) 555-0142", "type": "mobile", "score": 95 },
        { "number": "(206) 555-0177", "type": "landline", "score": 72 }
      ],
      "current_addresses": [
        {
          "address_id": "A9876543210",
          "full_address": "123 Main St Seattle, WA 98101",
          "line1": "123 Main St",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101"
        }
      ],
      "historic_addresses": [
        {
          "address_id": "A1234567890",
          "full_address": "456 Oak Ave Portland, OR 97204",
          "line1": "456 Oak Ave",
          "city": "Portland",
          "state": "OR",
          "zip": "97204"
        }
      ],
      "owned_properties": [
        { "id": "R1234567890", "address": "123 Main St Seattle, WA 98101" }
      ],
      "emails": [
        { "email": "john.smith@example.com", "score": 92 },
        { "email": "jsmith@example.net", "score": 68 }
      ],
      "relatives": [{ "id": "P0987654321", "name": "Jane Smith" }],
      "result_metadata": {
        "details_url": "/v2/person/P1234567890",
        "phones": { "displayed": 2, "additional": 1 },
        "emails": { "displayed": 2, "additional": 0 },
        "historic_addresses": { "displayed": 1, "additional": 3 },
        "owned_properties": { "displayed": 1, "additional": 0 }
      }
    }
  ],
  "businesses": []
}

Example data

Every value on this page is fictitious. Phone numbers come from the 555-01xx range reserved for documentation, and the identifiers are placeholders.

A switchboard

A company line collects everyone who has ever listed it, so people can be long while the number belongs to the business. This is the case primary_owner exists for: it reports business even though ten person records came back.

Response

{
  "phone": {
    "e164": "+12065550188",
    "national_format": "(206) 555-0188",
    "line_type": "landline",
    "carrier": "Example Telecom",
    "primary_owner": "business",
    "returned_people": 10,
    "people_limit": 10,
    "people_truncated": true,
    "returned_businesses": 1
  },
  "people": [
    {
      "id": "P2345678901",
      "name": "Maria Chen",
      "aliases": [],
      "is_dead": false,
      "age": 34,
      "date_of_birth": "1992-07-00",
      "linkedin_url": null,
      "company_name": "Acme Plumbing",
      "job_title": "Dispatcher",
      "match_score": null,
      "matched_by": ["phone"],
      "phones": [
        { "number": "(206) 555-0188", "type": "landline", "score": 61 },
        { "number": "(206) 555-0131", "type": "mobile", "score": 88 }
      ],
      "current_addresses": [
        {
          "address_id": "A2345678901",
          "full_address": "77 Cedar Ln Seattle, WA 98101",
          "line1": "77 Cedar Ln",
          "city": "Seattle",
          "state": "WA",
          "zip": "98101"
        }
      ],
      "historic_addresses": [],
      "owned_properties": [],
      "emails": [{ "email": "m.chen@example.com", "score": 74 }],
      "relatives": [],
      "result_metadata": {
        "details_url": "/v2/person/P2345678901",
        "phones": { "displayed": 2, "additional": 0 },
        "emails": { "displayed": 1, "additional": 0 },
        "historic_addresses": { "displayed": 0, "additional": 0 },
        "owned_properties": { "displayed": 0, "additional": 0 }
      }
    }
  ],
  "businesses": [
    {
      "name": "Acme Plumbing",
      "addresses": [],
      "approximate_locations": [
        {
          "city": "Seattle",
          "state": "WA",
          "zip": "98101",
          "plus4": null,
          "country": null,
          "latlong": { "lat": 47.6062, "lng": -122.3321 },
          "is_historical": false,
          "precision": "zip"
        }
      ]
    }
  ]
}

people is shown with one record for length; the response carries ten, and people_truncated says the ceiling was reached. Note the phone the query matched is pinned first in each record's phones even where another scores higher — (206) 555-0188 scores 61 against the mobile's 88.

Spellings

Any common spelling addresses the same number. These four are one resource and return one body:

/v2/phone/12065550142
/v2/phone/2065550142
/v2/phone/(206)%20555-0142
/v2/phone/%2B1-206-555-0142

The canonical form comes back in the Content-Location response header and is itself callable, so a client that normalises on its own side can follow it instead of writing its own rules.

The endpoint covers the North American Numbering Plan. A number outside it is refused with HTTP 400 rather than searched.

Reading the response

`phone` — the number's own facts

Present on every successful response, including one where nothing is associated with the number. line_type and carrier are resolved by lookup rather than derived from the numbering plan, so an unlisted number still tells you whether it is a mobile, a landline, or toll-free. Toll-free numbers resolve without a carrier and carry null.

A lookup that finds no parties is an answer, not an error — you still learn what kind of line it is.

`primary_owner` — which list to read first

person, business, or unknown.

A kind, not a pointer

primary_owner classifies the line, and business can appear alongside a long people list or an empty businesses list. A switchboard collects everyone who ever listed it, so people count is a poor signal of ownership. Read it as a kind and use both lists.

`businesses`

A business carries its name and, where one is known, its street address. Where no street address is known it carries approximate_locations instead: the postal code or city the business is placed within, with precision naming how closely. The two lists do not overlap — a location is an address or it is approximate.

`people`

Person records in the same shape person search returns. match_score and matched_by appear on every record and are inert here: there is no query for a result to be relevant to.

returned_people is how many this response carries, people_limit is the ceiling that applied, and people_truncated says the ceiling was reached. Truncated with ten returned means at least ten are associated and the true figure is unknown.

Ranking people against a number

When you want person records ranked, or want to combine the number with other criteria, use person search.

Verify that a number belongs to a particular person:

curl 'https://api.whitepages.com/v2/person/?phone=2125550198&name=John%20Smith' \
  --header 'X-Api-Key: YOUR_API_KEY'

Narrow by location:

curl 'https://api.whitepages.com/v2/person/?phone=2125550198&state_code=NY' \
  --header 'X-Api-Key: YOUR_API_KEY'

Matched-first for phone

Because the search input was a phone number, the matching phone is pinned to position 0 of each record's phones list even when it ranks below other phones by confidence score. The phone you queried on always appears above the cap.

Choosing between them

If you want to…	Use
Know the line type or carrier	`GET /v2/phone/{phone}`
Find the business behind a number	`GET /v2/phone/{phone}`
Get an answer even when nobody is associated with the number	`GET /v2/phone/{phone}`
Rank people against the number	`GET /v2/person/`
Confirm a number belongs to a named person	`GET /v2/person/`
Combine the number with an address or age filter	`GET /v2/person/`

Each successful lookup bills one unit on either endpoint, whether or not it found anyone.

Look up what is known about a phone number

Retrieve the number's own facts and the parties associated with it. Several spellings of one number address this resource, so the canonical form goes out in `Content-Location` for a caller normalizing on their side. A path segment that is not a North American number is rejected before any upstream call.

Look up a number

A switchboard

Spellings

Reading the response

`phone` — the number's own facts

`primary_owner` — which list to read first

`businesses`

`people`

Ranking people against a number

Choosing between them

Related

Look up what is known about a phone number

Capability Map

Person Search

Search for a person by name, phone number, and address

Search by Address

On this page