Skip to main content

​
The Caller IDs surface under Voice

Voice → Caller IDs (/voice/caller-ids) is the dashboard surface that drives the outbound caller-ID API: register a personal or partner phone number, prove control of it with a one-time code, and manage the verified numbers your outbound calls can present. This page is about the surface itself — what it shows you, what it accepts, and what its own description commits to — so an operator landing on it knows exactly which contract the table upholds. Use it when a desk line, a partner number, or a legacy outside number needs to appear on outbound calls without porting it into Orbit. For the endpoint-level contract (request shapes, status codes, attestation precedence), the API guide at /guides/voice-caller-ids goes deeper; this page stays at the surface level. Surface: /voice/caller-ids, read-only list plus Create/Resume/Resend/ Restart/Revoke actions.

​
1. What the surface does

The page is one list — every caller ID registered on your workspace — plus a two-step creation dialog. Three things to read on any visit:
  • The counts strip — Verified vs Awaiting verification. Verified is the number of caller IDs currently presentable on outbound calls; Awaiting is the backlog sitting between registration and confirm.
  • The table — one row per registered caller ID: phone number, optional label, status pill, when the row was created, when the last code was sent (with the attempt count and delivery method beneath it), and the verified timestamp. Statuses are the same lifecycle the API reports: pending, verifying, verified, expired, revoked.
  • The row actions — status-dependent. A pending or verifying row offers Resume (open the confirm step against the existing challenge) and Resend (re-deliver the code, rate-capped per recipient). An expired row offers Restart (re-run the registration to mint a fresh challenge). Any settled row offers Revoke, behind a destructive confirm.
Creation is a dialog, not a wizard: enter the number, an optional label, and the verification method (a voice call that reads the code aloud, or an SMS), then submit the code on the second step of the same dialog. The dialog keeps the candidate number visible while you type the code and names the delivery method the code actually went out on, so you know whether to watch an inbox or answer a call. Access is role-gated: the surface is visible to workspace owner, admin, and developer roles.

​
2. Verification contract — what is consulted and what is accepted

The surface validates the caller-ID format locally, then hands the number to the verification service, which is the authoritative source for everything else:
  • Number format. The entry field accepts E.164 only — a leading + followed by 8–15 digits, first digit non-zero. Anything short of that is rejected inline before a request is made; the backend re-validates the same shape and is the final word.
  • Verification channel. Exactly two delivery methods are accepted — the voice call and the SMS. The code is dispatched through Orbit’s outbound voice/SMS path, so there is no third-party carrier account to configure and no off-network channel (WhatsApp, email) to pick.
  • Status registry. The list reads your workspace’s caller-ID registry. Every row reflects the registry’s current lifecycle state plus its challenge history — last dispatch time, delivery method, and the code-attempt count — so a stuck registration shows where it stopped without leaving the page.
  • Duplicate and re-claim handling. Registering a number that is already verified is rejected; a previously revoked row for the same number is re-claimed by a fresh registration rather than duplicated. Restart re-uses the registration call, so an expired challenge converts to a fresh one on the same row.
Resend is rate-capped per recipient (five dispatches per hour by default). When the cap is hit, the surface shows the cooldown inline — as a countdown on the affected control — rather than a bare error.

​
3. Best-practices contract — the page’s own description

The surface’s page-level description in code states its scope in one sentence and the subtitle next to the heading says it to operators:
Verify personal or partner phone numbers as outbound caller-ID via OTP-back challenge.
Three commitments fall out of that description, and the page is built to keep them:
  1. Personal or partner numbers only. This surface proves you control a number you already have; it does not mint new numbers. If the number you want to present does not exist yet, buy or port it into Orbit and it presents without a verification step.
  2. Verification before presentation. A number is not presentable until its row is verified. The counts strip and the status pills exist to make that gate visible at a glance — treat any non-verified row as not yet usable for outbound, and use Resume/Resend/Restart to push it over the line.
  3. Challenge dispatched on Orbit’s path. The one-time code travels over the same outbound voice/SMS path every other Orbit call uses, and the surface names the delivery method after every dispatch. If a code does not arrive, re-send from the same row before starting over — resends preserve the row and its verification id.
Housekeeping practices that keep the list honest:
  • Label every row with the optional friendly name. It is an operator label shown in this table only — it never displays on a recipient handset — but it is the difference between a list you can audit and a list of raw digits.
  • Revoke numbers that leave your control (a departed employee’s mobile, a partner line you no longer may use). Revoke is immediate and reversible by re-registering; leaving stale verified rows is a presentation risk.
  • Prefer owned numbers for US traffic. A verified external caller ID caps at STIR/SHAKEN attestation level B; an Orbit-owned number attests at A. When answer rate matters, run the traffic from numbers you own — see STIR/SHAKEN attestation and CNAM & caller ID for the display-name layer on top.
Every control on this surface is tenant-owned. Orbit verifies the number you prove control of and presents it on your outbound calls; deciding which numbers your traffic may show, and the regulatory posture of that presentation, stays with your workspace. Codes and calls dispatched from this page egress only through Orbit’s outbound voice/SMS path.

​
See also