> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# The Caller IDs surface under Voice

> What the /voice/caller-ids dashboard page does — the register-and-verify lifecycle for outbound caller IDs, which number sources it reads, which formats it accepts, and how the page-level description sets the verification contract.

# The Caller IDs surface under Voice

**Voice → Caller IDs** (`/voice/caller-ids`) is the dashboard surface that
drives the [outbound caller-ID API](/guides/voice-caller-ids): 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](/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](/guides/buy-numbers)
   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](/channels/voice/stir-shaken) and
  [CNAM & caller ID](/numbers/cnam) for the display-name layer on top.

<Note>
  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.
</Note>

## See also

* [Manage outbound caller IDs](/guides/voice-caller-ids) — the API-level verification lifecycle behind this surface.
* [Validate caller-ID coverage before a campaign](/guides/caller-id-coverage-validation) — audit which destination area codes your pool can present.
* [CNAM & caller ID](/numbers/cnam) — register the branded name carriers display.
* [STIR/SHAKEN attestation](/channels/voice/stir-shaken) — how attestation levels resolve.
* [Place your first outbound voice call](/guides/first-outbound-voice-call) — present a verified caller ID on a real call.