Port a number end-to-end

Porting is the highest-stakes move a customer makes on Orbit: get the CSR data wrong and the losing carrier rejects weeks in, and you restart the clock. This guide walks one complete port — for a single DID or a 50-1000-DID estate — from the first portability check through the LOA signature, the FOC timeline, webhook-driven ops, and post-port lifecycle. Build it once and every migration looks the same. Reads (list, get, timeline, check, pre-validate) need the numbers:read scope; writes (create, LOA upload/sign/submit, supplement, cancel) need numbers:write and an owner, admin, or developer role. The API reference is at Numbers; the shorter endpoint sequence page is at Number Porting.

1. Prep the data

Before any API call, pull a Customer Service Record (CSR) from the losing carrier — a bill or the carrier’s own LNP record that shows the exact legal entity name, account number, billing telephone number (BTN for multi-line), service address, and any transfer PIN. Rejection codes like ADDRESS_MISMATCH and NAME_MISMATCH almost always trace back to a guessed, not copied, CSR field. Build the E.164 list of numbers to move, and note these country rules up front:

US / CA numbers route to a live synchronous portability check (Telnyx). Everywhere else routes to DIDWW, which has no synchronous check — the verdict comes back as check-not-supported and you verify eligibility manually.
Toll-free numbers do not port carrier-to-carrier. They move by changing the Responsible Organization (RespOrg) via Somos; submit that at POST /numbers/porting/toll-free/resporg instead of the LNP flow.
If the number is SMS-enabled on the losing carrier, call that out on the LOA — the response splittable: true tells you the carrier may port voice but leave SMS behind.

2. Preflight — gate before you submit

Run preflight on every number. It is read-only, creates no order, and catches the rejections that would otherwise cost you the 2-7 business-day submission window.

# Single number — one live carrier call
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+14155551234", "currentCarrier": "Acme Telecom" }'

{
  "data": {
    "eligible": true,
    "reasons": [],
    "splittable": false,
    "check_status": "checked",
    "provider": "telnyx"
  }
}

Read the verdict as:

eligible: false — do not submit; reasons names the blockers (e.g. rate-center exclusion). fatal rejections must stay at the losing carrier.
check_status: "check-not-supported" — DIDWW territory; verify eligibility manually before submitting.
check_status: "check-skipped" — the carrier call failed and Orbit passed optimistically; never gate on this. Re-run or verify manually.
splittable: true — call SMS out on the LOA explicitly.

For a full estate, batch it (up to 1000 distinct numbers per call, chunked upstream per provider):

# Bulk check — one call per CSV, not one call per DID
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/check/bulk \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumbers": ["+14155551234", "+14155555678"], "currentCarrier": "Acme Telecom" }'

The combined gate — pre-validate — runs the same portability check and statically lints the CSR fields you will send, catching the omission/mismatch class of rejections (ADM/address, name, BTN) before the order exists:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/pre-validate \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe",
    "serviceAddress": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    }
  }'

{
  "data": {
    "ready": true,
    "portability": {
      "results": [
        {
          "phoneNumber": "+14155551234",
          "eligible": true,
          "reasons": [],
          "splittable": false,
          "check_status": "checked",
          "provider": "telnyx",
          "country": "US"
        }
      ],
      "summary": { "total": 1, "eligible": 1, "ineligible": 0 }
    },
    "csr": {
      "ready": true,
      "issues": []
    }
  }
}

Gate on ready: true — every number portable AND no blocker-severity CSR issue. check is rate-limited to 20 req/min, check/bulk and pre-validate to 5 req/min per auth context.

3. Submit the port

Once ready, submit. numbers accepts a single E.164 string or an array for a multi-line port under one account. There are three ways a create can leave your system, and the choice matters for how the request is tracked afterwards:

Full dispatch (default) — send country and no draft flag. Orbit opens the carrier order immediately (Telnyx for US/CA, DIDWW elsewhere) and the row returns with a provider set. This is the single-shot path the curl below takes.
Wizard checkpoint — draft: true — store the request locally and deliberately skip carrier dispatch. The row is stamped staging: "draft"; nothing reaches the losing carrier until the LOA is uploaded and signed on the returned row. This is the semantic the tenant-facing port-in wizard’s first step uses, and any flow you build that needs to checkpoint numbers and CSR details before a signed LOA exists.
Ops handover — omit country — also stores the request with no carrier dispatch, but it means “ops hand-processes this port”: no provider is ever selected, refresh has nothing to poll (it returns 422), and the request stays in manual mode for its whole life. Use it when a human on your side (or ours) drives the port out-of-band.

Draft and ops-handover both skip dispatch at create time, but they are not interchangeable: a draft is a wizard checkpoint waiting on its own LOA and is meant to be resumed (below); an omitted-country row is a permanent manual-mode request with no resume semantics. Picking the wrong one either strands a wizard mid-flow or sends ops a request that was never meant for hand-processing.

