> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Number dormancy and rental spend

> Understand how Orbit flags quiet numbers, choose a tenant dormancy window, and review release candidates before monthly rental continues.

# 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](/concepts/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.

```mermaid theme={null}
flowchart LR
  renewal[Monthly renewal scheduler<br/>charges held numbers] --> rental[Monthly rental continues]
  activity[Locally stored calls and messages] --> dormancy[Daily dormancy sweep<br/>05:30 UTC]
  dormancy --> signal[Dashboard alerts and number.dormant webhook]
  signal --> review[Operator reviews traffic and cost]
  review --> scheduled[Operator schedules release]
  scheduled --> release[Scheduled-release scheduler]
  release --> park[active to parked]
  park --> expiry[Parking-expiry scheduler]
  expiry --> released[released]
```

## Two read surfaces

Use the list endpoint when an operator needs to inspect candidates and their estimated monthly cost:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/numbers/dormancy-alerts" \
  -H "X-API-Key: dv_live_sk_..."
```

`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](/reference/webhook-events) for event vocabulary and [Number API reference](/api-reference/numbers) 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](/concepts/number-lifecycle) and [Number lifecycle operations](/numbers/lifecycle).

## 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:

   ```bash theme={null}
   curl -X PUT "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/scheduled-release" \
     -H "X-API-Key: dv_live_sk_..." \
     -H "Content-Type: application/json" \
     -d '{"release_at":"2026-11-01T00:00:00.000Z"}'
   ```

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](/numbers/lifecycle#reclaim-a-parked-number) for details.

## Related number controls

* [Number status map](/concepts/number-lifecycle) — understand the active, parked, and released states and which transitions can be reversed.
* [Billing and numbers renewal model](/concepts/billing-and-numbers-renewal-model) — see how number rental interacts with wallet renewal.
* [Export number inventory](/numbers/inventory-export) — extract inventory to compare candidates with your own records.
* [Webhook events](/reference/webhook-events) — find the `number.dormant` event details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.