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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

Moving your inbound number estate onto Orbit

The questions above assume a port is already in flight. This section is for the earlier decision: you run inbound numbers at a UCaaS/CCaaS provider or on your own PBX, and you want the whole estate answering on Orbit. It covers what changes for callers, how the SIP-trunk half joins the port half, what checklist to run while seats are still live, and which walkthrough owns which stage.

Where does my number live during and after the move?

The answer is the same at every stage: the number terminates on the Orbit platform either way. The ports and trunks below only decide when the carrier route catches up with that fact:

Day 0 — SIP trunk first, numbers still at the incumbent. Register your existing PBX or carrier-facing SBC as an Orbit SIP trunk (Registering your PBX on Orbit). Your numbers still live at the losing carrier; Orbit answers the calls the trunk delivers and returns them over the same trunk. No port has started and callers notice nothing.
Mid-port — same termination, changing resolution. The moment you submit a port, inbound starts being answered from Orbit’s side for anything already routed in, while the losing carrier still owns the DIDs until FOC. The ENUM-style resolution decision per call — which trunk, SIP credential, or flow answers this DID — is the same lookup the inbound portability walkthrough builds on; porting changes who owns the number, not how a call is answered.
After the FOC cutover — carrier record matches reality. The losing carrier releases the DID and the carrier layer points where the calls already went. number.ported fires exactly once; the numbers render as inventory rows on your account.

Two carve-outs where “on the platform either way” stays true but the mechanics are tenant-owned: toll-free US numbers never enter the LNP flow — they move by a RespOrg change you submit at POST /numbers/porting/toll-free/resporg (details) — and port-out protection is yours to set: POST /numbers/:id/port-out-protection pins a 4-32 character PIN on every Orbit-held number so no unauthorized request can dispatch off them (setup).

How do the SIP trunk and the port fit together?

Run them as two lanes that converge at cutover:

Trunk lane first. Create the outgoing trunk to your PBX (host, port, udp/tcp/tls, digest credentials) and verify it — the pre-save probe, then GET /api/v1/voice/sip-trunks/health reading active. Registering your PBX on Orbit walks this end to end.
Resolution while you wait. With the trunk healthy, inbound calls to your still-incumbent DIDs that your PBX forwards arrive on Orbit and resolve per DID — the ENUM-style lookup over trunk → SIP credential → flow destination that the inbound portability walkthrough details. Rebuild the IVR/queues here, on real low-stakes traffic, before anything ports.
Port lane in waves. Submit the estate in batches (batch walkthrough); ported DIDs cut their carrier route to the termination you already validated.
Cutover check per wave. number.ported fires once per DID; the CCaaS ladder’s rollback probes (GET /api/v1/voice/calls?to=…&direction=inbound) confirm calls land before the next batch’s LOA goes out.

The inverse mistake is porting first and trunking after: then the FOC date arrives with nothing verified to terminate on.

What do I do about seats that are still live on the old CCaaS?

Port the numbers, not the seats — an active Genesys/Talkdesk/Five9/NICE CXone seat keeps working on the incumbent until its number’s FOC date; nothing about the port touches the seat licence. The operator checklist mirrors the enterprise CCaaS migration runbook:

Audit the estate: every inbound DID, its queue/IVR destination, its per-country registrations and emergency address — the CCaaS guide’s Step 1 artifact list.
Stand up the SIP trunk lane so unported numbers can already terminate on Orbit (same lane as the previous answer).
Rebuild queues and IVR on trunked numbers; validate on a low-stakes shadow queue.
Batch the LOA list per wave — never two customer-facing queues in the same window — with a rollback check per wave.
Hold per-number gates: registration export, emergency address record, and caller-ID display value captured before each LOA submits.
Cancel the incumbent only after the last ported number validates; until then unported numbers still answer there, which is your rollback.

The full ladder — audit schema, per-wave rollback, the port-LOA batch loop — is Migrate from enterprise CCaaS.

When does the FAQ stop and a walkthrough begin?

Use the route table — stay here only for the routing question itself:

Your situation	Open the walkthrough
First port ever, or the cause of a rejection code	First-port walkthrough
A second DID onward, single-port shape, the full endpoint surface	Port a number end-to-end
An estate of 50–1000 DIDs in CSV waves	Batch walkthrough
Inbound estate behind your own PBX/SBC (trunk-first move)	Registering your PBX on Orbit, then Inbound call portability
Live CCaaS seats mid-migration	Migrate from enterprise CCaaS
Leaving Orbit (port-outs, PIN protection)	Port out safely

What goes into the carrier LOA packet?

Supplements get rejected for the packet, not the signature — assemble all six artifacts per batch before anything submits:

LOA document — real PDF at ≥200 dpi, signature dated within 30 days, every porting number listed on it.
CSR pull from the losing carrier — legal entity name, account number, BTN, service address, any transfer PIN, all verbatim.
Authorized signer — named person with title, matching the LOA signature and the carrier’s records.
Per-number registrations — per-country identity/business registrations that travel with each DID.
Emergency address record — exported and ready to re-attach on the Orbit side.
SMS-on-LOA flags — for splittable: true preflight results, SMS is called out on the LOA or it stays behind while voice ports.

If it went into the request body, it goes in the packet: the batch walkthrough carries the full per-batch sequence.

What does the CSR request body actually look like?

One row from a batch, per column — this exact shape passes pre-validate when the values are CSR-verbatim:

