CNAM & Caller ID
Register the branded outbound Calling Name (CNAM) displayed on the recipient’s handset for each of your numbers, query what a carrier currently has registered, and remediate “Spam Likely” / “Scam Likely” labels that hurt your answer rate. Every verb is gated by org ownership — a sibling subaccount sharing your tenant schema cannot read or mutate another subaccount’s registration.Carrier-side LIDB/CNAM writes run only on the Devotel wholesale softswitch (the carrier of record). The API layer captures and enqueues your desired name — it never wires a third-party CNAM write directly. Captured registrations stay
pending until dispatched.Display-Name Rules
CNAM display names must fit the PSTN LIDB/CNAM on-wire field, and the API enforces that constraint up front instead of silently truncating on the handset:
Normalisation runs on every request before validation: leading/trailing whitespace is trimmed, internal whitespace runs collapse to a single space, and the result is uppercased.
" acme support " becomes "ACME SUPPORT" before the length and charset checks run.
A name that breaks the rules returns 422 with the failing constraint:
Register a Caller Name
display_name (another PUT) resets the lifecycle to pending, so a stale active verdict cannot linger after the name changed.
Lifecycle
A registration moves through a predictable lifecycle you can observe onGET /numbers/:id/cnam:
Dispatch ETA: LIDB/CNAM propagation is a carrier database update, not a real-time switch — expect propagation to take days, not minutes. Even after the wholesale write succeeds, some carriers cache the prior name until that cache expires.
Dispatch the Registration
Hand the captured name to the Devotel wholesale CNAM/LIDB provisioning queue. This advances the registrationpending/failed → submitted and stamps submitted_at. Until you dispatch, the name never appears on a handset.
404 when there is no captured registration, and 409 when it is already submitted/active.
CNAM Dip (carrier inquiry)
Query what display name a carrier currently has registered for one of your numbers — independent of your locally-captured registration.status: "coming_soon" with carrier_registered_name: null — the result echoes your local registration so you can reconcile desired-vs-carrier in one round-trip once the dip wires.
Reconciling Dip vs. Local
Once the dip provider wires, the response carries both the carrier-registered name and your local registration, so the comparison is one round-trip. When the carrier answer differs from what you registered locally, treat the carrier’s answer as authoritative — your localdisplay_name is what you asked for; the carrier value is what actually displays on the handset.
carrier_registered_name disagrees with local_registration.display_name, re-register (PUT …/cnam) with the correct name and re-dispatch — the carrier database cannot be assumed to reflect your latest capture until the wholesale write runs.
Spam Labels
Read the cross-carrier spam-label snapshot observed on a number, with a derived severity summary. Spam labels are not yet automatically polled from carrier reputation APIs and will appear empty until this feature is released.Remediate Spam Labels
File a cross-carrier remediation request against an observed label set.
Returns
422 when the number is clean (nothing to remediate) and 404 when the number doesn’t exist.
Remediation lifecycle: the API captures the request with submitted_at and queues it for the Devotel wholesale CNAM side-band. Submitted now, reviewed later means the request is durably captured immediately — so it cannot be lost or duplicated while waiting — and the authoritative carrier dispute then runs as the operator-managed side-band process on the Devotel wholesale queue, not as a synchronous carrier API call. Check GET …/cnam/spam-labels to see the current remediation status linked to the submitted request.