Skip to main content

​
Number dormancy and rental spend

A phone number can remain active and billable after its last call or message. Dormancy monitoring gives you a review signal for those numbers; it does not make release decisions for you. This model uses the active → parked → released release path. It does not change the number lifecycle or add a new number status.

​
Why dormancy matters on a prepaid meter

A quiet number can continue accruing monthly rental even when it no longer appears in traffic dashboards. Usage views answer how much traffic moved; they do not tell you which rented numbers have gone unused long enough to review. The dormancy signal adds that inventory-level view so you can decide whether to keep or release each number. For how number rental is charged alongside wallet renewals, see Billing and numbers renewal model.

​
How Orbit detects dormancy

Orbit runs a daily sweep at 05:30 UTC. For each tenant, it reads active numbers and derives each number’s last activity from locally stored message and call records. Inbound and outbound activity both count, across SMS and voice. A number with no activity in the selected window is reported only after it has been held for that window; a never-used number is reported once it passes the same age threshold. The window is configured per organization at organizations.settings.numbers.dormancy_alert_days. The default is 30 days, and the supported range is 1–365 days. If the setting is absent or invalid, Orbit uses the default. You can also pass ?days=<1..365> to the read endpoint to preview a different window without changing the organization setting. The sweep is tenant-scoped and considers numbers owned by the organization. The activity check uses Orbit’s locally stored messages and call logs, not a live carrier query. Activity that is not represented in those records will not reset the dormancy window.

​
Two read surfaces

Use the list endpoint when an operator needs to inspect candidates and their estimated monthly cost:
GET /api/v1/numbers/dormancy-alerts returns dormancy_days, default_dormancy_days, a summary, and an alerts list. Each alert includes the number, last_activity_at, dormant_days, never_used, monthly_cost, owned_days, threshold_days, and suggested_release. The summary.reclaimable_monthly_spend field totals the candidates’ monthly costs; it is an estimate of potential rental reduction, not a credit or refund. The response also reports dormant_count, never_used_count, the currency, and whether the results were truncated. For automation-first workflows, subscribe to the number.dormant webhook. Orbit sends one event per dormant number to the tenant’s configured webhook endpoints. Use it to start your own review or approval flow; do not treat receipt as authorization to release a number automatically unless that is your intended policy. See Webhook events for event vocabulary and Number API reference for the response contract.

​
What dormancy does not do

Dormancy is a signal only. It never releases, parks, or suspends a number. You choose what to do after reviewing the activity window and the number’s business purpose. Release remains an operator action through the existing scheduled-release lifecycle. Scheduling starts the active → parked path; the number stays reclaimable during its parking window, then the parking-expiry scheduler advances it to released unless you reclaim it first. For the complete status map and release controls, see Number lifecycle and Number lifecycle operations.

​
Worked flow: review, then release

  1. Receive a number.dormant event, or open the dormancy-alerts list.
  2. Fetch GET /api/v1/numbers/dormancy-alerts and match the event’s number to its current alert. Check last_activity_at, dormant_days, and suggested_release.
  3. Confirm that the quiet period is expected and that the number has no ongoing customer or operational use. A webhook is not a substitute for this review.
  4. If you decide to release it, schedule the release using the lifecycle API:
  5. The number follows active → parked → released if you take no further action. Reclaim it with POST /api/v1/numbers/num_abc123/reclaim while it is still parked to restore it to active without purchasing again.
Wrong-release recovery stops at reclaim: once the parking-expiry scheduler has moved a number to released, the row is terminal and the number must be purchased again. Review the grace window before it closes. See Number lifecycle operations for details.