# Single-shot — Orbit dispatches to the carrier immediately
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "country": "US",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe",
    "serviceAddress": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    }
  }'

{
  "data": {
    "id": "port_abc123",
    "numbers": ["+14155551234"],
    "status": "submitted",
    "loaSignatureStatus": "draft",
    "provider": "telnyx",
    "focDate": null,
    "rejectionReason": null
  }
}

Wizard draft intake

The hosted port-in wizard — the Single DID form on the dashboard’s Number Porting page — checkpoints the request before an LOA exists. Building the same flow yourself is one flag:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": ["+14155551234"],
    "currentCarrier": "Acme Telecom",
    "country": "US",
    "accountNumber": "998877",
    "authorizedSigner": "Jane Doe",
    "serviceAddress": {
      "line1": "1 Market St",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "countryCode": "US"
    },
    "draft": true
  }'

{
  "data": {
    "id": "port_draft456",
    "numbers": ["+14155551234"],
    "status": "submitted",
    "staging": "draft",
    "provider": null,
    "focDate": null
  }
}

The walk-through the wizard drives (and the order your own flow should follow):

Enter the numbers — one E.164 per line; the wizard’s single-DID form validates each line on entry. Run the preflight gate first; the dashboard offers the same eligibility check inline and blocks submission on a negative verdict.
Check the carrier — pick the losing carrier and fill the CSR fields (account number, PIN for US wireless, authorized signer, service address). These must match the losing carrier’s records exactly or the port rejects days later.
Save the draft — POST /numbers/porting with draft: true. The row is stored locally, staging: "draft", no carrier call. Re-creating with the same number set is idempotent: instead of a second row you get the original draft back, so a wizard step-forward or a page refresh never forks the checkpoint.
Upload the LOA in-platform — POST /numbers/porting/port_draft456/loa with the PDF/image (see LOA lifecycle).
Sign — POST /numbers/porting/port_draft456/loa/sign with the signer name, email, and acknowledgement.
Submit — POST /numbers/porting/port_draft456/loa/submit forwards the signed LOA. From here the timeline drives to FOC the same as a single-shot port.
A draft has no carrier-side state — the background status poller skips it and GET /porting/:id/refresh refuses it (422, nothing tracked at any carrier yet), so a draft can never be accidentally dispatched by polling. It only moves when you upload and sign the LOA.

Resume and submit from a draft

A draft never dispatches on its own. Turning it into a live port is the LOA lifecycle on the returned id — there is no separate “submit the draft” endpoint, and nothing to re-POST on the create route:

POST /numbers/porting/:id/loa — attach the document; loaSignatureStatus becomes draft.
POST /numbers/porting/:id/loa/sign — record the signer acknowledgement; status becomes signed. Submitting before this step, or signing twice, returns 422.
POST /numbers/porting/:id/loa/submit — the only signed-state endpoint; anything else returns 422. The signed LOA attaches to the carrier order when one already exists (the normal case for port ranges that were dispatched separately).

Validate the LOA upgrade path the same way you would a fresh create — re-run pre-validate before step 1 if the CSR data was gathered more than a few days ago, because a draft that sat through a billing-cycle change can arrive with stale account details. Do not park a request in draft. No FOC date is ever issued for an undispatched row: the losing carrier only starts its 7–14 business-day review once it holds an order plus a signed LOA, and a draft has neither. A wizard that stops after step 3 produces a checkpoint that ages silently while every stakeholder assumes the port is in flight — the dashboard wizard flags exactly this state as “draft — LOA pending”. If the request is genuinely blocked (signer unavailable, CSR unknown), cancel the draft and re-create it when ready rather than letting it sit.

4. LOA lifecycle — upload, sign, submit

The Letter of Authorization proves you are authorized to move the number. Orbit exposes a dedicated three-step lifecycle rather than accepting a bare file URL, and each step transitions loaSignatureStatus:

# 1. Upload the LOA artefact (PDF / JPEG / PNG / HEIC, up to 10MB)
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/loa \
  -H "X-API-Key: dv_live_sk_..." \
  -F "file=@loa.pdf"
# status -> draft

# 2. Record the in-platform signature acknowledgement
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/loa/sign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signerName": "Jane Doe",
    "signerEmail": "jane@acme.com",
    "acknowledgement": "I am authorized to request this number be ported to Orbit and the information above is accurate."
  }'
# status -> signed

# 3. Forward the signed LOA to the losing carrier
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/loa/submit \
  -H "X-API-Key: dv_live_sk_..."
# status -> submitted

