Number Porting (LNP)

Bring numbers from another carrier onto Orbit. A port-in request moves through carrier review, a Letter of Authorization (LOA), and a Firm Order Commitment (FOC) date before the number lands on your account — this guide covers the full self-serve flow: submitting a request, attaching and signing the LOA, reading the structured status timeline, reacting to webhooks, and migrating a large DID estate in one CSV upload. Read operations (list, get, timeline, the check / pre-validate preflight lints) are available to any role on the organization. Writes (create, LOA upload/sign/submit, supplement, cancel) require the numbers:write scope and an owner, admin, or developer role.

Submit a Port-In Request

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"
    }
  }'

numbers accepts a single E.164 string or an array for a multi-line port under one account. Omit country to store the request without dispatching to a carrier — useful when your team wants to attach documents before Orbit forwards it. Before submitting, run a portability preflight to catch a non-portable number early:

# Single number
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" }'

# Batch check — up to 1000 distinct numbers per call, chunked upstream to the carrier
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"] }'

# Combined readiness gate (portability + CSR/address checks) before you submit
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"], "country": "US" }'

pre-validate and check/bulk are rate-limited to 5 requests per minute per auth context.

Upload and Sign the LOA

The Letter of Authorization proves you’re authorized to move the number. Orbit exposes a dedicated upload → sign → submit lifecycle instead of accepting a bare file URL:

# 1. Upload the signed-by-hand 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"

# 2. Capture an 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."
  }'

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

Each step transitions loaSignatureStatus: upload sets it to draft, signing moves it to signed, and submit forwards it to the carrier. The state machine is one-directional — once a LOA is signed or submitted, re-uploading a replacement is refused; cancel the porting request and resubmit instead if the wrong document went out. Signing twice returns 422, not a silent merge. If the losing carrier kicks back a supplement request (a minor data correction — usually an address line or suite number), respond within the 7-day amend window so the FOC clock doesn’t 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" } }'

Track the Status Timeline

GET /porting/:id/timeline expands the flat porting status into a structured, per-stage view — submitted → validating_loa → carrier_review → foc_assigned → foc_scheduled → completed — so you can show operators exactly where a port is stuck without calling the losing carrier.

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 is echoed on the timeline once the losing carrier assigns one. If the port is rejected, the response includes a rejection object that translates the carrier’s opaque reject code (Telnyx/DIDWW/Bandwidth vocabularies, including numeric NIIF codes) into a plain-English summary and recommendedAction, tagged with a severity of operator_fixable, needs_carrier, or fatal so you know whether to fix your own data or escalate. Unknown codes fall through with the raw carrier text preserved rather than being hidden. Poll for a fresh carrier decision with POST /porting/:id/refresh, or cancel outright with DELETE /porting/:id.

React to Porting Webhooks

Subscribe to these events instead of polling timeline on a loop — see Webhook Events for the full catalog and Webhook Security for signature verification:

Event	Fires when
`number.ported`	The port-in completed and the number is live on your account.
`porting.request.loa_signed`	The in-platform LOA signature was captured.
`porting.request.supplement_submitted`	You submitted a carrier-requested supplement/amendment.
`porting.request.manual_review_required`	The port fell back to manual review (ops will process the LOA by hand).
`porting.request.cancelled`	You or an admin cancelled the request.

Bulk CSV Port-In (Enterprise Migration)

Migrating 50-500 DIDs from another carrier as a single handoff doesn’t 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 doesn’t matter, matching is case-insensitive):

phone_number, current_carrier_account_number, current_carrier_name, billing_name, billing_address

Each valid row becomes its own porting request (status: submitted, stored for manual carrier dispatch) so your team can attach the LOA and country code per-row afterwards through the normal dashboard flow — bulk import does not attempt 50-500 sequential carrier calls inside one request. 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" }
    ]
  }
}

Caps: 2MB file size (roughly 12k rows), 1000 rows per request, and a 30-second processing budget. The endpoint is rate-limited to 2 requests per minute per organization — split a larger ledger into multiple uploads rather than retrying a timed-out one.

Set Up a Ported Number

Once the port completes, provision the number’s regulated identity from the number’s detail page or API before you route traffic to it:

Emergency Address (E911) — register and validate the per-number dispatchable emergency address when the ported number carries voice.
CNAM & Caller ID — register the branded caller name recipients see, dip the carrier’s CNAM database for the currently registered name, and remediate “Spam Likely” or “Scam Likely” labels.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Changelog

Number porting: LOA upload, FOC scheduling, status timeline, and bulk CSV

Number Porting (LNP)

Submit a Port-In Request

Upload and Sign the LOA

Track the Status Timeline

React to Porting Webhooks

Bulk CSV Port-In (Enterprise Migration)

Set Up a Ported Number

See Also

​Number Porting (LNP)

​Submit a Port-In Request

​Upload and Sign the LOA

​Track the Status Timeline

​React to Porting Webhooks

​Bulk CSV Port-In (Enterprise Migration)

​Set Up a Ported Number

​See Also

Number Porting (LNP)

Submit a Port-In Request

Upload and Sign the LOA

Track the Status Timeline

React to Porting Webhooks

Bulk CSV Port-In (Enterprise Migration)

Set Up a Ported Number

See Also