docs(rest): add the CNAM (caller ID name) API for phone numbers - #638
Merged
Conversation
Adds the three caller ID name operations on a phone number, following the
existing /{id}/e911_address sub-resource pattern so they file under the
Phone Numbers tag with no nav change:
GET /api/relay/rest/phone_numbers/{id}/cnam
POST /api/relay/rest/phone_numbers/{id}/cnam
DELETE /api/relay/rest/phone_numbers/{id}/cnam
Also adds the `cnam` attribute to the phone number model, which the
serializer already returns but the spec omitted. It is the name live at
the carrier, as distinct from the requested name a CNAM request carries.
Verified against prime-rails: the controller, serializer, contracts,
operations, CnamRequest model, the four Job::Cnam jobs, and the request
spec. Three departures from the shape proposed in the issue:
- No maxLength/pattern on the POST body `name`. Validation runs on the
normalized form (control chars stripped, whitespace squished,
upper-cased), so a 19-character lowercase input can be valid and those
constraints would reject it. The rules are described in prose instead.
The response-side `name` and `cnam` do carry maxLength 15, matching
their string(15) columns.
- `reason` is nullable in every status, not only pending and approved.
Job::Cnam::Process holds an unverified account for review, and rejects
a suspended one, before review assigns any reason.
- 401 and 404 reuse the shared Types.StatusCodes models rather than
declaring text/plain bodies. The real bodies are plain text, but that
mismatch is repo-wide and a CNAM-only divergence would read as drift.
POST does not always return `pending`: Cnam::RequestReview reuses an
already-approved row for the same name on the same number without
resetting it, so that case returns 201 with status still `approved` and
re-applies at the carrier without re-review. Documented as the exception,
along with rejected/failed returning to `pending` on re-request.
The 13 reason codes are documented as a table on the `reason` field:
per-member enum @doc does not survive emission, so that is the only place
a reader sees what each code means.
Two guides said CNAM could only be set by opening a support ticket, which
the API and the dashboard's Caller ID Name field supersede. Both now
point at the self-serve routes and keep the ticket as the fallback for
numbers whose carrier does not offer CNAM.
Closes #634
Contributor
hey-august
self-requested a review
August 27, 2026 19:24
hey-august
approved these changes
Aug 31, 2026
hey-august
left a comment
hey-august
left a comment
Collaborator
There was a problem hiding this comment.
Looks good, comments addressed. Approving!
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.
Summary
cnamvalue to phone number responses.Validation
yarn build:specsyarn fern-md-check— all 2,823 MDX files validgit diff --checkyarn fern-check --warnings— known pre-existing environmental findings reproduced onmainCloses #634