The state machine is one-directional and the irreversibility is deliberate: once the LOA is signed or submitted, re-uploading a replacement is refused (cancel the port and resubmit if the wrong document went out). Signing twice returns 422, not a silent merge. Make the LOA a real PDF at ≥200 dpi with the signature dated within 30 days, every number in the port range listed, and the authorized-signer name + title legible — LOA_INVALID rejections cluster here. The acknowledgment text and signer details are your organization’s own authorization record; Orbit conveys it to the carrier and stores it for your audit trail — it does not certify authorization on your behalf.

5. Supplier response loop — supplements and refresh

If the losing carrier kicks back a supplement request (a minor data correction — an address line, a suite number), respond within the 7-day amend window so the FOC clock does not restart:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/supplement \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "serviceAddress": { "line2": "Suite 200", "countryCode": "US" } }'

Supply at least one of an updated LOA URL, CSR URL, billing name/address, account number, PIN, or narrative. The supplement endpoint returns 422 when the request is not in a rejected or supplement-submitted state, and 409 when the carrier refuses (amend window expired or order already completed). Poll the provider for a fresh carrier decision with:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/refresh \
  -H "X-API-Key: dv_live_sk_..."

Manual-mode requests (submitted without country) return 422 here — there is no carrier order to refresh. Cancel outright with DELETE /porting/:id; that is only possible while in submitted or reviewing — it returns 409 once the losing carrier has approved.

6. Track — timeline stages and FOC

GET /porting/:id/timeline expands the flat status enum into a structured per-stage view — a pure read on the stored row, no carrier call:

curl "https://api.orbit.devotel.io/api/v1/numbers/porting/port_abc123/timeline" \
  -H "X-API-Key: dv_live_sk_..."

{
  "data": {
    "portingId": "port_abc123",
    "status": "reviewing",
    "stages": [
      { "stage": "submitted", "state": "completed", "label": "Submitted", "enteredAt": "2026-08-01T10:00:00.000Z" },
      { "stage": "validating_loa", "state": "completed", "label": "Validating LoA", "enteredAt": "2026-08-01T10:00:00.000Z" },
      { "stage": "carrier_review", "state": "current", "label": "Losing carrier review", "enteredAt": "2026-08-01T10:00:00.000Z" },
      { "stage": "foc_assigned", "state": "pending", "label": "FOC date assigned" },
      { "stage": "foc_scheduled", "state": "pending", "label": "Scheduled for FOC" },
      { "stage": "completed", "state": "pending", "label": "Port complete" }
    ],
    "elapsedDays": 4,
    "focDate": null
  }
}

Status maps to stages: submitted → submitted, reviewing → carrier_review (LOA already validated), approved → foc_assigned (or foc_scheduled when focDate is set), completed → completed, rejected → snapshot at whichever stage it died at. focDate is echoed once the losing carrier assigns one. On a rejected port, stages after the current one come back skipped so a status dashboard does not show a ghost-future. When status is rejected, the response carries a rejection object that translates the carrier’s opaque reject code (Telnyx ADM/NMM, Bandwidth 5005/5006, DIDWW ADDRESS_DOES_NOT_MATCH, numeric NIIF codes, and more) into a plain-English summary and recommendedAction, tagged with a severity:

operator_fixable — fix your own data and resubmit inside the amend window (address/name/PIN/BTN/supplement issues).
needs_carrier — contact the losing carrier to resolve (unrecognized account number, conflicting order).
fatal — the number cannot be ported at all (NUMBER_NOT_PORTABLE); keep it at the losing carrier.

Unknown codes fall through with the raw carrier text preserved rather than being hidden, so an operator can always escalate with the exact reason.

7. Webhook-driven ops — build a status dashboard

Subscribe to these events instead of polling timeline on a loop — register once, and Orbit pushes each transition to your endpoint (see Webhooks overview and Webhook Security for signature verification):

curl -X POST https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": [
      "number.ported",
      "porting.request.loa_signed",
      "porting.request.supplement_submitted",
      "porting.request.manual_review_required",
      "porting.request.cancelled"
    ]
  }'

