Release a Number

Release a phone number you no longer need. Released numbers are returned to the available inventory after a cooling-off period.

Important Notes

Released numbers may have early termination fees depending on when they were purchased
Use the release preview endpoint first to check for any fees
Numbers have a cooling-off period before becoming available to other accounts
Once released, you cannot immediately re-purchase the same number

Preview Release

Before releasing a number, check if there are any early termination fees.

Endpoint

GET /v1/account/{account_id}/numbers/{e164}/release-preview

Request Example

curl --request GET \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/release-preview \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "e164": "+14155551234",
  "can_release": true,
  "early_termination_fee": 0.00,
  "currency": "USD",
  "cooling_off_period_days": 30,
  "warnings": []
}

If there's an early termination fee:

{
  "e164": "+14155551234",
  "can_release": true,
  "early_termination_fee": 25.00,
  "currency": "USD",
  "cooling_off_period_days": 30,
  "warnings": [
    "This number was purchased less than 3 months ago and has a $25.00 early termination fee"
  ]
}

Endpoint

DELETE /v1/account/{account_id}/numbers/{e164}

Request Example

curl --request DELETE \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234 \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "e164": "+14155551234",
  "status": "released",
  "released_at": "2026-04-09T11:45:00Z",
  "early_termination_fee": 0.00,
  "currency": "USD",
  "cooling_off_period_days": 30,
  "available_after": "2026-05-09T11:45:00Z"
}

Cancel a Release

If you released a number by mistake and it's still within the cooling-off period, you can cancel the release.

Endpoint

POST /v1/account/{account_id}/numbers/{e164}/cancel-release

Request Example

curl --request POST \
  --url https://api.tryvox.io/v1/account/acc_123abc/numbers/+14155551234/cancel-release \
  --header 'Authorization: Bearer tvx_sk_live_...'

Response

{
  "e164": "+14155551234",
  "status": "active",
  "release_cancelled_at": "2026-04-09T12:00:00Z",
  "message": "Number release cancelled successfully"
}

Release Response Fields

Field	Type	Description
e164	string	Phone number in E.164 format
status	string	Number status after release ("released")
released_at	string	ISO 8601 timestamp of release
early_termination_fee	number	Fee charged for early release (if any)
currency	string	Currency for fees (always "USD")
cooling_off_period_days	integer	Days before number becomes available
available_after	string	ISO 8601 timestamp when number becomes available

Error Handling

Common errors:

Error Code	Description
404	Number not found in your account
409	Number is already in the process of being released
400	Number cannot be released (e.g., active calls in progress)

Best Practices

Always check the release preview before releasing a number
Unassign the number from any trunks or applications before releasing
Ensure there are no active calls or ongoing billing issues
Keep a record of released numbers if you might need them again

Next Steps

List Your Numbers to view remaining numbers
Search Available Numbers to find replacement numbers

Release a Number

On this page