Repository navigation
docs: document the phone lookup endpoint - #66
Merged
Merged
Conversation
lhagenWP
force-pushed
the
phone-lookup-docs
branch
from
October 1, 2026 20:25
92c07e8 to
191f12b
Compare
A phone number has its own endpoint now, and the docs said the opposite.
The capability map told readers in a warning callout that no separate
phone lookup endpoint exists and to pass phone= to person search, which
becomes wrong the moment this ships.
Rewrite the reverse phone lookup guide around the two endpoints and
when each is the right one: /v2/phone/{phone} when the number is the
subject, person search when a person is and the number is one of the
criteria. The guide's example response was already wrong before this
change, showing a bare array where v2 person returns an object, so it
is replaced with a real response rather than patched.
Correct the capability map's callout and split its one phone row into
two, since the rows now answer different questions.
Generate the reference page from the published spec and give it facets:
the phone directory takes the person topic, since a lookup returns
people and businesses rather than warranting a facet of its own, and
person search now lists the phone reference among its related pages.
Add a changelog entry covering the endpoint, the facts it returns for a
number nobody is associated with, businesses reaching a response for
the first time, and how primary_owner should be read, and point the
changelog banner at it.
lhagenWP
force-pushed
the
phone-lookup-docs
branch
from
October 1, 2026 20:31
191f12b to
ec66e5c
Compare
lhagenWP
marked this pull request as ready for review
October 1, 2026 20:38
KevinEdry
approved these changes
Oct 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
A phone number has its own endpoint now, and these pages said the opposite. The
capability map carried a warning callout telling readers that no separate phone
lookup endpoint exists and to pass
phone=to person search.The endpoint is live:
GET /v2/phone/{phone}is routed in production andanswers alongside person search and property search.
What Changed
Reverse phone lookup guide, rewritten around the two endpoints and when
each is the right one.
GET /v2/phone/{phone}when the number is the subjectof the question;
GET /v2/person/withphone=when a person is the subjectand the number is one of the criteria. The page ends with a table for choosing
between them.
Its example response was already wrong before this change — it showed a bare
array, where v2 person returns an object with
resultsandmetadata. It isreplaced with a real response rather than patched around.
Capability map: the callout now describes both endpoints, and the single
phone row is split in two, since the rows answer different questions.
Reference page, generated from the published spec, with facets wired in
openapi.facets.ts. The phone directory takes thepersontopic — a lookupreturns people and businesses, which does not warrant a facet value of its own
— and person search now lists the phone reference among its related pages.
Changelog: an entry covering the endpoint, the facts returned for a number
nobody is associated with, businesses reaching a response for the first time,
and how
primary_ownershould be read. The banner points at it.Context
Example values in the guide and the changelog are real responses captured from
a running service rather than invented, so field names and shapes match what a
caller receives. The generated reference page was checked against the published
spec and matches it exactly.
Noted for a separate change, not fixed here: the generated description for
this endpoint carries the implementation's docstring sections verbatim,
including parameter names that mean nothing to a caller. The person, property
and deed-event reference pages have the same problem, so this page is
consistent with its siblings rather than newly broken, but the source of all
four is worth tidying.