{
  "numbers": ["+14155552671"],
  "currentCarrier": "Legacy Carrier Inc.",
  "country": "US",
  "accountNumber": "ACCT-1182",
  "accountPin": "0142",
  "authorizedSigner": "J. Operator",
  "serviceAddress": {
    "line1": "410 Pine St, Suite 300",
    "city": "Seattle",
    "state": "WA",
    "postalCode": "98101-2317",
    "countryCode": "US"
  },
  "contactEmail": "porting-ops@example.com"
}

The fields that reject are the unquoted ones: Suite 300 dropped, 98101 where the CSR says 98101-2317, Legacy Carrier where the CSR says Legacy Carrier Inc. — run POST /numbers/porting/pre-validate and gate on ready: true before this ever submits.

What does a first-port timeline actually look like?

A single US DID, no rejections, worked from the first-port walkthrough:

Day 0 — CSR in hand; pre-validate returns ready: true; create with the signed LOA attached (or checkpoint draft: true and run upload → sign → submit the same day).
Days 1–2 — submitted; the losing carrier holds the order. Cancel still works (DELETE /numbers/porting/:id).
Days 3–10 — reviewing; carrier checks the CSR data. Still cancellable. A fixable rejection here opens the 7-day supplement window.
Days 10–14 — approved with focDate set; cancel now returns 409. The cutover is scheduled.
FOC day — completed; number.ported fires exactly once; the number enters the normal inventory lifecycle.

Weekends and carrier reply latency move each band, not the order — the timeline endpoint (GET /numbers/porting/:id/timeline) reports the actual per-stage timestamps as they land.

Migrating from another provider

The porting questions above are one slice of a provider switch — the numbers move. This section answers the recurring switch question: whether to run the import wizard (or its CLI) or do a manual, code-level migration, per source provider. It routes; it does not re-tell the walkthroughs.

Migrating from Twilio? Run the import wizard at Settings → Import → Twilio to pull your numbers, messaging services, templates, and contacts, or script the same run with devotel migrate twilio. Use the manual walkthrough — Migrate from Twilio — only when you re-map TwiML, webhooks, and Verify by hand. The wizard section of that guide covers both entry points.
Migrating from Sinch? The wizard at Settings → Import covers configuration-only imports; the manual walkthrough — Migrate from Sinch — is the fullest concept mapping (service-plan tokens, batch sends, Conversation API). Same wizard-vs-CLI pointers live in that guide.
Migrating from MessageBird? Use the assisted wizard, which has a MessageBird (Bird) connector for channels, contacts, and flows: Assisted import wizard. The manual concept mapping (Flow Builder, WhatsApp channels, MNM) is Migrate from MessageBird.
Migrating from Vonage? There is no wizard connector for Vonage, so the manual walkthrough is the whole path: Migrate from Vonage (Applications, JWT auth, NCCO).
Migrating from Infobip? Same — no wizard connector; follow the manual walkthrough: Migrate from Infobip (base-URL auth, Moments flows, Answers bots).
Migrating from Telnyx? Use the assisted wizard’s Telnyx connector (numbers, messaging profiles, 10DLC registrations, contacts): Assisted import wizard. A manual code-level path would rebuild the same configuration by hand — pick the wizard here.
Migrating from Klaviyo? Use the assisted wizard’s Klaviyo connector (lists, segments, templates, flows, profiles): Assisted import wizard. There is no manual code-level Klaviyo walkthrough — the wizard is the supported path.

Still deciding? The migration playbook hub maps every covered source to its guide and the vendor-agnostic eight-step sequence; Run a platform migration end-to-end covers the wizard’s operations side (jobs, rollback, the fifth source: Front).

Does the wizard import my live traffic?

No. The wizard and the devotel migrate CLI authenticate read-only against the source account and copy configuration — numbers, messaging services, templates, contacts — never in-flight sends or inbound routes. Your existing integration keeps serving live traffic until you cut over on your own schedule.

When do I cut over?

Only when your integration targets Orbit’s responses — your send path, webhook verification (X-Orbit-Signature), and OTP calls handle Orbit’s payloads, and the parallel-run shows delivery-rate parity. Then freeze legacy sends, swap the API key, and hold the legacy credential warm through the seven-step cutover runbook in the migration playbook hub.

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.

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

Where do I go after the FAQ?

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

​FAQ: porting and numbers

​Rejection classes

​What does NAME_MISMATCH mean?

​What does ADDRESS_MISMATCH mean?

​What does BTN_MISMATCH mean?

​What does a PIN rejection mean?

​What does LOA_INVALID mean?

​Before you submit

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

​How do I gate a port before submitting?

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

​Why should I not park a port in draft?

​During the port

​When can I still cancel a port?

​How do I track the FOC date?

​Which webhooks should I subscribe to for porting?

​What happens when a rejection is operator_fixable vs needs_carrier vs fatal?

​How does the 7-day supplement window work?

​Protecting your numbers

​How do I stop an unauthorized port-out?

​What statuses block a port-out?

​When does a port-out become irreversible?

​Moving your inbound number estate onto Orbit

​Where does my number live during and after the move?

​How do the SIP trunk and the port fit together?

​What do I do about seats that are still live on the old CCaaS?

​When does the FAQ stop and a walkthrough begin?

​What goes into the carrier LOA packet?

​What does the CSR request body actually look like?

​What does a first-port timeline actually look like?

​Migrating from another provider

​Does the wizard import my live traffic?

​When do I cut over?

​Special cases

​How do toll-free numbers move?

​Can I practice porting flows in the sandbox?

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

​Where do I go after the FAQ?