diff --git a/Justfile b/Justfile index fc51563..a999b16 100644 --- a/Justfile +++ b/Justfile @@ -56,5 +56,9 @@ lint: bun run lint rg --files -g '*.nix' -g '!.*' -g '!bun.nix' | xargs -L 1 statix check -- +# Check heading case in content/docs/ (house style is sentence case) +check-heading-case: + bun run scripts/check-heading-case.ts + # Run all validation checks. `check-types` pulls in `build` as a dependency. -validate: check-types check-format lint test check-corpus check-bun-nix +validate: check-types check-format lint test check-corpus check-bun-nix check-heading-case diff --git a/README.md b/README.md index 8575ca9..221aaaf 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ Whitepages

-

API Documentation

+

Whitepages Pro API Documentation

- Official documentation for the Whitepages API
+ Official documentation for the Whitepages Pro API.
View Documentation

@@ -15,6 +15,17 @@ --- +## About the Whitepages Pro API + +The Whitepages Pro API is a U.S. people and property data API. It returns phone +numbers, email addresses, current and historical addresses, property ownership, +and residents. The data comes from public and legal records. + +Coverage is United States only, and coverage varies by record. The API is not an +FCRA-regulated product and is not intended for credit, underwriting, employment, +housing, or insurance decisions. See the [Terms of Service](https://www.whitepages.com/terms) +for full details, or contact [api@whitepages.com](mailto:api@whitepages.com) with questions. + ## Development ### Prerequisites diff --git a/bun.lock b/bun.lock index e32f999..15052b8 100644 --- a/bun.lock +++ b/bun.lock @@ -51,6 +51,9 @@ }, }, }, + "patchedDependencies": { + "fumadocs-openapi@10.1.1": "patches/fumadocs-openapi@10.1.1.patch", + }, "packages": { "@alloc/quick-lru": ["@alloc/quick-lru@5.2.0", "", {}, "sha512-UrcABB+4bUrFABwbluTIBErXwvbsU/V7TZWfmbgJfbkwiBuziS9gxdODUyuiecfdGQ85jglMW6juS3+z5TsKLw=="], diff --git a/content/docs/changelog/index.mdx b/content/docs/changelog/index.mdx index c4d8283..382e152 100644 --- a/content/docs/changelog/index.mdx +++ b/content/docs/changelog/index.mdx @@ -65,8 +65,8 @@ The endpoint covers the North American Numbering Plan. A number outside it is refused with HTTP 400 rather than searched. Each successful lookup bills one unit, whether or not it found anyone. -See [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup) -for when to use this endpoint and when person search is still the better fit. +See [Phone Search](/documentation/phone-search) for when to use this endpoint +and when person search is still the better fit. --- @@ -96,7 +96,7 @@ a different address, and `25` when the address you searched for is not deliverable. Both are `null` when the address could not be checked, which happens when the request carries no `street`, or a `street` with neither a `city` nor a `zipcode` to place it. The property is still -returned. See [Property Search](/documentation/property-search#match-confidence). +returned. See [Property Search API](/documentation/property-search#match-confidence). **New `strict_match` request parameter.** Set `strict_match=true` to receive only the address you searched for or an address in the same diff --git a/content/docs/documentation/agentic-guidance/capability-map.mdx b/content/docs/documentation/agentic-guidance/capability-map.mdx index 5dcd5c4..a18ede8 100644 --- a/content/docs/documentation/agentic-guidance/capability-map.mdx +++ b/content/docs/documentation/agentic-guidance/capability-map.mdx @@ -2,6 +2,7 @@ related: - /documentation/agentic-guidance/integration-guide - /documentation/agentic-guidance/entity-shapes + - /documentation/phone-search - /references/person-v2/search_person_by_name_phone_or_address_v2 - /references/property-v2/search_property_v2 title: Capability Map @@ -42,6 +43,7 @@ question you are asking; the row below says which. | ---------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- | | Find out what a phone number is | `GET /v2/phone/{phone}` | path `phone` (any common spelling) | | Rank people against a phone number | `GET /v2/person/` | `phone=`, optionally with `name` or location to narrow | +| Find a person by email | `GET /v2/person/` | `email=`, optionally with `name` or location to narrow | | Find who lives at an address | `GET /v2/person/` | `street`, `city`, `state_code`, `zipcode` | | Find a person by name | `GET /v2/person/` | `name`, or `first_name` / `middle_name` / `last_name` (+ location) | | Narrow a person search | `GET /v2/person/` | `min_age` / `max_age`, `include_fuzzy_matching`, `strict_match`, `include_historical_locations`, `radius` | diff --git a/content/docs/documentation/events/event-payload.mdx b/content/docs/documentation/events/event-payload.mdx index 70f35ad..63e50c8 100644 --- a/content/docs/documentation/events/event-payload.mdx +++ b/content/docs/documentation/events/event-payload.mdx @@ -32,7 +32,7 @@ full event object shown below. -## Top-Level Fields +## Top-level fields | Field | Type | Description | | ------------ | ------ | ----------------------------------------------------------------------------- | @@ -90,7 +90,7 @@ The `property` object contains details about the property involved in the deed e | `lot_sqft` | integer | Lot size in square feet | | `property_purpose` | string | Property type | -### Address Fields +### Address fields | Field | Type | Description | | -------- | ------ | --------------------- | @@ -100,14 +100,14 @@ The `property` object contains details about the property involved in the deed e | `zip` | string | ZIP code | | `county` | string | County name | -### Geolocation Fields +### Geolocation fields | Field | Type | Description | | ----- | ------ | ----------- | | `lat` | number | Latitude | | `lng` | number | Longitude | -### Legal Description Fields +### Legal description fields | Field | Type | Description | | ------ | ------ | ---------------------------------- | @@ -154,7 +154,7 @@ The `parties` array lists individuals or entities involved in the deed transacti | `person_id` | string | No | Whitepages person ID, if resolved | | `addresses` | array | No | Associated addresses | -### Party Address Fields +### Party address fields | Field | Type | Required | Description | | -------------- | ------ | -------- | ---------------------- | @@ -193,14 +193,14 @@ The `detail` object contains transaction-specific information from the deed reco | `consideration` | number | Transaction amount in USD | | `transaction_reason` | object | Transaction classification | -### Document Type Fields +### Document type fields | Field | Type | Description | | ---------- | ------ | -------------------- | | `category` | string | Normalized category | | `text` | string | Human-readable label | -### Transaction Reason Fields +### Transaction reason fields | Field | Type | Description | | ---------- | ------ | -------------------- | @@ -225,7 +225,7 @@ The `detail` object contains transaction-specific information from the deed reco } ``` -## Full Example +## Full example ```json title="Complete event response" { diff --git a/content/docs/documentation/events/event-types.mdx b/content/docs/documentation/events/event-types.mdx index c941743..0efbfcb 100644 --- a/content/docs/documentation/events/event-types.mdx +++ b/content/docs/documentation/events/event-types.mdx @@ -9,7 +9,7 @@ description: Understand the different types of property deed events Every event has an `event_type` field that describes the kind of property deed activity it represents. Event types follow a `category.action` format. -## Available Event Types +## Available event types | Event Type | Description | | ---------- | ------------------------------------------------------------------- | @@ -21,9 +21,9 @@ Every event has an `event_type` field that describes the kind of property deed a subscriptions to automatically receive all current and future event types. -## Using Event Types +## Using event types -### In Webhook Subscriptions +### In webhook subscriptions When [creating a webhook](/documentation/webhooks/create-webhook), the `event_type` parameter controls which events are delivered to your endpoint: @@ -38,7 +38,7 @@ curl -X POST 'https://api.whitepages.com/v1/webhooks/' \ }' ``` -### In Event Payloads +### In event payloads The `event_type` field appears in every event object, whether retrieved directly or delivered via webhook: @@ -51,6 +51,6 @@ The `event_type` field appears in every event object, whether retrieved directly } ``` -## Distinguishing Test Events +## Distinguishing test events Events generated by the [test webhook endpoint](/documentation/webhooks/test-webhook) include a `"test": true` field. Real events do not include this field. Use it to filter test events in your processing pipeline. diff --git a/content/docs/documentation/events/get-event.mdx b/content/docs/documentation/events/get-event.mdx index 75d994a..a1b5182 100644 --- a/content/docs/documentation/events/get-event.mdx +++ b/content/docs/documentation/events/get-event.mdx @@ -16,7 +16,7 @@ Use the `GET /v1/events/{event_id}` endpoint to retrieve a single event by its I Response](/references/support-and-incident-response) page. -## Basic Usage +## Basic usage Retrieve an event by its ID: @@ -25,7 +25,7 @@ curl 'https://api.whitepages.com/v1/events/evt_abc123' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -## Path Parameters +## Path parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------------------- | diff --git a/content/docs/documentation/events/search-events.mdx b/content/docs/documentation/events/search-events.mdx index e351417..c05f06a 100644 --- a/content/docs/documentation/events/search-events.mdx +++ b/content/docs/documentation/events/search-events.mdx @@ -24,7 +24,7 @@ Use `GET /v1/events/deed` to search historical property deed events. Filter by r valid region values, see the [Regions API](/references/regions/list_states). -## Basic Usage +## Basic usage ### All deed events in a county @@ -40,7 +40,7 @@ curl 'https://api.whitepages.com/v1/events/deed?region=county:tx.travis&property --header 'X-Api-Key: YOUR_API_KEY' ``` -## Query Parameters +## Query parameters | Parameter | Type | Required | Description | | ----------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- | diff --git a/content/docs/documentation/getting-started.mdx b/content/docs/documentation/getting-started.mdx index dd79ca0..ccc1f1b 100644 --- a/content/docs/documentation/getting-started.mdx +++ b/content/docs/documentation/getting-started.mdx @@ -9,9 +9,16 @@ description: Get started with the Whitepages Pro API icon: Rocket --- -The Whitepages Pro API provides access to comprehensive person and property data. Whether you're verifying identities, enriching customer records, or researching properties, our API delivers the data you need. +The Whitepages Pro API is a U.S. people and property data API. It returns phone +numbers, email addresses, current and historical addresses, property ownership, +and residents. The data comes from public and legal records. -## Get Your API Key +Coverage is United States only, and coverage varies by record. The API is not an +FCRA-regulated product and is not intended for credit, underwriting, employment, +housing, or insurance decisions. See the [Terms of Service](https://www.whitepages.com/terms) +for full details, or contact [api@whitepages.com](mailto:api@whitepages.com) with questions. + +## Get your API key To access the API, you'll need an API key. Sign up for a **free trial** at [whitepages.com/pro-api](https://www.whitepages.com/pro-api). @@ -32,23 +39,23 @@ To access the API, you'll need an API key. Sign up for a **free trial** at [whit -## Making Requests +## Making requests All API requests require your API key in the `X-Api-Key` header: @@ -59,6 +66,6 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Smith' \ Responses are returned in JSON format. Each successful request consumes one billable query — see [Billing](/references/billing) for the full policy on which responses are billed. -## Next Steps +## Next steps -Ready to make your first API call? Start with the [Person Search](/documentation/person-search) tutorial, or [Phone Lookup](/documentation/person-search/reverse-phone-lookup) if you are starting from a phone number. +Ready to make your first API call? Start with the [Person Search API](/documentation/person-search) tutorial, or [Phone Search](/documentation/phone-search) if you are starting from a phone number. diff --git a/content/docs/documentation/getting-trial-api-key.mdx b/content/docs/documentation/getting-trial-api-key.mdx index dbff32d..fa2e1a5 100644 --- a/content/docs/documentation/getting-trial-api-key.mdx +++ b/content/docs/documentation/getting-trial-api-key.mdx @@ -10,13 +10,13 @@ icon: Key This guide walks you through the process of signing up for a free trial API key. The trial gives you access to all API endpoints so you can evaluate the service before committing to a paid plan. -## Step 1: Visit the API Page +## Step 1: visit the API page Go to [whitepages.com/pro-api](https://www.whitepages.com/pro-api) to access the API signup page. You'll see the "Get API Access" form on the right side of the page. -## Step 2: Enter Your Contact Information +## Step 2: enter your contact information The first form requires three pieces of information: @@ -31,7 +31,7 @@ Fill in your details and click the **Start for Free** button. personal email increases your chances of trial approval and faster processing. -## Step 3: Provide API Usage Details +## Step 3: provide API usage details After submitting your contact information, you'll be asked to provide more details about your API needs. @@ -49,13 +49,13 @@ Click **Access API Trial** to submit your request. completely free during the trial period. -## Step 4: Check Your Email +## Step 4: check your email After submitting the form, you'll see a confirmation message. Check your email for instructions on how to activate your trial key. -## Step 5: Start Using Your API Key +## Step 5: start using your API key Once you receive your API key, you can start making requests immediately. Include your key in the `X-Api-Key` header: @@ -70,7 +70,7 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Smith' \ immediately. -## Trial Limitations +## Trial limitations The trial API key includes: @@ -80,16 +80,16 @@ The trial API key includes: For production use or higher query volumes, visit the [API Pricing](https://www.whitepages.com/pro-api/pricing/plans) page. -## Next Steps +## Next steps diff --git a/content/docs/documentation/making-your-first-request.mdx b/content/docs/documentation/making-your-first-request.mdx index ca1d542..a033597 100644 --- a/content/docs/documentation/making-your-first-request.mdx +++ b/content/docs/documentation/making-your-first-request.mdx @@ -10,13 +10,13 @@ icon: Play Ready to test your API key? Pick the use case that matches what you're building and try it right here in your browser — or follow the step-by-step guide using Postman. -## Try It Now +## Try it now Paste your API key once, then run a sample request for the use case you care about. Each section links to a deeper guide if you want to learn more. -## Using Postman (No Code Required) +## Using Postman (no code required) Postman is a free tool that lets you interact with APIs without writing code. Click the button below to import our pre-configured collection, or follow the manual setup steps. @@ -29,23 +29,23 @@ Postman is a free tool that lets you interact with APIs without writing code. Cl /> -### What You'll Need +### What you'll need - Your Whitepages Pro API key (received via email after [signing up for a trial](/documentation/getting-trial-api-key)) - [Postman](https://www.postman.com/downloads/) (free download) -### Step-by-Step Guide +### Step-by-step guide -### Download and Open Postman +### Download and open Postman Download Postman from [postman.com/downloads](https://www.postman.com/downloads/) and install it. Create a free account or skip sign-in to continue. -### Create a New Request +### Create a new request 1. Click the **+** button to open a new request tab 2. Make sure **GET** is selected in the dropdown (it's the default) @@ -64,7 +64,7 @@ https://api.whitepages.com/v2/person?name=John%20Smith&city=Seattle&state_code=W -### Add Your API Key +### Add your API key 1. Click the **Headers** tab below the URL field 2. In the **Key** column, enter: `X-Api-Key` @@ -77,7 +77,7 @@ https://api.whitepages.com/v2/person?name=John%20Smith&city=Seattle&state_code=W -### Send the Request +### Send the request Click the **Send** button. You should see a JSON response in the panel below. @@ -106,7 +106,7 @@ If you see data like this, your API key is working correctly. -## Using cURL (Command Line) +## Using cURL (command line) If you prefer the command line, you can use cURL: @@ -119,32 +119,32 @@ Replace `YOUR_API_KEY` with your actual API key. ## Troubleshooting -### 403 Forbidden or "Invalid API Key" +### 403 Forbidden or "invalid API key" - Double-check that you copied the entire API key from your email - Verify the header name is exactly `X-Api-Key` (case-sensitive) - Make sure there are no extra spaces before or after your API key -### No Results Found +### No results found A 404 response with no results is normal—it means your API key is working, but no records matched your search. Try different search parameters. -### Need Help? +### Need help? Contact [api@whitepages.com](mailto:api@whitepages.com) if you continue to have issues. -## Next Steps +## Next steps Now that you've made your first request, explore what else you can do: diff --git a/content/docs/documentation/mcp/index.mdx b/content/docs/documentation/mcp/index.mdx index b2382aa..13d88b9 100644 --- a/content/docs/documentation/mcp/index.mdx +++ b/content/docs/documentation/mcp/index.mdx @@ -15,18 +15,18 @@ import { Step, Steps } from "fumadocs-ui/components/steps"; The Whitepages MCP (Model Context Protocol) server allows AI assistants like Claude Desktop, Cursor, and other MCP-compatible tools to directly access Whitepages Pro API functionality. -## Quick Start +## Quick start -### Get Your API Key +### Get your API key If you don't have an API key yet, [get a trial key](/documentation/getting-trial-api-key). -### Configure Your AI Tool +### Configure your AI tool Choose your AI tool below and copy the configuration. @@ -353,7 +353,7 @@ If you don't have an API key: - [Get a trial key](/documentation/getting-trial-api-key) for testing - [Purchase a plan](/documentation/purchasing-api) for production use -## What's Available +## What's available Connecting to the MCP server gives your AI assistant two things: **tools** that call the Whitepages Pro API, and the **full corpus of documentation**. @@ -389,7 +389,7 @@ Because both forms serve the identical corpus, no assistant is left without the The exact tool names and their parameters are shown in your AI assistant after connecting. -## Usage in AI Assistants +## Usage in AI assistants After configuring the MCP server, you can ask your AI assistant to use Whitepages data: diff --git a/content/docs/documentation/meta.json b/content/docs/documentation/meta.json index 28b39d9..d0aa7aa 100644 --- a/content/docs/documentation/meta.json +++ b/content/docs/documentation/meta.json @@ -9,12 +9,13 @@ "purchasing-api", "---Guides---", "person-search", - "webhooks", - "events", - "regions", "property-search", + "phone-search", "...mcp", "agentic-guidance", + "events", + "webhooks", + "regions", "faq", "---LLMs---", "[Docs List](/llms.txt)", diff --git a/content/docs/documentation/person-search/confidence-scores.mdx b/content/docs/documentation/person-search/confidence-scores.mdx index 089d456..9089c0a 100644 --- a/content/docs/documentation/person-search/confidence-scores.mdx +++ b/content/docs/documentation/person-search/confidence-scores.mdx @@ -16,9 +16,9 @@ keywords: Person search responses include confidence scores on three levels: the person record itself, each phone number, and each email address. All scores range from **0 to 100** and represent relative confidence — a higher score means stronger evidence of association. -## Score Types +## Score types -### Person Match Score +### Person match score The top-level `match_score` on a person record indicates how well that record matches your search query. Higher scores reflect stronger matches across name, location, and other query parameters. A companion `matched_by` array names which of your query inputs contributed to the match. @@ -34,7 +34,7 @@ The top-level `match_score` on a person record indicates how well that record ma Use `match_score` to rank or filter results when multiple people match your query, and `matched_by` to understand which inputs were most decisive. -### Phone Score +### Phone score Each phone number includes a `score` indicating confidence that the number is actively associated with this person. @@ -47,7 +47,7 @@ Each phone number includes a `score` indicating confidence that the number is ac A higher score means the number is more likely to be current and correctly attributed. A low score may indicate the number is outdated or only loosely associated. -### Email Score +### Email score Each email address includes a `score` indicating confidence that the address belongs to this person. @@ -58,7 +58,7 @@ Each email address includes a `score` indicating confidence that the address bel ] ``` -## Interpreting Scores +## Interpreting scores Scores are **relative**, not absolute thresholds. There is no fixed cutoff for "good" vs "bad" — the right threshold depends on your use case: diff --git a/content/docs/documentation/person-search/filter-by-age-range.mdx b/content/docs/documentation/person-search/filter-by-age-range.mdx index 09e72c7..ed15783 100644 --- a/content/docs/documentation/person-search/filter-by-age-range.mdx +++ b/content/docs/documentation/person-search/filter-by-age-range.mdx @@ -15,7 +15,7 @@ keywords: Use the `min_age` and `max_age` parameters to filter person search results by age range. This is useful when you need to find individuals within a specific age bracket. -## Basic Usage +## Basic usage Add `min_age` and/or `max_age` to your request to filter results: @@ -40,7 +40,7 @@ This returns only records for individuals between 25 and 45 years old. ## Examples -### Filter by Minimum Age +### Filter by minimum age Filter for individuals 21 years or older: @@ -49,7 +49,7 @@ curl 'https://api.whitepages.com/v2/person?name=Jane%20Doe&city=Chicago&state_co --header 'X-Api-Key: YOUR_API_KEY' ``` -### Filter by Maximum Age +### Filter by maximum age Filter for individuals 40 or younger: @@ -58,7 +58,7 @@ curl 'https://api.whitepages.com/v2/person?last_name=Johnson&state_code=FL&max_a --header 'X-Api-Key: YOUR_API_KEY' ``` -### Filter by Age Range +### Filter by age range Filter for individuals between 25 and 55: @@ -67,7 +67,7 @@ curl 'https://api.whitepages.com/v2/person?name=Michael%20Williams&zipcode=90210 --header 'X-Api-Key: YOUR_API_KEY' ``` -## Combining with Other Filters +## Combining with other filters Age filters work alongside all other person search parameters: diff --git a/content/docs/documentation/person-search/fuzzy-matching.mdx b/content/docs/documentation/person-search/fuzzy-matching.mdx index 655daac..2ed81af 100644 --- a/content/docs/documentation/person-search/fuzzy-matching.mdx +++ b/content/docs/documentation/person-search/fuzzy-matching.mdx @@ -16,7 +16,7 @@ keywords: Person search matches names in two modes: **exact match** and **fuzzy match**. Fuzzy match broadens name matching to phonetic variants, common nicknames, initials, and typos. By default the API runs an exact match first and only falls back to fuzzy match if the exact pass returns no results — you get the precision of exact match when it works and the recall of fuzzy match when it doesn't. Set `include_fuzzy_matching=true` to skip the exact pass and start with fuzzy match directly. -## Basic Usage +## Basic usage You do not need to set anything to benefit from fuzzy matching. If your exact-name search returns no results, the API automatically retries with fuzzy matching: @@ -41,7 +41,7 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Doe&city=New%20York&state | `include_fuzzy_matching` | boolean | `false` | When `true`, the search starts with fuzzy matching instead of exact matching. When `false` (the default), the search runs exact first and falls back to fuzzy only when exact returns no results. | | `strict_match` | boolean | `false` | When `true`, the search does not fall back to fuzzy matching on a zero-result response; the exact query is authoritative. Cannot be combined with `include_fuzzy_matching=true`. | -## How It Works +## How it works Fuzzy matching expands name matching to include: @@ -68,7 +68,7 @@ Exact name matches are still ranked higher than fuzzy matches, so precise result the caller is a CRM export of informal names. -## Opting Out — `strict_match=true` +## Opting out — `strict_match=true` If your use case treats an empty result as authoritative — for example, verifying a name genuinely does not exist in the dataset — set diff --git a/content/docs/documentation/person-search/index.mdx b/content/docs/documentation/person-search/index.mdx index 1ddf84e..27e1a3f 100644 --- a/content/docs/documentation/person-search/index.mdx +++ b/content/docs/documentation/person-search/index.mdx @@ -4,7 +4,9 @@ related: - /documentation/agentic-guidance/capability-map - /documentation/person-search/reverse-phone-lookup - /documentation/person-search/search-by-address -title: Person Search + - /documentation/person-search/search-by-radius + - /documentation/person-search/pagination +title: Person Search API description: Look up individuals by name, phone, or address lifecycle: current topic: person @@ -17,11 +19,11 @@ keywords: The Person Search API finds matching records in the Whitepages dataset based on name, location, phone number, or address. Use it to verify identities, find contact information, or enrich customer data. -## Make Your First Request +## Make your first request -### Send a Request +### Send a request Search for a person by name and location: @@ -35,7 +37,7 @@ Replace `YOUR_API_KEY` with your actual API key. -### Review the Response +### Review the response A successful request returns matching person records: @@ -109,26 +111,30 @@ Each record includes identifiers, contact and employment fields, match signals, Scores](/documentation/person-search/confidence-scores) for details. -## Request Parameters +## Request parameters Combine any of these parameters to refine your search: -| Parameter | Description | Example | -| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -| `name` | Full or partial name | `John Smith` | -| `first_name` | First name | `John` | -| `middle_name` | Middle name | `Robert` | -| `last_name` | Last name | `Smith` | -| `phone` | Phone number | `2125550198` | -| `street` | Street address | `123 Main St` | -| `city` | City name | `New York` | -| `state_code` | Two-letter state code | `NY` | -| `zipcode` | ZIP code | `10001` | -| `min_age` | Minimum age filter (18-65) | `25` | -| `max_age` | Maximum age filter (18-65) | `55` | -| `include_historical_locations` | Include historical addresses in search (default: `false`) | `true` | -| `include_fuzzy_matching` | Force fuzzy name matching on the first pass. When `false` (default) the API runs exact match first and falls back to fuzzy automatically if the exact pass returns no results. See [Fuzzy Matching](/documentation/person-search/fuzzy-matching). | `true` | -| `strict_match` | Suppress automatic fuzzy fallback (default: `false`). When `true`, a zero-result exact query is returned as-is instead of retrying with fuzzy matching. Cannot be combined with `include_fuzzy_matching=true`. | `true` | +| Parameter | Description | Example | +| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | +| `name` | Full or partial name | `John Smith` | +| `first_name` | First name | `John` | +| `middle_name` | Middle name | `Robert` | +| `last_name` | Last name | `Smith` | +| `phone` | Phone number | `2125550198` | +| `email` | Email address | `john@example.com` | +| `street` | Street address | `123 Main St` | +| `city` | City name | `New York` | +| `state_code` | Two-letter state code | `NY` | +| `zipcode` | ZIP code | `10001` | +| `radius` | Search radius in miles (max 100) around the address, city, or ZIP code. See [Search by Radius](/documentation/person-search/search-by-radius). | `10` | +| `min_age` | Minimum age filter (18-65) | `25` | +| `max_age` | Maximum age filter (18-65) | `55` | +| `include_historical_locations` | Include historical addresses in search (default: `false`) | `true` | +| `include_fuzzy_matching` | Force fuzzy name matching on the first pass. When `false` (default) the API runs exact match first and falls back to fuzzy automatically if the exact pass returns no results. See [Fuzzy Matching](/documentation/person-search/fuzzy-matching). | `true` | +| `strict_match` | Suppress automatic fuzzy fallback (default: `false`). When `true`, a zero-result exact query is returned as-is instead of retrying with fuzzy matching. Cannot be combined with `include_fuzzy_matching=true`. | `true` | +| `page` | Page number, 1-indexed (default: `1`). See [Pagination](/documentation/person-search/pagination). | `2` | +| `page_size` | Results per page, 1-15 (default: `15`). See [Pagination](/documentation/person-search/pagination). | `15` | The API uses **AND logic**, meaning all parameters must match. For example, @@ -143,7 +149,7 @@ Combine any of these parameters to refine your search: https://api.whitepages.com/v2/person?name=John%20Smith&zipcode=10001 ``` -## Response Codes +## Response codes | Status | Description | Billable | | ----------------------- | ----------------------------- | -------- | @@ -160,6 +166,6 @@ https://api.whitepages.com/v2/person?name=John%20Smith&zipcode=10001 records were returned. -## Next Steps +## Next steps -Learn how to look up property ownership and resident data in the [Property Search](/documentation/property-search) tutorial. +Learn how to look up property ownership and resident data in the [Property Search API](/documentation/property-search) tutorial. diff --git a/content/docs/documentation/person-search/meta.json b/content/docs/documentation/person-search/meta.json index 2a60643..f8b1065 100644 --- a/content/docs/documentation/person-search/meta.json +++ b/content/docs/documentation/person-search/meta.json @@ -1,5 +1,5 @@ { - "title": "Person Search", + "title": "Person Search API", "icon": "User", "pages": [ "partial-name-search", diff --git a/content/docs/documentation/person-search/pagination.mdx b/content/docs/documentation/person-search/pagination.mdx index 4e5ceab..6597ad9 100644 --- a/content/docs/documentation/person-search/pagination.mdx +++ b/content/docs/documentation/person-search/pagination.mdx @@ -16,7 +16,7 @@ keywords: Person search returns up to 15 results per request by default. Use the `page` and `page_size` parameters to retrieve additional results when a query matches more records than a single page can return. -## Basic Usage +## Basic usage Add `page=2` to retrieve the second page of results for the same query: @@ -62,7 +62,7 @@ Each response includes a `metadata` object alongside the results: Use `result_count` to determine whether additional pages are available. If `result_count` is greater than `page × page_size`, there are more results on the next page. -## Iterating Through Pages +## Iterating through pages ```bash title="Iterate through all pages" PAGE=1 diff --git a/content/docs/documentation/person-search/partial-name-search.mdx b/content/docs/documentation/person-search/partial-name-search.mdx index 6290735..cd99187 100644 --- a/content/docs/documentation/person-search/partial-name-search.mdx +++ b/content/docs/documentation/person-search/partial-name-search.mdx @@ -15,7 +15,7 @@ keywords: When you only have partial name information, use the individual name parameters (`first_name`, `middle_name`, `last_name`) to search more precisely than using the combined `name` parameter. -## When to Use Partial Name Search +## When to use partial name search Use individual name parameters when: @@ -23,7 +23,7 @@ Use individual name parameters when: - You need to search across variations of a name - You want more control over which parts of a name to match -## Search by Last Name Only +## Search by last name only Find all people with a specific last name in a location: @@ -32,7 +32,7 @@ curl 'https://api.whitepages.com/v2/person?last_name=Smith&city=Seattle&state_co --header 'X-Api-Key: YOUR_API_KEY' ``` -## Search by First and Last Name +## Search by first and last name When you know both first and last name but want to match regardless of middle name: @@ -41,7 +41,7 @@ curl 'https://api.whitepages.com/v2/person?first_name=John&last_name=Smith&state --header 'X-Api-Key: YOUR_API_KEY' ``` -## Include Middle Name for Precision +## Include middle name for precision For more precise matching when you have complete name information: @@ -50,7 +50,7 @@ curl 'https://api.whitepages.com/v2/person?first_name=John&middle_name=Robert&la --header 'X-Api-Key: YOUR_API_KEY' ``` -## Combining with Location Parameters +## Combining with location parameters For best results, always include at least one location parameter: @@ -60,7 +60,7 @@ For best results, always include at least one location parameter: | `last_name` + `city` + `state_code` | City-level search | | `first_name` + `last_name` + `zipcode` | Precise local search | -## Name Parameter vs Individual Parameters +## Name parameter vs individual parameters | Parameter | Behavior | | -------------------------- | ------------------------------------------------------ | diff --git a/content/docs/documentation/person-search/reverse-phone-lookup.mdx b/content/docs/documentation/person-search/reverse-phone-lookup.mdx index b3a51f8..5ad68a8 100644 --- a/content/docs/documentation/person-search/reverse-phone-lookup.mdx +++ b/content/docs/documentation/person-search/reverse-phone-lookup.mdx @@ -1,12 +1,12 @@ --- related: - - /references/phone-v2/get_phone_by_number_v2 + - /documentation/phone-search - /documentation/agentic-guidance/capability-map - /documentation/person-search - /references/person-v2/search_person_by_name_phone_or_address_v2 - /documentation/person-search/search-by-address -title: Reverse Phone Lookup -description: Find out what a phone number is and who it belongs to +title: Reverse Phone Lookup API +description: Find the people who match a phone number, ranked by confidence lifecycle: current topic: person keywords: @@ -14,269 +14,90 @@ keywords: - "phone search" - "who owns this number" - "find owner of a phone number" - - "phone line type" - - "phone carrier" --- import { Callout } from "fumadocs-ui/components/callout"; -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. +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. + + + If the number itself is the subject — its line type, carrier, or the business + behind it — use [Phone Search](/documentation/phone-search) instead. That + guide also returns businesses, which person search cannot. + ## Look up a number ```bash title="Request" -curl 'https://api.whitepages.com/v2/phone/12065550142' \ +curl 'https://api.whitepages.com/v2/person/?phone=2065550142' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ```json title="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 } +[ + { + "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": 95, + "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": [], + "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": 0, "additional": 0 }, + "owned_properties": { "displayed": 1, "additional": 0 } } - ], - "businesses": [] -} + } +] ``` - - 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. - -```json title="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`. - - - `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. +## Combine with name for verification Verify that a number belongs to a particular person: ```bash -curl 'https://api.whitepages.com/v2/person/?phone=2125550198&name=John%20Smith' \ +curl 'https://api.whitepages.com/v2/person/?phone=2065550142&name=John%20Smith' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -Narrow by location: +## Combine with location + +Narrow results by adding location filters: ```bash -curl 'https://api.whitepages.com/v2/person/?phone=2125550198&state_code=NY' \ +curl 'https://api.whitepages.com/v2/person/?phone=2065550142&state_code=WA' \ --header 'X-Api-Key: YOUR_API_KEY' ``` @@ -289,14 +110,14 @@ curl 'https://api.whitepages.com/v2/person/?phone=2125550198&state_code=NY' \ ## 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/` | +| If you want to… | Use | +| ------------------------------------------------------------ | ------------------------------------------- | +| Rank people against the number | Reverse Phone Lookup | +| Confirm a number belongs to a named person | Reverse Phone Lookup | +| Combine the number with an address or age filter | Reverse Phone Lookup | +| Know the line type or carrier | [Phone Search](/documentation/phone-search) | +| Find the business behind a number | [Phone Search](/documentation/phone-search) | +| Get an answer even when nobody is associated with the number | [Phone Search](/documentation/phone-search) | Each successful lookup bills one unit on either endpoint, whether or not it found anyone. diff --git a/content/docs/documentation/person-search/search-by-address.mdx b/content/docs/documentation/person-search/search-by-address.mdx index 0bec65e..f191776 100644 --- a/content/docs/documentation/person-search/search-by-address.mdx +++ b/content/docs/documentation/person-search/search-by-address.mdx @@ -17,7 +17,7 @@ keywords: Use address parameters to find people associated with a specific location. By default, searches match only current addresses. Enable `include_historical_locations` to also search historical addresses. -## Basic Usage +## Basic usage Search for people at a specific address: @@ -28,7 +28,7 @@ curl 'https://api.whitepages.com/v2/person?street=123%20Main%20St&city=Seattle&s This returns people whose **current address** matches the search criteria. -## Include Historical Addresses +## Include historical addresses To search both current and historical addresses, set `include_historical_locations=true`: @@ -51,7 +51,7 @@ This returns people who currently live at the address **or** have previously liv ## Examples -### Search by ZIP Code Only +### Search by ZIP code only Find people in a specific ZIP code: @@ -60,7 +60,7 @@ curl 'https://api.whitepages.com/v2/person?zipcode=98101' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -### Search by City and State +### Search by city and state Find people in a specific city: @@ -69,7 +69,7 @@ curl 'https://api.whitepages.com/v2/person?city=Portland&state_code=OR' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -### Find Previous Residents +### Find previous residents Find anyone who has ever lived at an address: @@ -78,7 +78,7 @@ curl 'https://api.whitepages.com/v2/person?street=456%20Oak%20Ave&city=Denver&st --header 'X-Api-Key: YOUR_API_KEY' ``` -### Combine with Name Search +### Combine with name search Find a specific person at an address: @@ -141,7 +141,7 @@ The response includes both current and historical addresses for each person foun both fields regardless of the search setting. -## Address Standardization (CASS) +## Address standardization (CASS) Person addresses in the Whitepages dataset are processed through **CASS certification** (Coding Accuracy Support System), the USPS address standardization program. All addresses are run through SmartyStreets to normalize formatting and assign a validity status before being stored. @@ -150,7 +150,7 @@ This means: - Addresses are in a **consistent format** regardless of how they were originally recorded - Every address has a **validity status** indicating how well it was verified -### Validity Status +### Validity status | Status | Description | | ------------------- | ------------------------------------------------------------ | diff --git a/content/docs/documentation/person-search/search-by-radius.mdx b/content/docs/documentation/person-search/search-by-radius.mdx index b0fe0eb..5b0963f 100644 --- a/content/docs/documentation/person-search/search-by-radius.mdx +++ b/content/docs/documentation/person-search/search-by-radius.mdx @@ -16,7 +16,7 @@ keywords: Use the `radius` parameter to find people within a specific distance of a location. This enables proximity-based searches, such as finding all people within 10 miles of a given address or city. -## Basic Usage +## Basic usage Search for people within a radius of a location: @@ -27,7 +27,7 @@ curl 'https://api.whitepages.com/v2/person?city=Seattle&state_code=WA&radius=10' This returns people whose **current address** is within 10 miles of Seattle, WA. -## How It Works +## How it works When you provide a `radius` parameter along with location information, the API: @@ -59,7 +59,7 @@ When you provide a `radius` parameter along with location information, the API: ## Examples -### Search by City with Radius +### Search by city with radius Find people within 5 miles of downtown Portland: @@ -68,7 +68,7 @@ curl 'https://api.whitepages.com/v2/person?city=Portland&state_code=OR&radius=5' --header 'X-Api-Key: YOUR_API_KEY' ``` -### Search by ZIP Code with Radius +### Search by ZIP code with radius Find people within 1 miles of a specific ZIP code: @@ -77,7 +77,7 @@ curl 'https://api.whitepages.com/v2/person?zipcode=98101&radius=1' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -### Search by Full Address with Radius +### Search by full address with radius Find people within 0.1 miles of a specific street address: @@ -86,7 +86,7 @@ curl 'https://api.whitepages.com/v2/person?street=123%20Main%20St&city=Seattle&s --header 'X-Api-Key: YOUR_API_KEY' ``` -### Include Historical Addresses +### Include historical addresses Find people who currently live or have previously lived within 10 miles of a location: @@ -95,7 +95,7 @@ curl 'https://api.whitepages.com/v2/person?city=Austin&state_code=TX&radius=10&i --header 'X-Api-Key: YOUR_API_KEY' ``` -### Combine with Name Search +### Combine with name search Find a specific person within a radius: @@ -104,11 +104,11 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Smith&city=Denver&state_c --header 'X-Api-Key: YOUR_API_KEY' ``` -## Location Specification +## Location specification You can specify the center point for radius searches in several ways: -### Street Address (Most Precise) +### Street address (most precise) Provide a full street address for the most accurate center point: @@ -117,7 +117,7 @@ curl 'https://api.whitepages.com/v2/person?street=456%20Oak%20Ave&city=Boston&st --header 'X-Api-Key: YOUR_API_KEY' ``` -### City and State +### City and state Use city and state for a broader center point (typically the city center): @@ -126,7 +126,7 @@ curl 'https://api.whitepages.com/v2/person?city=San%20Francisco&state_code=CA&ra --header 'X-Api-Key: YOUR_API_KEY' ``` -### ZIP Code +### ZIP code Use a ZIP code as the center point: @@ -189,9 +189,9 @@ The response format is identical to standard person searches, including all addr other matching criteria. -## Error Handling +## Error handling -### Graceful Degradation +### Graceful degradation If the location cannot be geocoded (e.g., invalid address or service unavailable), the API automatically falls back to standard address matching without distance filtering: @@ -201,7 +201,7 @@ curl 'https://api.whitepages.com/v2/person?city=InvalidCity&state_code=XX&radius --header 'X-Api-Key: YOUR_API_KEY' ``` -### Radius Too Large +### Radius too large Requests with radius values exceeding 100 miles will return a validation error: @@ -217,15 +217,15 @@ Requests with radius values exceeding 100 miles will return a validation error: } ``` -## Best Practices +## Best practices -### Choose Appropriate Radius +### Choose appropriate radius - **Urban areas**: Use smaller radii (2-10 miles) for more targeted results - **Suburban areas**: Use medium radii (10-25 miles) to cover broader regions - **Rural areas**: Use larger radii (25-100 miles) to account for lower population density -### Combine with Other Filters +### Combine with other filters Radius searches work well with other parameters: @@ -235,7 +235,7 @@ curl 'https://api.whitepages.com/v2/person?city=Chicago&state_code=IL&radius=15& --header 'X-Api-Key: YOUR_API_KEY' ``` -### Performance Considerations +### Performance considerations - Larger radii return more results but will take longer to process - Combining radius with name or other filters improves performance diff --git a/content/docs/documentation/phone-search.mdx b/content/docs/documentation/phone-search.mdx new file mode 100644 index 0000000..5552c67 --- /dev/null +++ b/content/docs/documentation/phone-search.mdx @@ -0,0 +1,226 @@ +--- +related: + - /references/phone-v2/get_phone_by_number_v2 + - /documentation/person-search/reverse-phone-lookup + - /documentation/agentic-guidance/capability-map + - /references/person-v2/search_person_by_name_phone_or_address_v2 +title: Phone Search +description: Look up a phone number's own facts and the people or businesses behind it +icon: Phone +lifecycle: current +topic: person +keywords: + - "phone search" + - "phone lookup" + - "phone line type" + - "phone carrier" + - "business behind a phone number" +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +`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 itself is the subject of your question. + + + If a person is the subject and the number is one of your search criteria, use + [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup) + instead. That guide ranks person records against a number; this one answers + what the number is. + + +## Look up a number + +```bash title="Request" +curl 'https://api.whitepages.com/v2/phone/12065550142' \ + --header 'X-Api-Key: YOUR_API_KEY' +``` + +```json title="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": [], + "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": 0, "additional": 0 }, + "owned_properties": { "displayed": 1, "additional": 0 } + } + } + ], + "businesses": [] +} +``` + +### 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. + +```json title="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": [{ "...": "..." }], + "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" + } + ] + } + ] +} +``` + +### 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: an area code and +exchange starting with 2-9, followed by four digits. A number that doesn't +fit that shape is refused with HTTP 400 rather than searched. A number that +fits the shape but isn't a real assigned line — a reserved code like +`911` or `411` used as an area code or exchange, for instance — is +searched like any other and comes back with `primary_owner: "unknown"` +and empty `people` and `businesses`, the same as any other number nobody +is associated with. Each successful lookup bills one unit, whether or not +it found anyone. + +## 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` is one of `mobile`, `landline`, +`voip`, `tollfree`, or `unknown` when it can't be determined. `carrier` is +resolved by lookup where one is on file, and comes back `null` wherever +the provider has none — that isn't limited to toll-free numbers, so don't +assume a `null` carrier means toll-free. + +A lookup that finds no parties is an answer, not an error — the `phone` +block is still populated. + +### `primary_owner` — which list to read first + +`person`, `business`, or `unknown`. + + + `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. + +## Choosing between them + +| If you want to… | Use | +| ------------------------------------------------------------ | ------------------------------------------------------------------------- | +| Know the line type or carrier | Phone Search | +| Find the business behind a number | Phone Search | +| Get an answer even when nobody is associated with the number | Phone Search | +| Rank people against the number | [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup) | +| Confirm a number belongs to a named person | [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup) | +| Combine the number with an address or age filter | [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup) | + +Each successful lookup bills one unit on either endpoint, whether or not it +found anyone. diff --git a/content/docs/documentation/property-search.mdx b/content/docs/documentation/property-search.mdx index 4284381..c5aa657 100644 --- a/content/docs/documentation/property-search.mdx +++ b/content/docs/documentation/property-search.mdx @@ -4,7 +4,7 @@ related: - /references/property-v2/get_property_by_id_v2 - /documentation/agentic-guidance/capability-map - /documentation/person-search/search-by-address -title: Property Search +title: Property Search API description: Get ownership and resident data for any property icon: House lifecycle: current @@ -19,11 +19,11 @@ keywords: The Property Search API returns ownership and resident information for a given property. Use it to identify property owners, find current residents, or verify property details. -## Make Your First Request +## Make your first request -### Send a Request +### Send a request Search for property details by address: @@ -37,7 +37,7 @@ Replace `YOUR_API_KEY` with your actual API key, and replace `STREET_ADDRESS`, ` -### Review the Response +### Review the response A successful request returns property details with owner and resident information: @@ -224,7 +224,7 @@ The response includes the matched property with geolocation, property owners, an -## Match Confidence +## Match confidence Search ranks properties by how closely they match the address text you send, so the closest match to an address that does not exist can be a different property @@ -262,7 +262,7 @@ well did this rank". still returned. -## Returning Only Exact Matches — `strict_match=true` +## Returning only exact matches — `strict_match=true` If a wrong property is worse than no property — an automated pipeline, say, or address verification — set `strict_match=true`. The API returns the address you @@ -278,7 +278,7 @@ A result the API cannot verify is also dropped, because strict matching promises nothing approximate comes back. `strict_match` needs a `street` to compare against; a request without one returns `400`. -## Contact Limits on Owners and Residents +## Contact limits on owners and residents Each owner and resident carries up to **4 phone numbers** and **3 email addresses**, highest confidence first. A metadata block on each person reports @@ -305,7 +305,7 @@ residents carry `resident_metadata`; the contents are identical. portfolio reports fewer than they hold. Phone and email counts are exact. -## Request Parameters +## Request parameters | Parameter | Required | Description | Example | | -------------- | -------- | ------------------------------------------------------------ | ----------------- | @@ -332,7 +332,7 @@ https://api.whitepages.com/v2/property/?street=123%20Main%20Street&zipcode=98101 https://api.whitepages.com/v2/property/RSAMPLE0001 ``` -## Property Details by ID +## Property details by ID The property details endpoint accepts either a Whitepages property ID (`R` prefix) or an address ID (`A` prefix). Address IDs are resolved to the associated property before lookup, so you can pass the address IDs found throughout other API responses directly: @@ -347,7 +347,7 @@ https://api.whitepages.com/v2/property/{property_id_or_address_id} details for any address ID you encounter. -## Address Standardization +## Address standardization Property addresses (both physical and mailing) are **not** processed through CASS certification. Property address data is sourced directly from county assessor and recorder records and is stored as-received without USPS standardization. @@ -362,6 +362,6 @@ remain as the county recorded them. Address](/documentation/person-search/search-by-address#address-standardization-cass). -## What's Next +## What's next You've completed the getting started tutorials. Explore the [References](/references) section for complete API documentation. diff --git a/content/docs/documentation/purchasing-api.mdx b/content/docs/documentation/purchasing-api.mdx index 991a1e6..ddaf3ee 100644 --- a/content/docs/documentation/purchasing-api.mdx +++ b/content/docs/documentation/purchasing-api.mdx @@ -10,7 +10,7 @@ icon: CreditCard This guide walks you through the process of purchasing a paid Whitepages Pro API subscription. Paid plans offer higher query limits and are suitable for production use. -## Step 1: Visit the Pricing Page +## Step 1: visit the pricing page Go to [whitepages.com/pro-api/pricing/plans](https://www.whitepages.com/pro-api/pricing/plans) to view paid plans. @@ -22,13 +22,13 @@ The page shows three primary pricing cards along the top — **Starter**, **Grow free queries before purchasing. -## Step 2: Select Your Plan +## Step 2: select your plan -### Monthly vs Annual Billing +### Monthly vs annual billing Use the **Monthly / Annual** toggle at the top of the page to switch billing cadence. Annual plans are 15% cheaper than the equivalent monthly plan. -### Pick a Tier +### Pick a tier Pick one of the three primary cards (Starter / Growth / Scale) and click **Get Pro Access**, or open the **Additional Plans** section below and click the price button next to a higher tier (Advanced / Enterprise) to proceed to checkout. @@ -41,11 +41,11 @@ Pick one of the three primary cards (Starter / Growth / Scale) and click **Get P [pricing page](https://www.whitepages.com/pro-api/pricing/plans). -## Step 3: Complete the Checkout Form +## Step 3: complete the checkout form After clicking "Get Pro Access", you'll be taken to the secure checkout page. -### Account Details +### Account details Fill in the following information: @@ -73,7 +73,7 @@ Fill in the following information: address. Make sure it's correct before submitting. -### Payment Information +### Payment information Enter your payment details: @@ -83,7 +83,7 @@ Enter your payment details: - **CVV** - The 3 or 4 digit security code on your card - **Billing ZIP Code** - The ZIP code associated with your billing address -## Step 4: Review and Submit +## Step 4: review and submit Before submitting, review your order summary on the right side of the page: @@ -98,7 +98,7 @@ Check the box to agree to the recurring charges, then click **Submit Order**. support. There are no long-term contracts for monthly plans. -## Step 5: Copy Your API Key +## Step 5: copy your API key After successful payment, your API key will be displayed on the confirmation screen. @@ -108,7 +108,7 @@ After successful payment, your API key will be displayed on the confirmation scr not receive your API key via email. -## Using Your API Key +## Using your API key Include your API key in the `X-Api-Key` header with every request: @@ -123,7 +123,7 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Smith' \ immediately. -## Managing Your Subscription +## Managing your subscription To manage your subscription, upgrade your plan, or view usage statistics: @@ -133,7 +133,7 @@ To manage your subscription, upgrade your plan, or view usage statistics: For billing questions or to cancel your subscription, contact customer support at (800) 916-7806 or visit [support.whitepages.com](https://support.whitepages.com/hc/en-us). -## Next Steps +## Next steps diff --git a/content/docs/documentation/regions.mdx b/content/docs/documentation/regions.mdx index e1db218..ece678b 100644 --- a/content/docs/documentation/regions.mdx +++ b/content/docs/documentation/regions.mdx @@ -13,18 +13,18 @@ The Regions API provides access to the full list of US states and their associat Use the interactive browser below to explore available regions, or jump to the API reference for programmatic access. -## Browse Regions +## Browse regions -## API Reference +## API reference | Endpoint | Description | | -------------------------------------------------- | -------------------------------------- | | [List States](/references/regions/list_states) | Retrieve all US states and territories | | [List Counties](/references/regions/list_counties) | Retrieve counties for a given state | -## Next Steps +## Next steps -## Add a Name for Easy Identification +## Add a name for easy identification Assigning a name makes it easier to manage multiple subscriptions: diff --git a/content/docs/documentation/webhooks/delete-webhook.mdx b/content/docs/documentation/webhooks/delete-webhook.mdx index e0914cb..0276e5f 100644 --- a/content/docs/documentation/webhooks/delete-webhook.mdx +++ b/content/docs/documentation/webhooks/delete-webhook.mdx @@ -9,7 +9,7 @@ description: Permanently remove a webhook subscription Use the `DELETE /v1/webhooks/{webhook_id}` endpoint to permanently remove a webhook subscription. Once deleted, no further events will be delivered to the endpoint. -## Basic Usage +## Basic usage Delete a webhook subscription: @@ -26,7 +26,7 @@ A successful deletion returns a `204 No Content` response with no body. staging endpoint instead. -## Verify Deletion +## Verify deletion After deleting, you can confirm the webhook no longer exists by listing your subscriptions: diff --git a/content/docs/documentation/webhooks/index.mdx b/content/docs/documentation/webhooks/index.mdx index bd8f090..3c05bfd 100644 --- a/content/docs/documentation/webhooks/index.mdx +++ b/content/docs/documentation/webhooks/index.mdx @@ -22,7 +22,7 @@ The Webhooks API delivers live property deed event notifications directly to you page](/documentation/regions). -## Why Use Webhooks +## Why use webhooks - **Live updates** — Get notified as soon as deed events are recorded, rather than polling the API on a schedule - **Reduced API usage** — Receive only the events you care about instead of repeatedly querying for changes diff --git a/content/docs/documentation/webhooks/list-webhooks.mdx b/content/docs/documentation/webhooks/list-webhooks.mdx index f9872cc..40f9579 100644 --- a/content/docs/documentation/webhooks/list-webhooks.mdx +++ b/content/docs/documentation/webhooks/list-webhooks.mdx @@ -9,7 +9,7 @@ description: List and filter your webhook subscriptions Use the `GET /v1/webhooks/` endpoint to retrieve all of your webhook subscriptions. You can filter by status or event type. -## Basic Usage +## Basic usage List all webhook subscriptions: @@ -18,14 +18,14 @@ curl 'https://api.whitepages.com/v1/webhooks/' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -## Query Parameters +## Query parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------- | | `status` | string | No | Filter by status: `active` or `inactive` | | `event_type` | string | No | Filter by subscribed event type | -## Filter by Status +## Filter by status List only active subscriptions: @@ -34,7 +34,7 @@ curl 'https://api.whitepages.com/v1/webhooks/?status=active' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -## Filter by Event Type +## Filter by event type List subscriptions for a specific event type: @@ -74,7 +74,7 @@ The response includes an array of all matching webhook subscriptions: } ``` -## Get a Single Webhook +## Get a single webhook Retrieve a specific subscription by its ID: diff --git a/content/docs/documentation/webhooks/quickstart.mdx b/content/docs/documentation/webhooks/quickstart.mdx index ecfa119..61afdf3 100644 --- a/content/docs/documentation/webhooks/quickstart.mdx +++ b/content/docs/documentation/webhooks/quickstart.mdx @@ -25,7 +25,7 @@ This interactive walkthrough guides you through the complete webhook lifecycle u -## Next Steps +## Next steps - [Create a Webhook](/documentation/webhooks/create-webhook) — Full guide with all parameters and options - [Event Payload](/documentation/events/event-payload) — Detailed breakdown of event data fields diff --git a/content/docs/documentation/webhooks/test-webhook.mdx b/content/docs/documentation/webhooks/test-webhook.mdx index 0c327f4..30a6e00 100644 --- a/content/docs/documentation/webhooks/test-webhook.mdx +++ b/content/docs/documentation/webhooks/test-webhook.mdx @@ -9,7 +9,7 @@ description: Send a mock event payload to verify your webhook endpoint Use the `POST /v1/webhooks/{webhook_id}/test` endpoint to send a mock event payload to your webhook's URL. This lets you verify that your server receives and processes deliveries correctly without waiting for a real event. -## Basic Usage +## Basic usage Send a test delivery to a webhook: @@ -55,7 +55,7 @@ The response tells you whether your endpoint received the delivery successfully: The `payload` field shows what was sent to your endpoint. This is a lightweight notification containing the event type and a link to retrieve the full event details using the [Events API](/documentation/events/get-event). -## What Your Endpoint Receives +## What your endpoint receives Your webhook URL receives a POST request with the following payload: @@ -86,7 +86,7 @@ Each entry in `links` contains a `version` string and a `url` pointing to the fu linked event data is synthetic. -## Diagnosing Failures +## Diagnosing failures If `success` is `false`, check the `delivery.status_code` to diagnose the issue: diff --git a/content/docs/documentation/webhooks/update-webhook.mdx b/content/docs/documentation/webhooks/update-webhook.mdx index e6da523..11d8848 100644 --- a/content/docs/documentation/webhooks/update-webhook.mdx +++ b/content/docs/documentation/webhooks/update-webhook.mdx @@ -9,7 +9,7 @@ description: Modify an existing webhook subscription Use the `PATCH /v1/webhooks/{webhook_id}` endpoint to update a webhook subscription. All fields are optional — only include the fields you want to change. -## Basic Usage +## Basic usage Update the delivery URL for a webhook: @@ -31,7 +31,7 @@ curl -X PATCH 'https://api.whitepages.com/v1/webhooks/wh_abc123' \ | `region` | string | No | New region filter in `type:value` format | | `name` | string | No | New human-readable label (max 255 chars) | -## Rename a Webhook +## Rename a webhook ```bash title="Request" curl -X PATCH 'https://api.whitepages.com/v1/webhooks/wh_abc123' \ @@ -42,7 +42,7 @@ curl -X PATCH 'https://api.whitepages.com/v1/webhooks/wh_abc123' \ }' ``` -## Change the Region +## Change the region Move a subscription to a different region: diff --git a/content/docs/references/authentication.mdx b/content/docs/references/authentication.mdx index 800e699..f2f6108 100644 --- a/content/docs/references/authentication.mdx +++ b/content/docs/references/authentication.mdx @@ -19,7 +19,7 @@ import { Callout } from "fumadocs-ui/components/callout"; All API requests require a valid API key provided in the `X-Api-Key` header. -## API Key +## API key Include your API key in every request using the `X-Api-Key` header: @@ -33,12 +33,12 @@ curl -X GET "https://api.whitepages.com/v2/person/" \ repositories. -## Obtaining an API Key +## Obtaining an API key - **Trial key**: Provisioned through self-serve sign-up. Visit the [Getting a Trial API Key](/documentation/getting-trial-api-key) guide to get started. - **Production key**: Requires purchasing an API product at [whitepages.com/pro-api/pricing/plans](https://www.whitepages.com/pro-api/pricing/plans). -## Error Responses +## Error responses If authentication fails, you will receive a `403 Forbidden` response: diff --git a/content/docs/references/billing-prior-to-2026-06-01.mdx b/content/docs/references/billing-prior-to-2026-06-01.mdx index dc69e0f..04c30eb 100644 --- a/content/docs/references/billing-prior-to-2026-06-01.mdx +++ b/content/docs/references/billing-prior-to-2026-06-01.mdx @@ -21,7 +21,7 @@ import { Callout } from "fumadocs-ui/components/callout"; API usage was tracked and billed based on successful requests. -## Billing Rules +## Billing rules | Response Type | Billable | | ------------------ | -------- | @@ -35,18 +35,18 @@ API usage was tracked and billed based on successful requests. were not billable. -## Billable Requests +## Billable requests All `2xx` (success) and `4xx` (client error) responses from Person and Property endpoints were charged to your account. -## Non-Billable Requests +## Non-billable requests The following responses were **not** charged: - `5xx` (server error) responses - issues on our end - `429` (rate limit) responses - when you've exceeded rate limits -## Billing Period +## Billing period Usage was calculated from the start of the month in UTC time. Billing cycles reset on the 1st of each month at 00:00 UTC. diff --git a/content/docs/references/billing.mdx b/content/docs/references/billing.mdx index 9ee788b..f596d11 100644 --- a/content/docs/references/billing.mdx +++ b/content/docs/references/billing.mdx @@ -26,7 +26,7 @@ API usage is tracked and billed based on successful requests. 2026-06-01](/references/billing-prior-to-2026-06-01). -## Billing Rules +## Billing rules | Response Type | Billable | | ------------------ | -------------------------------------------- | @@ -42,14 +42,14 @@ API usage is tracked and billed based on successful requests. and v2). Account, Regions, Events, and Webhooks endpoints are not billable. -## Billable Requests +## Billable requests The following responses from Person and Property endpoints, in any API version, are charged to your account: - All `2xx` (success) responses - `404` (not found) responses, except on `GET /v2/property/{property_id}` -## Non-Billable Requests +## Non-billable requests The following responses are **not** charged: @@ -63,11 +63,11 @@ The following responses are **not** charged: `GET /v2/property/{property_id}` accepts either a Whitepages property ID (`R` prefix) or an address ID (`A` prefix). Not every address ID has full property details, so these lookups may return `404`. Because `404` responses on this endpoint are never billed, you can optimistically look up property details for the address IDs you encounter throughout other API responses. -## Billing Period +## Billing period Usage is calculated from the start of the month in UTC time. Your billing cycle resets on the 1st of each month at 00:00 UTC. -## Usage Reports +## Usage reports Detailed usage reports are available through the [Account Usage](/references/account/get_account_usage_data) endpoint. You can query: diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx index a5aec35..cad4cef 100644 --- a/content/docs/references/index.mdx +++ b/content/docs/references/index.mdx @@ -37,7 +37,7 @@ Account management endpoints for retrieving usage statistics. /> -## Person V2 API +## Person v2 API -## Phone V2 API +## Phone v2 API -## Property V2 API +## Property v2 API -## Best Practices +## Best practices - **Implement retry logic** with exponential backoff for rate-limit 429s - **Branch on `error`** so your integration does not retry a usage cap in a loop @@ -116,6 +116,6 @@ Every plan includes a query allowance for its billing period, and trial keys inc - **Monitor usage** via the [Account Usage](/references/account/get_account_usage_data) endpoint - **Batch requests** where possible to optimize your quota -## Rate Limit Increases +## Rate limit increases For rate limit increases or quota adjustments, please contact our team at api@whitepages.com. diff --git a/content/docs/references/support-and-incident-response.mdx b/content/docs/references/support-and-incident-response.mdx index 04bcf8c..0866c0a 100644 --- a/content/docs/references/support-and-incident-response.mdx +++ b/content/docs/references/support-and-incident-response.mdx @@ -20,7 +20,7 @@ import { Callout } from "fumadocs-ui/components/callout"; We are committed to keeping the Whitepages Pro API reliable and transparent. This page covers how to get help, what to expect during incidents, and how we handle changes to the API. -## Support Channels +## Support channels For any questions, issues, or feature requests, reach out through the following channels: @@ -33,7 +33,7 @@ For any questions, issues, or feature requests, reach out through the following prefixed by **[URGENT]** to ensure priority routing. -## Incident Response Times +## Incident response times We classify incidents by severity. The following are our typical response and resolution times based on current operational metrics. These are not formal SLAs. @@ -44,7 +44,7 @@ Incidents are typically detected and responded to within **30 seconds**, with re rapid response across all severity levels. -### During an Incident +### During an incident When an incident occurs, we follow this process: @@ -54,7 +54,7 @@ When an incident occurs, we follow this process: 4. **Resolution** — The issue is resolved and services are verified as operational 5. **Post-mortem** — For Critical and High severity incidents, an internal post-mortem is conducted to prevent recurrence -## Getting Help During an Outage +## Getting help during an outage If you suspect an outage or are experiencing unexpected errors: @@ -64,7 +64,7 @@ If you suspect an outage or are experiencing unexpected errors: - Error responses you are receiving - Approximate time the issue started -## Versioning & Breaking Changes +## Versioning & breaking changes Our versioning approach, what we count as a breaking change, and how we announce changes now live in their own reference section: diff --git a/content/docs/references/versioning/breaking-changes-policy.mdx b/content/docs/references/versioning/breaking-changes-policy.mdx index 30b017f..a4ef67a 100644 --- a/content/docs/references/versioning/breaking-changes-policy.mdx +++ b/content/docs/references/versioning/breaking-changes-policy.mdx @@ -21,7 +21,7 @@ import { Callout } from "fumadocs-ui/components/callout"; We avoid breaking changes at nearly all cost. Backward compatibility is a top priority, and our goal is to minimize disruption to your integrations. -## Our Commitments +## Our commitments - **Breaking changes are always introduced in a new API version.** Your existing integration continues to work on the current version. - **No unannounced breaking changes.** Every breaking change is communicated in advance. @@ -30,7 +30,7 @@ We avoid breaking changes at nearly all cost. Backward compatibility is a top pr - **Deprecation notices** are communicated via email and changelog before anything is removed. - **Version support** — when a new version introduces breaking changes, the previous version remains available for at least 3 months after the new version is released. -## What We Consider a Breaking Change +## What we consider a breaking change - Removing or renaming an endpoint or data tool you call - Removing or renaming a field from a response body @@ -39,7 +39,7 @@ We avoid breaking changes at nearly all cost. Backward compatibility is a top pr - Changing authentication or authorization behavior - Modifying error response formats -## What We Do Not Consider a Breaking Change +## What we do not consider a breaking change - Adding a new optional request parameter - Adding a new tool to the MCP server @@ -56,11 +56,11 @@ We avoid breaking changes at nearly all cost. Backward compatibility is a top pr The same policy applies wherever we expose the API. What it means in practice depends on the surface you use. -## REST / HTTP Endpoints +## REST / HTTP endpoints Breaking changes ship in a new API version at a new path (for example, `/v2/`), so your current integration keeps working untouched. We announce the change with the notice and support windows above. Within a version, an endpoint's type signature — the parameters it accepts and the fields it returns — only grows: we may add new optional parameters and new response fields, but we do not remove, rename, or change the type of those already there. -## MCP Server & Tools +## MCP server & tools Our Breaking Changes policy covers only the [MCP server's](/documentation/mcp) **data tools**. Data tools fetch live data or change your account and **require your API key to run** — person search, property lookup, account usage, and the like. diff --git a/content/docs/references/versioning/change-notifications.mdx b/content/docs/references/versioning/change-notifications.mdx index be1ec8d..ca9d94b 100644 --- a/content/docs/references/versioning/change-notifications.mdx +++ b/content/docs/references/versioning/change-notifications.mdx @@ -19,7 +19,7 @@ import { Callout } from "fumadocs-ui/components/callout"; We notify you about critical changes through multiple channels to ensure you never miss an important update. -## Notification Types +## Notification types | Type | Channel | Lead Time | | ------------------------- | ---------------- | ------------------- | @@ -29,7 +29,7 @@ We notify you about critical changes through multiple channels to ensure you nev | **Scheduled maintenance** | Email | 7 days minimum | | **Emergency maintenance** | Email | As soon as possible | -## Staying Informed +## Staying informed - **Changelog** — All API changes are documented in our [changelog](/changelog) with detailed descriptions - **Email notifications** — Sent to the email address associated with your API account. Ensure your contact information is up to date. diff --git a/package.json b/package.json index 878f274..f61e28a 100644 --- a/package.json +++ b/package.json @@ -65,5 +65,8 @@ "typescript": "^5.9.3", "wrangler": "^4.53.0", "yaml": "2.8.2" + }, + "patchedDependencies": { + "fumadocs-openapi@10.1.1": "patches/fumadocs-openapi@10.1.1.patch" } } diff --git a/patches/fumadocs-openapi@10.1.1.patch b/patches/fumadocs-openapi@10.1.1.patch new file mode 100644 index 0000000..18e22d3 --- /dev/null +++ b/patches/fumadocs-openapi@10.1.1.patch @@ -0,0 +1,13 @@ +diff --git a/dist/ui/operation/index.js b/dist/ui/operation/index.js +index 6f879bf06d23b67cfda0016612bdfa5971a6d4a8..682096032cfbb467d3fbdf6bf26aeacfb61afa01 100644 +--- a/dist/ui/operation/index.js ++++ b/dist/ui/operation/index.js +@@ -84,7 +84,7 @@ export async function Operation({ type = 'operation', path, method, ctx, showTit + }); + authNode = (_jsxs(SelectTabs, { defaultValue: items[0].value, children: [_jsxs("div", { className: "flex items-start justify-between gap-2 mt-10 mb-5", children: [ctx.renderHeading(headingLevel, 'Authorization', { + className: 'my-0!', +- }), items.length > 1 ? (_jsx(SelectTabTrigger, { items: items })) : (_jsx("p", { className: "not-prose", children: items[0].label }))] }), securities.map((security, i) => (_jsx(SelectTab, { value: items[i].value, children: Object.entries(security).map(([key, scopes]) => { ++ }), items.length > 1 ? (_jsx(SelectTabTrigger, { items: items })) : (_jsx("div", { className: "not-prose", children: items[0].label }))] }), securities.map((security, i) => (_jsx(SelectTab, { value: items[i].value, children: Object.entries(security).map(([key, scopes]) => { + const scheme = securitySchemes?.[key]; + if (!scheme) + return; diff --git a/scripts/check-heading-case.ts b/scripts/check-heading-case.ts new file mode 100644 index 0000000..3b232bc --- /dev/null +++ b/scripts/check-heading-case.ts @@ -0,0 +1,63 @@ +import { Glob } from "bun"; + +// House style is sentence case: only the heading's first word, acronyms, and +// a short list of proper nouns stay capitalized. This flags headings that +// read as Title Case instead, so a page doesn't regress once it's fixed. +const PRESERVE_EXACT = new Set([ + "cURL", + "Postman", + "Whitepages", + "JavaScript", + "Python", + "I", +]); + +function isAcronymWord(word: string): boolean { + return /^[A-Z]{2,}s?$/.test(word); +} + +// A token with a digit is a version or identifier (V2, 429), not prose, so +// case doesn't apply to it. +function isVersionOrIdentifier(word: string): boolean { + return /\d/.test(word); +} + +// Sentence case lowercases everything after the first word, so any later +// word that isn't an acronym or an allow-listed proper noun and still +// starts with a capital letter is a violation on its own — no ratio needed. +function isTitleCaseHeading(heading: string): boolean { + const withoutCode = heading.replace(/`[^`]+`/g, ""); + const words = withoutCode.match(/[A-Za-z][A-Za-z0-9'-]*/g) ?? []; + + return words.some((word, i) => { + if (i === 0) return false; + if (isAcronymWord(word)) return false; + if (isVersionOrIdentifier(word)) return false; + if (PRESERVE_EXACT.has(word)) return false; + + return /^[A-Z]/.test(word); + }); +} + +const glob = new Glob("content/docs/**/*.mdx"); +const violations: string[] = []; + +for await (const file of glob.scan(".")) { + const text = await Bun.file(file).text(); + const lines = text.split("\n"); + + lines.forEach((line, i) => { + const match = line.match(/^(#{2,3}) (.+)$/); + if (!match) return; + if (isTitleCaseHeading(match[2])) { + violations.push(`${file}:${i + 1} ${match[2]}`); + } + }); +} + +if (violations.length > 0) { + console.error("Title Case headings found (house style is sentence case):\n"); + for (const violation of violations) console.error(` ${violation}`); + console.error(`\n${violations.length} violation(s)`); + process.exit(1); +} diff --git a/scripts/generators/openapi/openapi.facets.ts b/scripts/generators/openapi/openapi.facets.ts index 3250efd..f0e33c3 100644 --- a/scripts/generators/openapi/openapi.facets.ts +++ b/scripts/generators/openapi/openapi.facets.ts @@ -88,6 +88,7 @@ const FILE_KEYWORDS: Record = { const FILE_RELATED: Record = { "phone-v2/get_phone_by_number_v2.mdx": [ + "/documentation/phone-search", "/documentation/person-search/reverse-phone-lookup", "/documentation/agentic-guidance/capability-map", "/references/person-v2/search_person_by_name_phone_or_address_v2", diff --git a/src/app/[[...slug]]/page.tsx b/src/app/[[...slug]]/page.tsx index 719a20a..17ca427 100644 --- a/src/app/[[...slug]]/page.tsx +++ b/src/app/[[...slug]]/page.tsx @@ -1,4 +1,5 @@ import { getPageImage, source } from "@/lib/source"; +import { absoluteDocsUrl } from "@/lib/site-url"; import { DocsBody, DocsDescription, @@ -10,6 +11,8 @@ import { getMDXComponents } from "@/mdx-components"; import type { Metadata } from "next"; import { createRelativeLink } from "fumadocs-ui/mdx"; import { RelatedLinks, type RelatedLink } from "@/components/related-links"; +import { getBreadcrumbItems } from "fumadocs-core/breadcrumb"; +import { buildStructuredData, toScriptSafeJson } from "@/lib/structured-data"; function resolveRelatedLinks(urls: readonly string[]): RelatedLink[] { return urls.flatMap((url) => { @@ -33,8 +36,36 @@ export default async function Page(props: PageProps<"/[[...slug]]">) { const MDX = page.data.body; const relatedLinks = resolveRelatedLinks(page.data.related); + // Matches the items PageBreadcrumb renders with its own defaults, so the + // schema never asserts a trail the reader doesn't see. A non-string name + // is dropped rather than mislabeled with this page's own title. + const breadcrumb = getBreadcrumbItems(page.url, source.pageTree).flatMap( + (item) => { + if (typeof item.name !== "string") return []; + return [ + { + name: item.name, + url: item.url ? absoluteDocsUrl(item.url) : undefined, + }, + ]; + }, + ); + + const structuredData = buildStructuredData( + { + url: absoluteDocsUrl(page.url), + title: page.data.title, + description: page.data.description, + }, + breadcrumb, + ); + return ( + "); + expect(JSON.parse(json.replace(/\\u003c/g, "<"))).toEqual({ + headline: "" would otherwise close +// the tag this JSON is embedded in early. `<` never appears unescaped in +// valid JSON, so replacing it is safe for any input. +export function toScriptSafeJson(data: unknown): string { + return JSON.stringify(data).replace(/