From 67c9e2af44c0c180f24f3b9d304dda19c994d5cd Mon Sep 17 00:00:00 2001 From: Taylor Richards Date: Wed, 17 Jun 2026 11:31:22 -0400 Subject: [PATCH] docs(mcp): add agentic guidance docs and integrator FAQ Add core-tier authored knowledge for agents under a new Agentic Guidance section: a capability map (intent to endpoint+params), an integration guide (the prescribed workflow), and an entity-shapes caveat (the same entity differs by endpoint; read the type document). Add an integrator FAQ at the documentation root covering trial exhaustion, how rate limits apply, and what counts as a breaking change. All pages carry lifecycle/topic/keywords facets. --- .../agentic-guidance/capability-map.mdx | 67 +++++++++++++++++++ .../agentic-guidance/entity-shapes.mdx | 42 ++++++++++++ .../agentic-guidance/integration-guide.mdx | 52 ++++++++++++++ .../documentation/agentic-guidance/meta.json | 5 ++ content/docs/documentation/faq.mdx | 43 ++++++++++++ content/docs/documentation/meta.json | 2 + 6 files changed, 211 insertions(+) create mode 100644 content/docs/documentation/agentic-guidance/capability-map.mdx create mode 100644 content/docs/documentation/agentic-guidance/entity-shapes.mdx create mode 100644 content/docs/documentation/agentic-guidance/integration-guide.mdx create mode 100644 content/docs/documentation/agentic-guidance/meta.json create mode 100644 content/docs/documentation/faq.mdx diff --git a/content/docs/documentation/agentic-guidance/capability-map.mdx b/content/docs/documentation/agentic-guidance/capability-map.mdx new file mode 100644 index 0000000..9e11648 --- /dev/null +++ b/content/docs/documentation/agentic-guidance/capability-map.mdx @@ -0,0 +1,67 @@ +--- +title: Capability Map +description: Map a user's intent to the exact endpoint and parameters that answer it. +icon: Compass +lifecycle: current +topic: getting-started +keywords: + - "capability map" + - "which endpoint do I use" + - "what endpoint for" + - "intent to endpoint" + - "reverse phone lookup" + - "who lives at this address" + - "who owns this property" + - "how do I find a person" +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +Start here. This table maps what you are trying to do to the endpoint and parameters that do it. Match the intent, copy the parameters, then read the [type document](/references) for that endpoint before writing your types. + + + **Person search is one endpoint.** Reverse phone lookup, address lookup, and + name search are all the same `GET /v2/person/` call with different parameters. + There is no separate "phone lookup" endpoint — pass `phone=` to person search. + + +## People + +| You want to… | Endpoint | Key parameters | +| ---------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------- | +| Reverse phone lookup (who owns a number) | `GET /v2/person/` | `phone=` | +| 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`, `include_historical_locations`, `radius` | +| Page through person results | `GET /v2/person/` | `page`, `page_size` | +| Get full detail for a known person | `GET /v2/person/{id}` | path `id` (the `id` from any person object) | + +A person search returns results scored by `match_score` (1–99). See [Entity Shapes](/documentation/agentic-guidance/entity-shapes) for how a person's shape differs by context. + +## Property + +| You want to… | Endpoint | Key parameters | +| ------------------------------------ | ----------------------- | ----------------------------------------------------------------- | +| Find who owns a property | `GET /v2/property/` | `street`, `city`, `state_code`, `zipcode` → read `ownership_info` | +| Find current residents of a property | `GET /v2/property/` | same address params → read `residents` | +| Get property detail by id | `GET /v2/property/{id}` | path id (`R`-prefixed property id or `A`-prefixed address id) | + + + Owners and residents come back as **summary** person objects that carry an + `id`. To get full detail (date of birth, relatives, historic addresses), call + `GET /v2/person/{id}` with that `id` — see [Entity + Shapes](/documentation/agentic-guidance/entity-shapes). + + +## Events and account + +| You want to… | Endpoint | Key parameters | +| ---------------------------------------- | ------------------------ | ------------------------------------------ | +| Find deed events / property transactions | `GET /v1/events/deed` | see [Events reference](/references/events) | +| Check usage / remaining quota | `GET /v1/account/usage/` | date range | + +## What's next + +- [Integration Guide](/documentation/agentic-guidance/integration-guide) — the workflow to follow before writing integration code. +- [Entity Shapes](/documentation/agentic-guidance/entity-shapes) — the shapes you get back and how to hydrate summaries. +- [FAQ](/documentation/faq) — trial limits, rate limits, and breaking changes. diff --git a/content/docs/documentation/agentic-guidance/entity-shapes.mdx b/content/docs/documentation/agentic-guidance/entity-shapes.mdx new file mode 100644 index 0000000..6eda430 --- /dev/null +++ b/content/docs/documentation/agentic-guidance/entity-shapes.mdx @@ -0,0 +1,42 @@ +--- +title: Entity Shapes by Context +description: The same entity comes back in different shapes depending on the endpoint. Do not assume one shape. +icon: Boxes +lifecycle: current +topic: person +keywords: + - "person shape" + - "response shape" + - "owner summary" + - "resident summary" + - "hydrate person" + - "person by id" + - "different shapes" +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +The same entity does not come back the same way everywhere. A person from one endpoint and a person from another are **different shapes** — and so are addresses. This page exists to make that one caveat unmistakable; for the exact fields, read the [type document](/references) for the endpoint you are calling. + + + **Do not assume one shape.** A type you build from one endpoint's response + will not fit another's. Always read the endpoint's type document for the shape + it actually returns. + + +## A person comes back in three kinds + +- **Fetched by id** — `GET /v2/person/{id}` returns the full person record. +- **As a search result** — `GET /v2/person/` returns persons as scored, paginated results. Same entity, presented with relevance and list context. +- **Embedded in a property** — owners and residents inside a property response are a **reduced** form of a person, not the full record. + +These are not interchangeable. The embedded form in particular carries far less than the full record. + + + **Reduced forms carry an `id`.** When you get a person embedded in a property + response and need the full record, hydrate it with `GET /v2/person/{id}`. + + +## Addresses also differ by context + +An address is not one shape either: a person's address and a property's own address carry different fields. As with persons, do not reuse one address type across endpoints — check the type document for the endpoint you are calling. diff --git a/content/docs/documentation/agentic-guidance/integration-guide.mdx b/content/docs/documentation/agentic-guidance/integration-guide.mdx new file mode 100644 index 0000000..fcfcc67 --- /dev/null +++ b/content/docs/documentation/agentic-guidance/integration-guide.mdx @@ -0,0 +1,52 @@ +--- +title: Integration Guide +description: The workflow to follow when integrating the Whitepages API, by hand or with an agent. +icon: Workflow +lifecycle: current +topic: getting-started +keywords: + - "integration guide" + - "how to integrate" + - "agent workflow" + - "writing types" + - "best practices" + - "how should I call the api" +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +This is the prescribed workflow for integrating the API. Follow it in order; each step removes a mistake we have seen integrations make. + +## The workflow + +1. **Map the intent first.** Use the [Capability Map](/documentation/agentic-guidance/capability-map) to turn what you want ("reverse phone lookup", "who owns this property") into the endpoint and parameters. Do not guess at endpoints — person search is also phone search and address search. +2. **Read the type document before writing types.** Each endpoint has a [reference](/references) carrying its request and response schema. That schema is the authoritative source for the shapes you integrate against. +3. **Never infer types from sample responses.** Example payloads omit `null` and optional fields and show only one variant. A type built from an example will be wrong. Build types from the schema, not the sample. +4. **Ignore unknown fields.** Adding a new field to a response is [not a breaking change](/references/versioning/breaking-changes-policy). Parse the fields you need and tolerate fields you do not, so new fields never break you. +5. **Hydrate summaries by id.** Nested person objects (property owners, residents) are summaries that carry an `id`. Fetch full detail with `GET /v2/person/{id}`. See [Entity Shapes](/documentation/agentic-guidance/entity-shapes). + +## What costs money + + + **Documentation is free; data costs money.** Reading these docs and the + capability map never bills your key. Data calls (person search, property + lookup, account usage) are billed identically whether made over REST or the + MCP server. + + +Billing follows the response status: successful (`2xx`) and client-error (`4xx`) responses are billed; throttling (`429`) and server errors (`5xx`) are not. A `404` on a property lookup by address id is **not** billed, so you can optimistically resolve any address id you encounter. See [Billing](/references/billing). + +## Authentication + +Pass your key in the `X-Api-Key` header on every data call. The key is a bearer secret: never log it, echo it back, or place it in a URL. + +## Breaking changes, in one line + +Breaking changes ship only in a new API version, with at least 30 days' notice; within a version, response shapes only grow. Read the full [Breaking Changes Policy](/references/versioning/breaking-changes-policy) before you depend on a shape. + +## Gotchas + +- **Person search is one endpoint** — phone, address, and name search are all `GET /v2/person/` with different parameters. +- **Addresses differ by context** — a person's addresses and a property's address are not the same shape. See [Entity Shapes](/documentation/agentic-guidance/entity-shapes). +- **Property addresses are not CASS-standardized** — they come from county assessor records as-received. +- **Trial keys exhaust** — when usage runs out you get `Limit Exceeded`, distinct from a `429`. See the [FAQ](/documentation/faq). diff --git a/content/docs/documentation/agentic-guidance/meta.json b/content/docs/documentation/agentic-guidance/meta.json new file mode 100644 index 0000000..26887dd --- /dev/null +++ b/content/docs/documentation/agentic-guidance/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Agentic Guidance", + "icon": "Bot", + "pages": ["capability-map", "integration-guide", "entity-shapes"] +} diff --git a/content/docs/documentation/faq.mdx b/content/docs/documentation/faq.mdx new file mode 100644 index 0000000..49f249a --- /dev/null +++ b/content/docs/documentation/faq.mdx @@ -0,0 +1,43 @@ +--- +title: FAQ +description: Answers to the questions integrators hit most often. +icon: CircleQuestionMark +lifecycle: current +topic: getting-started +keywords: + - "faq" + - "frequently asked questions" + - "trial ran out" + - "trial exhausted" + - "how are rate limits applied" + - "what counts as a breaking change" + - "is person search the same as phone lookup" +--- + +import { Callout } from "fumadocs-ui/components/callout"; + +## What do I do when my trial usage runs out? + +When a trial key uses up its allowance, data calls return `Limit Exceeded` (not a `429`). The allowance does not refill — to keep going, [purchase a plan](/documentation/purchasing-api) or contact `api@whitepages.com`. Documentation calls keep working regardless; only data calls consume the allowance. See [Rate Limits](/references/rate-limits#monthly-query-limits--trial-exhaustion). + +## How are rate limits applied? + +There are two distinct limits: + +- **`429 Too Many Requests`** — short-term throttling. Back off and retry with exponential backoff; it clears on its own. +- **`Limit Exceeded`** — you have used up your monthly plan limit or trial allowance. It persists until your quota resets (next month for a plan) or you upgrade. + +Neither a `429` nor a `5xx` is billed. See [Rate Limits](/references/rate-limits). + +## What counts as a breaking change? + +Removing or renaming an endpoint or field, changing a field's type, adding a required parameter, or changing auth or error formats. **Adding** a new optional parameter, a new field, a new endpoint, or a new enum value is **not** breaking — so always ignore unknown fields. Breaking changes ship only in a new API version with at least 30 days' notice. Full detail: [Breaking Changes Policy](/references/versioning/breaking-changes-policy). + +## Is person search the same as phone lookup? + +Yes. Reverse phone lookup, address lookup, and name search are all the same `GET /v2/person/` endpoint with different parameters — pass `phone=` for a reverse phone lookup. There is no separate phone endpoint. See the [Capability Map](/documentation/agentic-guidance/capability-map). + + + Not seeing your question? Use `search_documentation` over the MCP server, or + email `api@whitepages.com`. + diff --git a/content/docs/documentation/meta.json b/content/docs/documentation/meta.json index 5637e55..28b39d9 100644 --- a/content/docs/documentation/meta.json +++ b/content/docs/documentation/meta.json @@ -14,6 +14,8 @@ "regions", "property-search", "...mcp", + "agentic-guidance", + "faq", "---LLMs---", "[Docs List](/llms.txt)", "[Full Docs](/llms-full.txt)"