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.

​
How the common transitions look

There are five paths a number traverses from purchase:
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 — set manually or when provisioning never succeeded. You can still see it with a status 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.
  • Number lifecycle — the operations (auto-renew, release, reassign, retry-release, reclaim, repair-provisioning, attach-compliance-profile, trial pool) that move a number through these states.
  • Numbers overview — the Numbers pillar surface.