> ## 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.

# Toll-Free Verification and RespOrg lifecycle

> How Orbit runs US toll-free numbers end-to-end — the Toll-Free Verification (TFV) lifecycle from use-case declaration to carrier decision, the staged 'pending platform submission' state, the RespOrg change flow for toll-free voice numbers, and how TFV state plugs into the daily-cap and warming kernels.

# Toll-Free Verification and RespOrg lifecycle

US toll-free numbers (800/833/844/855/866/877/888 prefixes) sit in their
own regulatory lane: carriers do not weigh 10DLC registration for them,
and they impose their own throughput penalties on unverified senders
instead. Orbit handles toll-free from two directions — the SMS surface
(Toll-Free Verification, `POST /numbers/:id/tfv-submit`) and the voice
surface (the SMS/800 RespOrg — Responsible Organization — change
workflow). This page is the lifecycle model for both.

## 1. Where toll-free fits in the sender-identity taxonomy

The sender-identity classifier resolves every `from` value to one of
five classes — `alphanumeric`, `short_code`, `toll_free`, `long_code`,
or `unknown` — before any gate or registration decision applies. A NANP
`+1` number on a toll-free prefix beats the geographic long-code branch
and becomes `toll_free`, which is what puts the verification lane on
deck. See
[Sender identity classification model](/concepts/sender-identity-classification-model)
for the full mapping.

The classes are ordered by explicit prefix checks, not by likelihood:

| Class          | Registration lane                                      | Notes for toll-free relevance                                                             |
| -------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `long_code`    | 10DLC (US) or alphanumeric sender-ID (other corridors) | The fallback a toll-free prefix check beats                                               |
| `toll_free`    | Toll-Free Verification (this page)                     | Carrier-graded throughput; unverified senders are throttled by the US carriers            |
| `short_code`   | Short-code lease + carrier approval                    | Does not enter the TFV lane                                                               |
| `alphanumeric` | Per-country sender-ID registration                     | US/Canada carriers reject it — toll-free and long-code are the only US/Can A2P SMS shapes |
| `unknown`      | Re-check the stored identity                           | Bad strings stay unknown until they are corrected                                         |

The `toll_free` label does not describe a brand — it describes the
number shape. Everything after this label resolves (whether to run TFV,
which gate to apply, which daily cap to land) hangs off the classifier's
five-output verdict.

## 2. The TFV lifecycle — draft, pending, and terminal verdicts

TFV moves a per-number row on the tenant schema through a four-state
status enum: `not_submitted` → `pending` → `approved` or `rejected`.

1. **Draft** — the row exists but has stored no payload yet. The
   persisted shape of the draft is what the dashboard fills in before it
   calls `POST /numbers/:id/tfv-submit`.
2. **Submit** — `POST /numbers/:id/tfv-submit` validates the payload
   server-side (same rules the dashboard form enforces), then routes the
   submission to the carrier that owns the DID. Twilio-imported DIDs go
   to Twilio's Tollfree Verifications endpoint; Telnyx-owned DIDs go to
   Telnyx's Verification Requests API; a DID that is not wired to either
   (Bandwidth-hosted, inventory placeholder, credentials absent) is
   staged locally so the reconciler retries the next time the
   credentials state changes.
3. **Pending platform submission (staged-local)** — when the carrier
   could not be reached, `tfv_status` lands at `pending` with
   `tfv_provider = 'platform_staged'` and a synthetic `tfv_local_*`
   submission id. The dashboard renders the same state it would for a
   live submission, so a missing-creds tenant is not told the number is
   safe. The background reconciler (and the on-demand refresh button)
   re-attempts the carrier call on every poll; a call that went live on
   retry advances exactly the same way as a first-call success. This is
   the staged-submission state — not a separate status, but the same
   `pending` state with a staged provider label.
4. **Carrier decision** — a background reconciler polls every pending
   submission until the carrier returns a terminal verdict, which is
   normalized onto the same four-state enum (`approved`, `rejected`,
   `pending`, or null for transient errors). The on-demand "refresh"
   button forces that poll for one DID and persists the verdict on first
   read; an operator can also re-submit the form if a rejection was
   down-weighted by a missing field.

The submission payload itself carries the review context the carrier
asks for: a use-case category (one of the `TFV_USE_CASES` enum), a
40–500 character use-case summary, 1–5 production sample messages, the
opt-in mechanism and at least one opt-in evidence URL, the business
name/website/contact, and either a US EIN or a business-registration
number plus its ISO-3166 country. A Political use case additionally
requires a Campaign Verify authorization token — the field is validated
at the API boundary so a missing token fails fast with a 422 rather
than a carrier rejection days later.

## 3. What a reviewer looks for in sample messages and the use case

The carrier decision lands on the content of the submission, so the
reviewer's checklist matches what the form collects:

