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; }