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

# FAQ: porting and numbers

> The twenty questions the support desk answers most often about porting numbers in and out of Orbit — each short answer links into the authoritative runbook rather than restating it.

# FAQ: porting and numbers

Support-grade answers to the questions that come up on every port. Each answer is two or three sentences and links into the authoritative guide — read the linked section before re-typing the advice into a ticket.

## Rejection classes

### What does `NAME_MISMATCH` mean?

The legal entity name you sent does not match the losing carrier's Customer Service Record (CSR) — usually a guessed or abbreviated form. Pull the CSR and submit a supplement with the name copied verbatim. Mitigation walk: [first-port walkthrough §5](/guides/number-porting-walkthrough-first-port#5-common-rejections-and-the-fix-for-each).

### What does `ADDRESS_MISMATCH` mean?

The service address differs from the CSR — suite numbers, ZIP+4 vs ZIP, abbreviations. Supplement with the exact CSR address, quoted unmodified. Mitigation walk: [first-port walkthrough §5](/guides/number-porting-walkthrough-first-port#5-common-rejections-and-the-fix-for-each).

### What does `BTN_MISMATCH` mean?

On multi-line accounts, the billing telephone number (BTN) sent does not match the losing carrier's billing record — it is a distinct field from the account number. Get the BTN from the CSR and supplement. Mitigation walk: [first-port walkthrough §5](/guides/number-porting-walkthrough-first-port#5-common-rejections-and-the-fix-for-each).

### What does a PIN rejection mean?

The transfer PIN from the losing carrier was missing or wrong — on port-in the carrier rejects it; on port-out you get `401 PORT_OUT_PIN_MISMATCH`. Confirm the PIN with the carrier before resubmitting. Mitigation walk: [first-port walkthrough §5](/guides/number-porting-walkthrough-first-port#5-common-rejections-and-the-fix-for-each).

### What does `LOA_INVALID` mean?

The Letter of Authorization is missing numbers, unsigned, a photo of a screen, over 30 days old, or below legibility. Redo it as a real PDF at >=200 dpi with every porting number listed, then cancel and resubmit. Mitigation walk: [first-port walkthrough §5](/guides/number-porting-walkthrough-first-port#5-common-rejections-and-the-fix-for-each).

## Before you submit

### Where does the pre-import CSR checklist come from?

Run the six-item pre-import checklist before any API call: CSR in hand, authorized signer named, LOA scan ready, port-out PIN set on existing numbers, country rules confirmed, and the eligibility gate passed. Source: [first-port walkthrough §2](/guides/number-porting-walkthrough-first-port#2-pre-import-checklist-before-the-first-api-call).

### How do I gate a port before submitting?

Call `POST /numbers/porting/pre-validate` and gate on `ready: true` — it runs the portability check and lints the CSR fields in the same pass. The full gate sequence (including bulk preflight) is in [Port a number end-to-end §2](/guides/port-numbers#2-preflight-gate-before-you-submit).

### What is the difference between a draft and a submitted port?

A draft (`draft: true` at create) is stored locally with `staging: "draft"` and never reaches a carrier; a submitted port is dispatched immediately. A draft only moves once the LOA is uploaded and signed. Walkthrough: [Port a number end-to-end §3](/guides/port-numbers#3-submit-the-port).

### Why should I not park a port in draft?

No carrier ever sees a draft, so no FOC date is ever issued for it and the review clock never starts. Cancel the draft and re-create it when the CSR and signer are ready. Details: [Port a number end-to-end §3](/guides/port-numbers#3-submit-the-port).

## During the port

### When can I still cancel a port?

Cancel works while the request is `submitted` or `reviewing`; once the losing carrier approves it, cancel returns `409` and the port completes on the carrier's schedule. Port-out cancellation is honored only until the FOC cutover. Cancel boundaries: [first-port walkthrough §1](/guides/number-porting-walkthrough-first-port#1-the-state-machine-you-are-navigating).

### How do I track the FOC date?

Call `GET /numbers/porting/:id/timeline` — it expands the flat status into per-stage entries and echoes `focDate` as soon as the carrier assigns one. The dashboard's porting wizard renders the same timeline. Tracking walkthrough: [Port a number end-to-end §6](/guides/port-numbers#6-track-timeline-stages-and-foc).

### Which webhooks should I subscribe to for porting?

Subscribe to `number.ported`, `porting.request.loa_signed`, `porting.request.supplement_submitted`, `porting.request.manual_review_required`, and `porting.request.cancelled`. Delivery is at-least-once, so dedupe on the event `id`. Event table: [first-port walkthrough §4](/guides/number-porting-walkthrough-first-port#4-status-webhooks-what-to-subscribe).

### What happens when a rejection is `operator_fixable` vs `needs_carrier` vs `fatal`?

`operator_fixable` means fix your own data and supplement inside the 7-day amend window; `needs_carrier` means the losing carrier must resolve it; `fatal` (for example `NUMBER_NOT_PORTABLE`) means the number stays at the losing carrier. Severity model: [Port a number end-to-end §6](/guides/port-numbers#6-track-timeline-stages-and-foc).

### How does the 7-day supplement window work?

After a fixable rejection, you have 7 days to submit a supplement before the FOC clock restarts. The row sits in `supplement_submitted` until the carrier accepts it back into `reviewing` or rejects again. Walkthrough: [Port a number end-to-end §5](/guides/port-numbers#5-supplier-response-loop-supplements-and-refresh).

## Protecting your numbers

### How do I stop an unauthorized port-out?

Set a port-out PIN (4-32 chars) with `POST /numbers/:id/port-out-protection` — any port-out attempt without the matching PIN rejects `401` before the carrier is contacted. There is no recovery path, so record the PIN in your secret store when you set it. Setup walkthrough: [Port out safely §2](/guides/port-out-numbers#2-pre-flight-portable-status-then-pin-protection).

### What statuses block a port-out?

`released`, `suspended`, `parked`, and `port_out_pending` all reject the submit with `409`, so check `GET /numbers/:id` first. Full pre-flight order: [Port out safely §2](/guides/port-out-numbers#2-pre-flight-portable-status-then-pin-protection).

### When does a port-out become irreversible?

After the FOC cutover, the winning carrier owns the number — cancel no longer applies and there is no rollback. Treat the cancel window as real: a delayed decision past FOC expiry means the number is gone. Cancel discipline: [Port out safely §1](/guides/port-out-numbers#1-treat-port-outs-as-gated-work).

## Special cases

### How do toll-free numbers move?

Toll-free numbers do not use the standard carrier-to-carrier port flow — they move by changing the Responsible Organization (RespOrg) via `POST /numbers/porting/toll-free/resporg`. Submitted outside the LNP flow; post-port administration runs the same way. Carve-out details: [Port a number end-to-end §1](/guides/port-numbers#1-prep-the-data).

### Can I practice porting flows in the sandbox?

Yes — the sandbox's reserved magic numbers (from the `+1 555 01XX` range) let you run the full port and DLR exercise loop without touching a real carrier. Provisioning shapes: [Sandbox test mode](/guides/sandbox-test-mode#buy-test-numbers-without-touching-a-carrier) and [Sandbox magic numbers playbook](/guides/sandbox-magic-numbers-playbook).

### How do I migrate more than a handful of numbers at once?

Use the bulk CSV flow at `POST /numbers/port-in/bulk-csv` — up to 1000 rows per upload, each row becoming its own porting request you finish through the dashboard. CSV shape and caps: [Port a number end-to-end §8](/guides/port-numbers#8-bulk-csv-migration-50-1000-dids-at-once).

### Where do I go after the FAQ?

For everything beyond a short answer, work from the two runbooks — [Port a number end-to-end](/guides/port-numbers) and [Port out safely](/guides/port-out-numbers) — with the [first-port walkthrough](/guides/number-porting-walkthrough-first-port) as the checklist map between them. The [batch walkthrough](/guides/port-numbers-batch-walkthrough) covers CSV estates; the [endpoint sequence](/numbers/porting) is the shorter per-endpoint reference.