Skip to main content

​
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. 
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 }'

​
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. 
# 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. Sending release_at: null on the PATCH /:id/scheduled-release variant also clears the schedule.

​
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. 
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 the number must be in a purchased state. 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. 
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. 
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. 
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. 
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. 
# 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.