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

# Troubleshooting: US toll-free sender blocked with TFV_REQUIRED

> A US-bound SMS or MMS from your toll-free number returns 422 TFV_REQUIRED and the message never queues. Confirm the number's verification status, submit Toll-Free Verification, and handle a pending or rejected review.

# Troubleshooting: US toll-free sender blocked with TFV\_REQUIRED

US carriers (Verizon, AT\&T, T-Mobile) treat A2P SMS and MMS from
**unverified toll-free numbers** as guaranteed-throttle traffic — they
filter it, cap it to a trickle, or drop it entirely. To keep that send
from burning credits on a guaranteed-no-deliver request, Orbit's send
preflight rejects the request synchronously with
`422 TFV_REQUIRED` until your sender's `tfv_status` reads `approved`.
The message is never queued and never handed to a carrier.

<Note>
  The gate refuses the send **before** it is queued, so a retry loop only
  re-trips the 422. The move is a one-time verification filing, not a
  retry schedule.
</Note>

## Match the status to its meaning

| `tfv_status`    | What fired                                                               | Fix class                                                                                 |
| --------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `not_submitted` | No Toll-Free Verification filing has ever been submitted for this number | Submit the TFV form — see [Submit Toll-Free Verification](#submit-toll-free-verification) |
| `pending`       | A filing is in carrier review and has not cleared yet                    | Wait for the carrier — see [Wait for the review](#wait-for-the-review)                    |
| `rejected`      | The carrier declined the previous filing                                 | Amend and re-submit — see [Recover from rejected](#recover-from-rejected)                 |

The error body names the status so you do not have to guess which lane
you are in:

```json theme={null}
{
  "error": {
    "code": "TFV_REQUIRED",
    "status": 422,
    "message": "Sender +1888... is a US toll-free number that has not completed Toll-Free Verification. Submit a Toll-Free Verification form on /settings/compliance before sending US A2P SMS from this number.",
    "details": { "from": "+1888", "to": "+1202", "tfv_status": "not_submitted" }
  }
}
```

The `message` text changes per status: `pending` says the review is in
flight (expect 1–3 business days), and `rejected` asks you to amend the
use-case and sample messages and re-submit.

## Reproduce the block

Send an SMS or MMS where `from` is a toll-free number on your account
and `to` is a US recipient:

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/messages/sms \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+12025550142",
    "from": "+18885550100",
    "body": "Your receipt is ready."
  }'
```

While that number's verification is unfinished, the response is a 422
with the shape above.

## Confirm the number's status

Two read-backs tell you where the number stands.

1. **The account-level trust hub.** Call
   `GET /api/v1/brand-identity/status` and find the `messaging_toll_free`
   entry — a gated number shows that channel at `action_required` with a
   `detail` like "1 of 3 numbers verified", and it raises the
   `nextActions` priority list accordingly:

   ```bash theme={null}
   curl https://api.orbit.devotel.io/api/v1/brand-identity/status \
     -H "X-API-Key: dv_live_sk_..."
   ```

2. **The number itself.** Open **Settings → Numbers** in the dashboard
   and read the number's Toll-Free Verification status, or query the
   number list over the API — every toll-free row carries a `tfv_status`
   field (`not_submitted` when no filing exists).

A `detail` on the brand-identity hub that counts verified toll-free
numbers is the fastest sweep: it tells you whether the gate will fire
for every toll-free sender on the account, not just the one that
tripped.

## Submit Toll-Free Verification

Verification is a carrier-side filing Orbit submits on your behalf —
the information comes from you, the queue belongs to the carrier.

1. Open **Settings → Compliance** in the dashboard and start the
   **Toll-Free Verification** form for the gated number.
2. Fill in the business details (name, website, contact email and
   phone) plus the fields carriers screen the filing on:
   * a **use case** label (the category list mirrors the carriers'
     fixed enum — `2FA`, `Marketing`, `Customer Care`, and so on);
   * a **use-case summary** describing the traffic you actually send;
   * **one to five sample messages** copied from your live templates.
3. Submit. The number's `tfv_status` moves to `pending` immediately,
   and the carrier review typically clears in **1–3 business days**.
4. Send again once the status flips to `approved` — the gate drops
   that entry from its block list without any change on your
   integration.

<Note>
  Carriers review the filing against what you declare, so an accurate
  use case and real sample messages clear faster than a generic one.
  Lead times are expectations, not guarantees.
</Note>

## Wait for the review

While `tfv_status` is `pending`, the carrier decides — not Orbit. Do
not retry the blocked sends in a loop: they return the same 422 and
burn rate-limit budget without changing the outcome. Poll the status
with the read-backs above and queue or hold the traffic until the
filing clears.

If a `pending` status sits well past a week, that is escalation
territory — see [Escalation](#escalation).

## Recover from rejected

A `rejected` status is terminal like `pending` is not: only a new
filing moves the number back into review.

1. Read the rejection note on the number's compliance card —
   **Settings → Numbers** → the number → Toll-Free Verification — or in
   the `messaging_toll_free` channel's `reason` on the brand-identity
   hub.
2. Amend what the carrier named. In practice the decline lands on the
   **use case** (does not match the traffic) or the **sample messages**
   (do not demonstrate the declared use). Resubmitting an unchanged
   form earns a faster second rejection.
3. Re-submit the amended form through the same **Settings →
   Compliance** path. The status re-enters review at `pending` with a
   fresh 1–3 business-day expectation.

## Scope of the gate

The preflight is deliberately narrow. It fires only when all of these
hold at once:

* the sender is a **toll-free number owned on your account** (platform
  pool senders and shared defaults bypass it);
* the channel is **SMS or MMS** — voice, email, WhatsApp, RCS, and the
  other channels never consult TFV;
* the recipient resolves to **US** (by the account's country hint, or
  the `+1` NANP prefix when no hint is sent).

Everything else is unaffected: non-US destinations, non-toll-free
senders, and every channel other than SMS/MMS send exactly as before.

## Escalation

Escalate to support when the fix above cannot land — a `pending` filing
that has sat for over a week, or a `rejected` verdict whose reason you
cannot resolve with the documents you hold. Include:

1. The **toll-free number** (E.164) and the **destination country**.
2. The current **tfv\_status** — copied from **Settings → Numbers** or
   the `messaging_toll_free` entry on `GET /api/v1/brand-identity/status`.
3. The **message ID or request ID** from a rejected send (`error.code`
   plus `meta.request_id`), and the timestamp with timezone.

## Related references

* [Sender-ID Registration](/compliance/sender-id-registration) — the
  broader registration lifecycle for alphanumeric senders and the
  `pending → approved / rejected` statuses.
* [Brand Identity API](/api-reference/endpoints/brand-identity) — the
  consolidated trust-posture read used above, with the toll-free
  channel key and the next-actions list.
* [Error Codes](/reference/error-codes) — the full table where
  `TFV_REQUIRED` is catalogued alongside the other 422 gates.
* [FAQ](/reference/faq) — the shorter one-paragraph summary of this
  same gate.