New: look up a phone number on its own endpoint, businesses included. See what's changed →
Whitepages Pro API
DocumentationReferencesChangelog
ReferencesPhone V2

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. Parameters ---------- response : Response Carries the canonical form back to the caller. phone : str North American phone number in any common format. _query_params : EmptyQueryParams Present to reject query parameters; the lookup takes none. Returns ------- PhoneLookupV2ResponseDto The number's facts and the parties associated with it. A path segment that is not a North American number is rejected before any upstream call.

GET
/v2/phone/{phone}

Authorization

ApiKeyAuth

x-api-key<token>

API key for authentication. Get your key from the Whitepages developer portal.

In: header

Path Parameters

phone*string

North American phone number, in any common format. Numbers outside the North American Numbering Plan are not supported.

Example"12065550198"
Example"2065550198"
Example"(206) 555-0198"
Example"206-555-0198"
Example"+1-206-555-0198"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.whitepages.com/v2/phone/12065550198"
{
  "phone": {
    "e164": "string",
    "national_format": "string",
    "line_type": "mobile",
    "carrier": "string",
    "primary_owner": "person",
    "returned_people": 0,
    "people_limit": 0,
    "people_truncated": true,
    "returned_businesses": 0
  },
  "people": [
    {
      "id": "string",
      "name": "string",
      "aliases": [
        "string"
      ],
      "is_dead": true,
      "owned_properties": [
        {
          "id": "string",
          "address": "string"
        }
      ],
      "phones": [
        {
          "number": "string",
          "type": "mobile",
          "score": 0
        }
      ],
      "date_of_birth": "string",
      "linkedin_url": "string",
      "company_name": "string",
      "job_title": "string",
      "relatives": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "age": 0,
      "current_addresses": [
        {
          "address_id": "string",
          "full_address": "string",
          "city": "string",
          "state": "string",
          "line1": "string",
          "zip": "string"
        }
      ],
      "historic_addresses": [
        {
          "address_id": "string",
          "full_address": "string",
          "city": "string",
          "state": "string",
          "line1": "string",
          "zip": "string"
        }
      ],
      "match_score": 0,
      "matched_by": [
        "string"
      ],
      "emails": [
        {
          "email": "string",
          "score": 0
        }
      ],
      "result_metadata": {
        "details_url": "string",
        "phones": {
          "displayed": 0,
          "additional": 0
        },
        "emails": {
          "displayed": 0,
          "additional": 0
        },
        "historic_addresses": {
          "displayed": 0,
          "additional": 0
        },
        "owned_properties": {
          "displayed": 0,
          "additional": 0
        }
      }
    }
  ],
  "businesses": [
    {
      "name": "string",
      "addresses": [
        {
          "full_address": "string",
          "line1": "string",
          "city": "string",
          "state": "string",
          "zip": "string",
          "plus4": "string",
          "latlong": {
            "lat": 0,
            "lng": 0
          },
          "is_historical": true
        }
      ],
      "approximate_locations": [
        {
          "city": "string",
          "state": "string",
          "zip": "string",
          "plus4": "string",
          "country": "string",
          "latlong": {
            "lat": 0,
            "lng": 0
          },
          "is_historical": true,
          "precision": "zip4"
        }
      ]
    }
  ]
}
{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "long_message": "Invalid person ID format: 'sdf'. Person ID must start with 'P' followed by exactly 10 alphanumeric characters. Example: 'PABcd12345e' or 'P1234567890'.",
    "meta": null
  },
  "wp_trace_id": "3b0b537a60d84057817bb40563ca5c99"
}
{
  "message": "Forbidden"
}
{
  "error": {
    "code": 422,
    "message": "Unprocessable Entity",
    "long_message": "The request contains semantic errors and cannot be processed",
    "meta": null
  },
  "wp_trace_id": "7e5f2c9a1d8b4e6f9c0a3b5d7e1f2a4c"
}
{
  "message": "Too Many Requests",
  "error": "usage_cap_exceeded",
  "error_instance_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "limit": 1000,
  "used": 1000,
  "reset_at": "2026-09-01T00:00:00+00:00",
  "upgrade_url": "https://www.whitepages.com/billing/manage-plan/pro-api"
}
{
  "error": {
    "code": 500,
    "message": "Internal Server Error",
    "long_message": "An internal server error occurred",
    "meta": null
  },
  "wp_trace_id": "9c1a4e7f2b8d4c6a9e0f3b5d7c1a2e4f"
}

Related

Reverse Phone Lookup

Find out what a phone number is and who it belongs to

Capability Map

Map a user's intent to the exact endpoint and parameters that answer it.

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

Retrieve person information with match scores and enriched emails. Raises ------ StrictMatchWithFuzzyMatchingError If ``strict_match`` and ``include_fuzzy_matching`` are both set to true — the two flags are semantically contradictory.

Authentication

Learn how to authenticate your requests to the Whitepages Pro API.

Rate Limits

Understand the rate limiting policies for the Whitepages Pro API, including monthly query limits and trial exhaustion.