> ## 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. # Your first port-in: a do-it-right walkthrough (LOA, PIN, and FOC tracking) > First-time checklist across the whole number lifecycle: pre-import documents and account PIN, the wizard steps from request to signed LOA, FOC date tracking at cutover, the webhooks to subscribe, and the five rejection reasons that stall first ports — with the fix for each. # Your first port-in walkthrough The two operator runbooks — [Port a number end-to-end](/guides/port-numbers) and [Port out safely](/guides/port-out-numbers) — 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: | Event | Fires when | What to do with it | | ---------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | `number.ported` | The port-in completed and the number is live on your account. Emitted exactly once. | Cut routing, send the "you're live" notification, kick off post-port provisioning. | | `porting.request.loa_signed` | The in-platform LOA signature was captured. | Advance the internal checklist; queue the LOA submit step. | | `porting.request.supplement_submitted` | You submitted a carrier-requested supplement. | Reset the amend-window countdown; alert the operator who owns the file. | | `porting.request.manual_review_required` | The port fell back to manual review. | Flag for human follow-up; do not auto-retry. | | `porting.request.cancelled` | You or an admin cancelled the request. | Remove from the active board; record the reason. | | `number.port_out.requested` | A port-out was submitted and accepted by the carrier. | Start the cancel-window countdown — after FOC cutover, cancel no longer applies. | | `number.port_out.cancelled` | A port-out request was cancelled before cutover. | Remove the number from your "leaving" board. | 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](/webhooks/events); signature verification at [Webhook Security](/webhooks/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: | Rejection | Why it happens | Fix | | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NAME_MISMATCH` | The legal entity name on the request differs from the CSR — often because of a guessed or abbreviated form ("Acme, Inc." vs "ACME INC"). | Pull the CSR, submit a supplement within the 7-day amend window with the name copied verbatim. | | `ADDRESS_MISMATCH` | The service address differs — suite numbers, ZIP+4 vs ZIP, abbreviations. | Supplement with the exact CSR address, quoted unmodified from the carrier. | | `BTN_MISMATCH` | For multi-line accounts, the billing telephone number sent does not match the losing carrier's billing record. | Get the BTN from the CSR (it is a distinct field from your account number) and supplement. | | PIN rejection (`401 PIN_MISMATCH` on port-out; carrier PIN reject on port-in) | The transfer PIN from the losing carrier was absent or wrong. | Confirm the PIN with the carrier — the port cannot proceed without it. Prevent entirely by setting the account and PIN into the pre-import checklist before submitting. | | `LOA_INVALID` | The LOA is missing numbers, unsigned, a photo of a screen, signed more than 30 days ago, or a scan below legibility. | Redo the LOA as a real PDF at ≥200 dpi, complete number list, signature dated within 30 days; cancel the port and resubmit with the corrected document. | 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 * [Port a number end-to-end](/guides/port-numbers) — the runbook this page maps; every endpoint worked through in order. * [Port out safely](/guides/port-out-numbers) — the symmetric runbook for moving numbers off Orbit, including PIN protection and cancel-window discipline. * [Number Porting endpoint sequence](/numbers/porting) — the shorter per-endpoint reference. * [Number Lifecycle](/numbers/lifecycle) — what applies to the number after the port completes. * [Webhook Events](/webhooks/events) — the complete event catalog.