* **Use-case alignment** — the `useCase` category and
  `useCaseSummary` must agree with the sample messages; a 2FA category
  carrying marketing copy is a rejection trigger.
* **Sample messages** — 1–5 production bodies, each 1–1024 characters,
  numbered as `ProductionMessageSample1…5` (Twilio) or positional
  `messageSample{N}` (Telnyx). An array carrying fewer than the
  declared length is a common source of silent rejection.
* **Opt-in evidence** — at least one public URL (`optInImageUrls`)
  showing how the recipient opted in (`VERBAL`, `WEB_FORM`,
  `PAPER_FORM`, `VIA_TEXT`, or `MOBILE_QR_CODE`). A missing or
  non-http(s) URL fails the API-level check first.
* **Business identity** — either `ein` (format `xx-xxxxxxx`) or
  `businessRegistrationNumber` + `businessRegistrationCountry` (holds
  ISO-3166 alpha-2; carriers have required one of the two since
  January 2026 — a tenant can have non-US registration and still submit).
* **Political traffic** — `cvToken` when the use case is `Political` or
  `isPolitical: true`; the token travels to the carrier for the
  round-trip and is not persisted.

Pre-flight the file is validated server-side so a malformed submission
fails the call with a 422 before the carrier sees it.

## 4. RespOrg evolution for toll-free voice

A RespOrg change (SMS/800-administered Responsible Organization) is the
inbound-telephony equivalent of a port-in/port-out for toll-free voice
numbers, and it sits upstream of every SMS consideration on the same
row: until the correct RespOrg owns the number, the TFV lane is the
operation you are preparing, not resolving. Without a RespOrg path an
established toll-free number could not be brought or released — the
service closes the gap the TFV and port-in routes left.

Orbit runs RespOrg as a manual, ops-processed request stored on the
tenant schema: direction (`in`/`out`), the target numbers (up to 50 per
request), the LOA + in-platform signature, ownership of the submission
timestamped, and a Redis-locked write that serializes concurrent
mutations. The service deliberately has no live Somos integration —
request/tracking is the customer-facing surface, exactly like a
manual-mode port-in row, and operations processes the change through
the Somos portal. A RespOrg change is an inbound-routing ownership
operation, not an outbound voice/SMS path — it does not touch the MT
termination lane at all.

When the numbers on the row are toll-free by shape — `+1` on the 800,
833, 844, 855, 866, 877, or 888 prefixes — the REST surface
(`POST /porting/toll-free/resporg`) accepts only that E.164 form and a
LOA URL that resolves to the platform's media-bucket prefix. The
lifecycle beyond "captured" is the same: an Ops team member claims the
request, submits it through Somos, and the row advances to its terminal
state.

## 5. How TFV state plugs into the daily-cap and warming kernels

The warming and daily-cap engines treat TFV state as a hard first gate,
not a bonus multiplier. For a tenant-owned toll-free sender the daily
cap computed by the sender-warming kernel (rule the sender pool) is the
**smaller of**:

* the warming curve for that number (unverified toll-free senders are
  excluded from the high-trust-phase tables and pinned to a conservative
  initial-tier cap), and
* the carrier-grade ceiling that the TFV preflight enforces at send time.

At send time the TFV preflight gate (`sender is toll_free` AND
`recipient is US`) blocks the entire channel when the sender's
`tfv_status` is not `approved` — a preflight DB outage fails closed with
"unable to verify TFV state" instead of fail-OPEN-ing a
guaranteed-throttled send, so the warming ramp is not advanced on work
the carriers will drop. A number that has never been TFV-approved stops
there; approved entries proceed to the daily-cap count check; a
rejected verdict blocks until the form is resubmitted and the carrier
returns a new verdict.

This is also why the sender-identity classifier must label toll-free
correctly at render: misclassifying `+1 888…` as a long code would skip
both the TFV state check and the TFV-idle daily-cap pin, and the warming
kernel would read the number as eligible for throughput it can never
carry.

## Related references

* [Sender identity classification model](/concepts/sender-identity-classification-model) —
  the five-output classification that toll-free resolution sits on, and
  why `toll_free` beats the geographic long-code branch.
* [Sender warming and reputation](/concepts/sender-warming-and-reputation) —
  the two-layer ramp whose daily cap TFV gates.
* [Brand identity trust score](/concepts/brand-identity-trust-score) —
  how TFV state (alongside 10DLC, WhatsApp, RCS, and branded-calling)
  rolls into the cross-channel posture each operations team sees.
* [Send Gates](/compliance/send-gates) — where the TFV preflight lines
  up with quiet-hours, DNC, and RND checks.
* [Sender-ID Registration](/compliance/sender-id-registration) — the
  dashboard surface that renders TFV per-number and drives the submit
  form.