Skip to main content

​
Your first port-in walkthrough

The two operator runbooks — Port a number end-to-end and Port out safely — cover every endpoint and edge case. This page is the shorter checklist for the first time you move a number: it orders the decisions, names the one thing each step protects, and maps the ports that stall onto the rejection reason that caused it. Read this once, then run your port with the runbook pages open. Reads (check, get, timeline) need the numbers:read scope; writes (create, LOA upload/sign/submit, cancel, PIN set) need numbers:write and an owner, admin, or developer role. This page adds nothing to the two runbooks — it is the map between them, not a replacement. Both stay authoritative.

​
1. The state machine you are navigating

Both directions of porting are a one-directional state machine. Knowing which state you are in tells you what actions are still open — most first-port mistakes are an action attempted one state too late.

​
Port-in (number moving onto Orbit)

submitted → reviewing → approved → completed, with rejected and cancelled as the terminal branches, and supplement_submitted as a holding state while the carrier weighs your amendment:
  • submitted — the order exists. Cancellable (DELETE /numbers/porting/:id). The staging: "draft" marker on a create response means the row is stored but NOTHING was dispatched to a carrier — a draft only moves once the LOA is uploaded and signed.
  • reviewing — the losing carrier holds your order plus the signed LOA and is checking the CSR data. Still cancellable. Anything beyond this is not.
  • approved — the losing carrier accepted and (usually) issued an FOC date. Cancel now returns 409; the port will complete.
  • completed — the number is live on your Orbit account, exactly once, with number.ported emitted.
  • rejected — the carrier refused; rejectionReason carries the translated code. Fixable rejections open a 7-day supplement window; submitting one parks the row in supplement_submitted until the carrier accepts it (back to reviewing) or rejects it again.
  • cancelled — terminal branch for both port-in and port-out; nothing further applies.
The LOA has its own three-state machine on top: loaSignatureStatus: draft → signed → submitted, and it only moves forward. A stale-signed or wrong-document LOA is not replaceable after signed — cancel the port and resubmit.

​
Port-out (number moving off Orbit)

Same progression, gated first by the number’s own status: released, suspended, parked, or port_out_pending all reject the submit with 409, so the pre-flight status check is the first thing to run. After the FOC cutover, the winning carrier owns the number — no cancel, no rollback.

​
2. Pre-import checklist — before the first API call

Every rejection class in section 5 traces to something on this list. Run it before submitting, not after:
  1. Customer Service Record (CSR) from the losing carrier — the legal entity name, account number, billing telephone number (BTN), service address, and any transfer PIN, copied verbatim. Do not retype from memory; NAME_MISMATCH and ADDRESS_MISMATCH rejections come almost entirely from guessed CSR fields.
  2. Authorized signer — a named person with title who is authorized to move the number and will sign the LOA. Their name here must match the LOA signature and the losing carrier’s records exactly.
  3. LOA scan — a real PDF at ≥200 dpi, signature dated within 30 days, every porting number listed on it. LOA_INVALID rejections cluster here.
  4. Port-out PIN already set on your Orbit numbers — before you bring new numbers in, protect the ones you already have. POST /numbers/:id/port-out-protection with a 4-32 char PIN means a credential alone can never dispatch a port-out; anything without the matching PIN rejects 401 before the carrier is contacted. Record the PIN in your secret store on the day you set it — there is no recovery path, only rotation.
  5. Country rules known — US/CA numbers get a live synchronous portability check; everywhere else returns check-not-supported and eligibility is manual. Toll-free numbers do not use the LNP flow at all — they move by RespOrg change at POST /numbers/porting/toll-free/resporg.
  6. Eligibility verdict in hand — run POST /numbers/porting/pre-validate and gate on ready: true. That one call runs the portability check AND lints the CSR fields together — the two rejection classes in the same gate.
If any checklist line is unresolved, stop. Gate discipline before the first create is what keeps a first port from becoming a rejected one three weeks in.

​
3. Step-by-step — the wizard order

The dashboard’s Number Porting form walks exactly this order; the API equivalent is in the runbook. The order itself is what matters:
  1. Enter the numbers (one E.164 per line) → run the preflight gate. Eligible, or do not proceed.
  2. Fill the carrier + CSR fields — losing carrier, account number, PIN (US wireless), authorized signer, service address — exact CSR copies.
  3. Checkpoint as a draft — draft: true stores the request locally with staging: "draft" and never touches a carrier. Re-creating with the same number set is idempotent, so a re-visit or refresh never forks the checkpoint.
  4. Upload the LOA in-platform (POST /numbers/porting/:id/loa) — PDF/image under 10MB.
  5. Sign (.../loa/sign) — signer name, email, acknowledgement. Signing twice returns 422; something else is wrong if you reach this twice.
  6. Submit (.../loa/submit) — the only action valid in signed state. This is the moment the losing carrier starts its 7-14 business-day review.
  7. Track the FOC — GET /numbers/porting/:id/timeline expands the flat status into per-stage entries with timestamps, and echoes focDate the moment the carrier assigns one. Watch until status: completed.
  8. At cutover, number.ported fires exactly once — the number enters the normal lifecycle (auto-renew, release, reassignment) the same as a purchased DID. SMS provisioned on a ported number behaves identically to a purchased one.
  9. Never park a draft — a draft never reaches the carrier, never gets an FOC, and never completes. The dashboard flags exactly this state as “draft — LOA pending”. If the signer is unavailable or the CSR is unknown, cancel the draft and re-create it when ready; a checkpoint that ages silently is the single most common way a first port quietly stalls.
If the port is in submitted or reviewing and something about it is wrong, cancel it with DELETE /numbers/porting/:id. After approved, cancel returns 409 — the port will complete on the carrier’s schedule.

​
4. Status webhooks — what to subscribe

Register one webhook endpoint and subscribe to the porting events rather than polling. The events that move a first port: Delivery is at-least-once, so dedupe on the event id in your receiver. The events drive realtime updates; a daily GET /numbers/porting + timeline sweep reconciles anything missed. Full catalog at Webhook Events; signature verification at Webhook Security.

​
5. Common rejections — and the fix for each

GET /numbers/porting/:id/timeline translates carrier rejection codes into a plain-English summary + recommendedAction tagged with a severity: operator_fixable (fix your own data), needs_carrier (the losing carrier must resolve), or fatal (the number cannot port at all). The five that stall first ports: Any rejection with a fatal severity (NUMBER_NOT_PORTABLE) is not worth a supplement — the number has to stay at the losing carrier. Unknown carrier codes surface with the raw carrier text preserved so you can escalate with the exact reason.

​
See Also