Event	Fires when	Use it to
`number.ported`	The port-in completed and the number is live on your account.	Cut routing, send the “you’re live” notification, kick off post-port provisioning. Emitted exactly once.
`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 (ops processes the LOA by hand).	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 for the migration ledger.

Compose these into a status dashboard by joining the event stream with the timeline endpoint — events drive the realtime updates, and a daily GET /porting + timeline sweep reconciles anything missed (deliveries are at-least-once, so dedupe on the event id). That combination gives you a live board of “where is every port stuck and what do I do about it” without a carrier call per page load. Dashboard vs. API path: the dashboard renders the same timeline and rejection explanation in the porting wizard, and bulk CSV upload has a UI twin — use it for a one-off operator-led migration. Use the API when you need the gate (pre-validate) in a pipeline, the event stream wired into your own ops tooling, or a 500-DID estate you cannot click through. Both paths read the same underlying request, so you can mix them — submit by API, watch in the dashboard.

8. Bulk CSV migration — 50-1000 DIDs at once

Migrating a whole DID estate as one handoff does not fit the one-number-at-a-time form. Upload a CSV instead:

curl -X POST https://api.orbit.devotel.io/api/v1/numbers/port-in/bulk-csv \
  -H "X-API-Key: dv_live_sk_..." \
  -F "file=@port-in-batch.csv"

The CSV must have a header row with exactly these columns (order does not matter, header matching is case-insensitive):

phone_number, current_carrier_account_number, current_carrier_name, billing_name, billing_address

A complete example row set for a three-line migration:

phone_number,current_carrier_account_number,current_carrier_name,billing_name,billing_address
+14155551234,998877,Acme Telecom,Jane Doe,"1 Market St, San Francisco, CA 94105, US"
+14155555678,998877,Acme Telecom,Jane Doe,"1 Market St, San Francisco, CA 94105, US"
+14155559901,112233,Acme Telecom,Jane Doe,"410 Pine St, Suite 200, Seattle, WA 98101, US"

Rules and caps:

Quote any field containing a comma (billing_address almost always needs it). A header missing a required column aborts the whole upload with 422 and names the missing columns.
Each valid row becomes its own porting request (status: submitted, stored for manual carrier dispatch) — bulk import does not fire 50-1000 sequential carrier calls inside one request. Your team attaches the LOA and country code per-row afterwards through the normal dashboard flow.
2MB file size (roughly 12k rows), 1000 rows per request, 30-second processing budget, rate-limited to 2 requests per minute per organization. Split a larger estate across uploads rather than retrying a timed-out one. Duplicate submissions against an active in-flight request are skipped; the response reports both sides of the batch:

{
  "data": {
    "request_ids": ["port_a1b2c3", "port_d4e5f6"],
    "validation_errors": [
      { "row": 14, "field": "phone_number", "error": "Not a valid E.164 number" }
    ],
    "duplicates_skipped": 2,
    "summary": {
      "total_rows": 3,
      "created_count": 2,
      "duplicate_count": 2,
      "validation_error_count": 1,
      "overall_result": "partial"
    }
  }
}

Run the preflight bulk check on the same number list before you upload — it is far cheaper to drop a non-portable DID from the CSV than to rear-face a rejection days later.

9. After the port — lifecycle, hosted messaging, RespOrg

Once number.ported fires:

The number enters the normal lifecycle — auto-renew, scheduled release, reassignment, and reclaim all apply to ported numbers the same as purchased ones. See Number Lifecycle.
SMS on a ported DID behaves exactly like a purchased DID on Orbit — no extra step.
Hosted messaging / text-enable without porting — if you deliberately kept voice with the losing carrier (or the number was not voice-portable), you can still text-enable it via POST /numbers/hosted-messaging. That is a carrier-side SMS route with its own LOA, not a port.
Toll-free post-port administration lives under the RespOrg flow (/porting/toll-free/resporg — you re-home the number, not port it). Route changes go through Somos out-of-band.

Checklist for the next migration: build the E.164 list → pull the CSR → run pre-validate to ready: true → submit (or checkpoint with draft: true when the LOA is still outstanding) → upload/sign/submit LOA → subscribe the five events → track on the timeline → react to number.ported → hand off to lifecycle. That is the whole loop.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Porting numbers end-to-end: preflight, LOA, FOC, and bulk CSV

Port a number end-to-end

1. Prep the data

2. Preflight — gate before you submit

3. Submit the port

Wizard draft intake

Resume and submit from a draft

4. LOA lifecycle — upload, sign, submit

5. Supplier response loop — supplements and refresh

6. Track — timeline stages and FOC

7. Webhook-driven ops — build a status dashboard

8. Bulk CSV migration — 50-1000 DIDs at once

9. After the port — lifecycle, hosted messaging, RespOrg

See Also

​Port a number end-to-end

​1. Prep the data

​2. Preflight — gate before you submit

​3. Submit the port

​Wizard draft intake

​Resume and submit from a draft

​4. LOA lifecycle — upload, sign, submit

​5. Supplier response loop — supplements and refresh

​6. Track — timeline stages and FOC

​7. Webhook-driven ops — build a status dashboard

​8. Bulk CSV migration — 50-1000 DIDs at once

​9. After the port — lifecycle, hosted messaging, RespOrg

​See Also

Port a number end-to-end

1. Prep the data

2. Preflight — gate before you submit

3. Submit the port

Wizard draft intake

Resume and submit from a draft

4. LOA lifecycle — upload, sign, submit

5. Supplier response loop — supplements and refresh

6. Track — timeline stages and FOC

7. Webhook-driven ops — build a status dashboard

8. Bulk CSV migration — 50-1000 DIDs at once

9. After the port — lifecycle, hosted messaging, RespOrg

See Also