From 5a375640b033c97fb41df2cbed16c10b4ae03a6d Mon Sep 17 00:00:00 2001 From: Taylor Richards Date: Tue, 2 Jun 2026 18:14:11 -0400 Subject: [PATCH] docs: update billing policy and document address id support Billing changes effective 2026-06-01: billable responses are 2xx everywhere plus 404 on person and property endpoints, except 404 on GET /v2/property/{property_id}, which is never billed to encourage optimistic lookups by address ID. No other response is billed. Document that /v2/property/{property_id} accepts either a property ID (R prefix) or an address ID (A prefix), regenerate the reference page from the live spec, and add a changelog entry. Archive the prior policy at an unlisted page, Billing Policy For Usage Prior to 2026-06-01, linked from the billing page and changelog. Also exclude the Internal Ledger tag from openapi generation so internal endpoints are never published to the public docs to reduce potential confusion about externally accessible vs internally accessible endpoints. --- content/docs/changelog/index.mdx | 27 +++++++++++ .../docs/documentation/getting-started.mdx | 2 +- .../docs/documentation/property-search.mdx | 15 ++++++ .../billing-prior-to-2026-06-01.mdx | 46 +++++++++++++++++++ content/docs/references/billing.mdx | 38 +++++++++++---- .../property-v2/get_property_by_id_v2.mdx | 12 +++++ .../generators/openapi/openapi.generator.ts | 16 +++---- scripts/generators/openapi/openapi.utils.ts | 8 +++- 8 files changed, 143 insertions(+), 21 deletions(-) create mode 100644 content/docs/references/billing-prior-to-2026-06-01.mdx diff --git a/content/docs/changelog/index.mdx b/content/docs/changelog/index.mdx index ebf7d35..e2e2645 100644 --- a/content/docs/changelog/index.mdx +++ b/content/docs/changelog/index.mdx @@ -5,6 +5,33 @@ description: Notable changes to the Whitepages API, newest first. --- +## June 1, 2026 + +### Address ID support on property details + +`GET /v2/property/{property_id}` now 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 look up property details directly +from the address IDs found throughout other API responses. + +Not every address ID has full property details, so lookups by address ID may +return `404`. These responses are not billed. + +### Billability changes + +Billing rules have been simplified: + +- `400 Bad Request` responses are no longer billable on any endpoint. +- `404 Not Found` responses on `GET /v2/property/{property_id}` are no longer + billable, so you can optimistically look up property details by address ID. + +`2xx` responses remain billable, as do `404` responses on all other endpoints. +See [Billing](/references/billing) for the full policy. These changes apply to +usage from June 1, 2026 onward — usage on or before May 31, 2026 is governed by +the [prior billing policy](/references/billing-prior-to-2026-06-01). + +--- + ## April 22, 2026 ### Pagination on v2 person search diff --git a/content/docs/documentation/getting-started.mdx b/content/docs/documentation/getting-started.mdx index 3830dde..72ba275 100644 --- a/content/docs/documentation/getting-started.mdx +++ b/content/docs/documentation/getting-started.mdx @@ -47,7 +47,7 @@ curl 'https://api.whitepages.com/v2/person?name=John%20Smith' \ --header 'X-Api-Key: YOUR_API_KEY' ``` -Responses are returned in JSON format. Each successful request that returns data consumes one billable query. +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 diff --git a/content/docs/documentation/property-search.mdx b/content/docs/documentation/property-search.mdx index f4fe26f..e53ee44 100644 --- a/content/docs/documentation/property-search.mdx +++ b/content/docs/documentation/property-search.mdx @@ -146,6 +146,21 @@ https://api.whitepages.com/v2/property/?street=1600%20Pennsylvania%20Ave%20NW&zi https://api.whitepages.com/v2/property/RVMKL8l80mK ``` +## 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: + +``` +https://api.whitepages.com/v2/property/{property_id_or_address_id} +``` + + + Not every address ID has full property details, so lookups by address ID may + return `404`. These responses are not billed — see + [Billing](/references/billing) — so you can optimistically look up property + details for any address ID you encounter. + + ## 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. diff --git a/content/docs/references/billing-prior-to-2026-06-01.mdx b/content/docs/references/billing-prior-to-2026-06-01.mdx new file mode 100644 index 0000000..ec4c367 --- /dev/null +++ b/content/docs/references/billing-prior-to-2026-06-01.mdx @@ -0,0 +1,46 @@ +--- +title: Billing Policy For Usage Prior to 2026-06-01 +description: Billing rules that applied to usage on or before May 31, 2026. +--- + +import { Callout } from "fumadocs-ui/components/callout"; + + + This policy applies only to usage on or before May 31, 2026. For usage from + June 1, 2026 onward, see the current [Billing](/references/billing) policy. + + +API usage was tracked and billed based on successful requests. + +## Billing Rules + +| Response Type | Billable | +| ------------------ | -------- | +| 2xx (Success) | Yes | +| 4xx (Client Error) | Yes | +| 5xx (Server Error) | No | +| 429 (Rate Limit) | No | + + + Only requests to Person and Property endpoints were charged. Account endpoints + were not billable. + + +## Billable Requests + +All `2xx` (success) and `4xx` (client error) responses from Person and Property endpoints were charged to your account. + +## 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 + +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. + +## Support + +For billing inquiries about usage during this period, please contact our team at api@whitepages.com. diff --git a/content/docs/references/billing.mdx b/content/docs/references/billing.mdx index 890f6a3..e769765 100644 --- a/content/docs/references/billing.mdx +++ b/content/docs/references/billing.mdx @@ -8,30 +8,48 @@ import { Callout } from "fumadocs-ui/components/callout"; API usage is tracked and billed based on successful requests. + + The billing rules below apply to usage from June 1, 2026 onward. For usage on + or before May 31, 2026, see the [Billing Policy For Usage Prior to + 2026-06-01](/references/billing-prior-to-2026-06-01). + + ## Billing Rules -| Response Type | Billable | -| ------------------ | -------- | -| 2xx (Success) | Yes | -| 4xx (Client Error) | Yes | -| 5xx (Server Error) | No | -| 429 (Rate Limit) | No | +| Response Type | Billable | +| ------------------ | -------------------------------------------- | +| 2xx (Success) | Yes | +| 404 (Not Found) | Yes, except `GET /v2/property/{property_id}` | +| 400 (Bad Request) | No | +| 403 (Forbidden) | No | +| 429 (Rate Limit) | No | +| 5xx (Server Error) | No | - Only requests to Person and Property endpoints are charged. Account endpoints - are not billable. + All Person and Property endpoints are billable, across every API version (v1 + and v2). Account, Regions, Events, and Webhooks endpoints are not billable. ## Billable Requests -All `2xx` (success) and `4xx` (client error) responses from Person and Property endpoints are charged to your account. +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 The following responses are **not** charged: -- `5xx` (server error) responses - issues on our end +- `400` (bad request) responses - missing or invalid parameters +- `403` (forbidden) responses - even when an API key is provided +- `404` (not found) responses on `GET /v2/property/{property_id}` - `429` (rate limit) responses - when you've exceeded rate limits +- `5xx` (server error) responses - issues on our end + +### Property details lookups and 404s + +`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 diff --git a/content/docs/references/property-v2/get_property_by_id_v2.mdx b/content/docs/references/property-v2/get_property_by_id_v2.mdx index 18d74d9..9d975de 100644 --- a/content/docs/references/property-v2/get_property_by_id_v2.mdx +++ b/content/docs/references/property-v2/get_property_by_id_v2.mdx @@ -3,6 +3,10 @@ title: Get property details by ID description: |- Retrieve detailed property information by Whitepages property ID. + Accepts either a Whitepages property ID (prefix ``R``) or an address ID + (prefix ``A``). Address IDs are resolved to the associated property + before lookup. + This endpoint returns comprehensive property data including physical characteristics, tax assessment information, ownership details, mortgage history, predictive insights, and current residents. @@ -21,6 +25,14 @@ _openapi: Retrieve detailed property information by Whitepages property ID. + Accepts either a Whitepages property ID (prefix ``R``) or an address + ID + + (prefix ``A``). Address IDs are resolved to the associated property + + before lookup. + + This endpoint returns comprehensive property data including physical characteristics, tax assessment information, ownership details, diff --git a/scripts/generators/openapi/openapi.generator.ts b/scripts/generators/openapi/openapi.generator.ts index ff78c4c..d13beeb 100644 --- a/scripts/generators/openapi/openapi.generator.ts +++ b/scripts/generators/openapi/openapi.generator.ts @@ -2,7 +2,7 @@ import { generateFiles } from "fumadocs-openapi"; import { createOpenAPI } from "fumadocs-openapi/server"; import type { OpenAPISpec } from "./openapi.types"; import { - DEPRECATED_TAGS, + EXCLUDED_TAGS, extractTagGroups, tagToDirectoryName, tagToDisplayName, @@ -30,14 +30,14 @@ async function generateApiEndpointDocs(): Promise { output: OUTPUT_DIR, groupBy: "tag", beforeWrite(files) { - const deprecatedDirectories = DEPRECATED_TAGS.map(tagToDirectoryName); - const nonDeprecatedFiles = files.filter( + const excludedDirectories = EXCLUDED_TAGS.map(tagToDirectoryName); + const includedFiles = files.filter( (file) => - !deprecatedDirectories.some((directory) => + !excludedDirectories.some((directory) => file.path.startsWith(`${directory}/`), ), ); - files.splice(0, files.length, ...nonDeprecatedFiles); + files.splice(0, files.length, ...includedFiles); }, }); } @@ -73,8 +73,8 @@ async function generateMetaFiles(openApiSpec: OpenAPISpec): Promise { } } -async function cleanupDeprecatedDirectories(): Promise { - for (const tag of DEPRECATED_TAGS) { +async function cleanupExcludedDirectories(): Promise { + for (const tag of EXCLUDED_TAGS) { const directoryPath = `${OUTPUT_DIR}/${tagToDirectoryName(tag)}`; await Bun.$`rm -rf ${directoryPath}`; } @@ -82,7 +82,7 @@ async function cleanupDeprecatedDirectories(): Promise { async function main(): Promise { const openApiSpec = await fetchOpenApiSpec(); - await cleanupDeprecatedDirectories(); + await cleanupExcludedDirectories(); await generateApiEndpointDocs(); await generateRoutesPage(openApiSpec); await generateMetaFiles(openApiSpec); diff --git a/scripts/generators/openapi/openapi.utils.ts b/scripts/generators/openapi/openapi.utils.ts index 5e64a8f..6c84891 100644 --- a/scripts/generators/openapi/openapi.utils.ts +++ b/scripts/generators/openapi/openapi.utils.ts @@ -2,6 +2,10 @@ import type { OpenAPISpec, TagGroup } from "./openapi.types"; export const DEPRECATED_TAGS = ["Property", "Person"]; +export const INTERNAL_TAGS = ["Internal Ledger"]; + +export const EXCLUDED_TAGS = [...DEPRECATED_TAGS, ...INTERNAL_TAGS]; + const TAG_DISPLAY_NAMES: Record = { "Person V2": "Person", "Property V2": "Property", @@ -28,7 +32,7 @@ function createTagGroupsFromSpec( const tagGroups = new Map(); for (const tag of openApiSpec.tags ?? []) { - if (DEPRECATED_TAGS.includes(tag.name)) { + if (EXCLUDED_TAGS.includes(tag.name)) { continue; } @@ -52,7 +56,7 @@ function addRoutesToTagGroups( const tagName = operation.tags?.[0] ?? "default"; - if (DEPRECATED_TAGS.includes(tagName)) { + if (EXCLUDED_TAGS.includes(tagName)) { continue; }