Skip to main content

​
Number status map

Every phone number in Orbit carries a status value. The vocabulary is a closed set of six states, and every Numbers page and list endpoint you touch reads one of them. This page defines what each state means, who moves a number into it, and which transitions are reversible. The lifecycle operations (auto-renew, release, reassign, reclaim) that move a number through these states are documented step by step in Number lifecycle — this page is the anchor for the status vocabulary those operations depend on.

​
The six states

The lifecycle is a closed enum. A number is always in exactly one of:
  • active — held and fully usable. Works for sending, receiving, and billing.
  • pending_compliance — purchased into a regulated country and the carrier-approved compliance bundle is still being verified. Not yet a usable number.
  • inactive — never provisioned or deliberately disabled. Shows in listings but is not usable.
  • released — let go. The carrier DELETE completed, and this is a terminal state — the only path back in is a fresh purchase.
  • parked — mid-release grace window. Holding the number against upstream release so you can reclaim it during a bounded window.
  • suspended — soft pause on a NaaS DID (for an overdue balance or a manual suspend). It stops sending and receiving until reactivated.

​
One more status exists mid-transition

The six values above are the states a number can settle into. One further, synthetic member joins the closed enum while a port-out is in flight: port_out_pending — the DID is claimed by an outbound port order and sits between active (its only entry edge, returning there on cancel/failure) and gone (on completion). It is not a seventh lifecycle path; it exists so the list endpoint, dashboard badge, and every ownership guard can treat a mid-port number uniformly. The two-direction model that defines it lives in Number portability model, and its guards live in Port-out lifecycle and ownership model.

​
Wire vs. terminal

The six states split by the same distinction the delivery lifecycle draws for messages: one terminal outcome, and five states a number can visibly leave again. There are six paths a number traverses from purchase. Annotating them, only one arrow is irreversible:
parked is the last reversible stop on the release path — cross it, and the row is gone. Every regulated-country purchase routes through pending_compliance before it is active, because the carrier only approves the compliance bundle after Orbit attaches it.

​
What each state means, and who sets it

  • active — set at purchase when the country has no regulatory bundle, and set from pending_compliance once the carrier accepts the attached compliance profile. The dashboard and list endpoints default to active when no status filter is supplied.
  • pending_compliance — set at purchase into a regulated country. Orbit auto-releases it after its grace window unless you attach a compliance profile first (Attach a compliance profile).
  • inactive — never provisioned or deliberately unhooked. Either way, the number is still yours; it only stops being usable. Set it yourself by sending PUT /numbers/:id with status: "inactive" (the same update accepts status: "active" to bring it back — the configuration stays intact, so re-enabling is free). Provisioning arrives at it the other way: when a purchase left the messaging-profile or voice-connection attachment incomplete, the row waits for repair provisioning instead of ever reaching active. Both directions route through the update endpoint, not the lifecycle schedulers, so PUT and repair- provisioning are the only two doors into inactive. You can still see the row with a status=inactive filter on the list endpoint.
  • released — set after the graceful-release parking window closes and the carrier DELETE completes. Terminal; recover by purchasing again.
  • parked — set when you schedule a release. The parking-expiry scheduler is the only actor that moves the row from parked to released. During the window, POST /:id/reclaim moves it back to active without re-purchasing.
  • suspended — set for an overdue balance or a manual suspend on a NaaS DID. It is an explicit soft pause; reactivation flips it back to active with the configuration intact. Only an active number can be suspended, so pending_compliance, parked, and released rows are rejected with 409.

​
Filtering by status on the list endpoint

GET /numbers accepts a status query. Omit it and the list returns active rows only. Pass one value (suspended, released, …) and you get that subset. Pass status=all to see every state at once, and pass a comma-separated list to union several states in one call. The dashboard Active tab deliberately queries the union active,pending_compliance so a newly-purchased regulated-country DID shows up alongside your usable numbers instead of disappearing from the list until its compliance clears.

​
Suspended is not released

Use suspended when you want the number to come back under you (an overdue balance, a manual pause). Use released only for a verified teardown. parked sits between them: the number was handed to a release schedule but the grace window is still open, so it is reclaimable until the scheduler closes it.

​
Timeline examples

  • Fresh purchase, unregulated country — purchase completes and the number lands at active immediately.
  • Fresh purchase, regulated country — purchase lands at pending_compliance. Attach the approved compliance profile (POST /:id/attach-compliance-profile); the carrier webhook flips the row to active. If the grace window lapses first, Orbit auto-releases it to released.
  • Trial-pool number — claimed from the shared pool as active. Purchasing flips your claim to permanent ownership, releasing returns it to the pool.
  • Scheduled release — you schedule it; the number moves to parked. The parking-expiry scheduler moves it to released when the window ends, unless you reclaim it first.
  • Reclaim during the grace window — a parked number moves back to active via POST /:id/reclaim without another purchase.

​
States and the operations that move them

The mechanics live in Number lifecycle — this table maps every state to the operations that can move it into or out of the state you hold. Use it as the index; the linked section is where the operation itself runs step by step. Operations that update a number without touching its state — auto-renew toggle, reassign to a subaccount, capability and label updates — ride on the same rows but never move a state.
  • Number portability model — where the synthetic port_out_pending status comes from, and the unified port-in/port-out model it anchors.
  • Number lifecycle — the step-by-step operations.
  • Number rental and your wallet — the money arc that moves a number into suspended (unpaid renewal → 7-day grace → suspend → reactivate) and the controls that keep it from happening.
  • Numbers overview — the Numbers pillar surface.