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

> Auto-renew, schedule releases, reassign between subaccounts, retry failed releases, and manage trial numbers

# Number Lifecycle

Once you own a number, Orbit gives you full lifecycle control: keep it billing automatically, schedule a future teardown, hand it to a sibling subaccount, recover from a failed carrier release, or reclaim a parked number during its grace window.

All lifecycle mutations are gated by org ownership — a sibling subaccount sharing your tenant schema cannot touch a number it doesn't own.

## Auto-Renew

Toggle automatic recurring renewal so a held number is re-billed each cycle instead of lapsing at `next_billing_at`.

```bash theme={null}
curl -X PATCH https://api.orbit.devotel.io/api/v1/numbers/num_abc123/auto-renew \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "auto_renew": true }'
```

## Renewal Reminders & Low-Balance Warnings

A held number's monthly rental is charged from your wallet each cycle. When your balance can't cover an upcoming charge, Orbit warns you before the renewal is attempted — and again if it fails — so a number never lapses without notice.

* **Before the renewal.** When a number is approaching its renewal date and your wallet balance is already below the monthly charge, every owner and admin gets an email ("Action needed: add funds before your number renews") and an in-app alert in the Notification Center ("Number renewal at risk — add funds"). Both link to the wallet top-up screen. The email is throttled and the in-app alert fires at most once per billing cycle, so a low balance won't produce a daily pile-up of reminders.
* **When the renewal fails.** If the charge is attempted with too little balance, you get a follow-up notice ("Number renewal failed — add funds"). The number stays active and Orbit re-attempts the charge once a day. Once you top up, the next attempt renews the number automatically — no manual step needed.
* **After the grace window.** A renewal that stays unpaid for 7 days past its due date suspends the number. A suspended number stops sending and receiving until you add funds and reactivate it from the Numbers page. It is not released, so reactivating restores it unchanged.

To clear a warning, add funds from **Billing**, then confirm the number reads `active` on the Numbers page. Owner and admin users receive these notices; other team members are not emailed.

## Scheduled Release

Pre-plan a teardown (seasonal campaign DIDs, trial overflow, contract end-of-term) without remembering to release on the day. A separate sweeper drives the existing release path when the date arrives.

```bash theme={null}
# Schedule a future release
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-09-01T00:00:00.000Z" }'

# Read the current schedule
curl "https://api.orbit.devotel.io/api/v1/numbers/num_abc123/scheduled-release" \
  -H "X-API-Key: dv_live_sk_..."

# Clear it
curl -X DELETE https://api.orbit.devotel.io/api/v1/numbers/num_abc123/scheduled-release \
  -H "X-API-Key: dv_live_sk_..."
```

`release_at` is an ISO-8601 future timestamp.

<Warning>
  The `PUT` / `GET` / `DELETE /:id/scheduled-release` trio above is the canonical scheduled-release surface — all three verbs read and write the **same** schedule.

  A separate `PATCH /:id/scheduled-release` endpoint (body `{ "release_at": "<iso>" | null }`) also exists, but it keeps its **own independent** schedule and does **not** interoperate with the trio: a schedule set with `PUT` is not returned by `GET`, is not removed by the `PATCH` endpoint, and vice versa. `PATCH` with `release_at: null` clears only the `PATCH` schedule, never the one set via `PUT`. Pick one surface and use it consistently — for read/write/clear, prefer the `PUT` / `GET` / `DELETE` trio.
</Warning>

## Reassign to a Subaccount

Move a purchased number from your subaccount to a sibling subaccount under the same reseller parent — the DID parity to wallet transfer-to-subaccount.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/num_abc123/reassign \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "target_org_id": "org_sibling456" }'
```

The target must be a same-tenant, same-family sibling, and your subaccount must currently own the number. Eligibility is decided by ownership, not by a status value: a number your subaccount doesn't own (including a trial-pool number you've only claimed) can't be reassigned. Cross-tenant or unowned moves are rejected.

## Retry a Failed Release

When a carrier `DELETE` fails (`release_status = "failed"` or stuck `pending`), re-issue it without re-purchasing.

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

## Reclaim a Parked Number

Re-claim a parked number during its grace window without re-purchasing from upstream. Returns `409` when the number isn't reclaimable (not parked, wrong org, or window expired) — fall back to a fresh purchase in those cases.

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

## Repair Provisioning

Re-attach the messaging profile and voice connection on a number whose original purchase left them partial.

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

## Attach a Compliance Profile

For a number that landed at `pending_compliance`, attach an approved compliance profile. Orbit re-submits the profile to the carrier and patches the pending order; a carrier webhook later flips the row to `active`.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/num_abc123/attach-compliance-profile \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "compliance_profile_id": "cprof_abc123" }'
```

## Trial & Shared-Pool Numbers

New organizations can claim a trial number from a shared pool, then purchase it to keep it permanently or release it back.

```bash theme={null}
# Get the current trial assignment (null when none)
curl "https://api.orbit.devotel.io/api/v1/numbers/trial" \
  -H "X-API-Key: dv_live_sk_..."

# Claim a trial number from the pool
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/claim-trial \
  -H "X-API-Key: dv_live_sk_..."

# Purchase the trial number to keep it
curl -X POST https://api.orbit.devotel.io/api/v1/numbers/purchase-trial \
  -H "X-API-Key: dv_live_sk_..."

# Release it back to the pool
curl -X DELETE https://api.orbit.devotel.io/api/v1/numbers/release-trial \
  -H "X-API-Key: dv_live_sk_..."
```

Claim and purchase are rate-limited to 5 requests per minute per tenant.