Release a Phone Number

DELETE

api

Account

{auth_id}

numbers

{e164}

Release a number

curl --request DELETE \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164} \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164}"

headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>"
}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "cancel_url": "/api/v1/account/MA_XXXXXX/numbers/+919876543210/cancel-release",
  "cooldown_ends_at": "2026-07-21T09:18:26.785758533Z",
  "message": "number release initiated",
  "note": "Number will be in pending_release for 24 hours (cancellable), then quarantined for 45 days before becoming available.",
  "release_fee": 700,
  "status": "pending_release"
}

DELETE https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164}

Releases a phone number from your account. Vobiz charges the number-release fee configured for your account. A standard release enters pending_release for 24 hours before it completes.

Releasing or unrenting a number is not free. The release fee is account-specific, and the API returns the amount charged in release_fee.

Authentication required:

X-Auth-ID - Your Auth ID (e.g., {auth_id})
X-Auth-Token - Your account Auth Token
Content-Type: application/json

Releasing a number detaches its trunk and voice application. Cancelling a pending release restores the number to active, but it does not restore those routing assignments.

During the 24-hour cooldown, use Cancel Release to keep the number. An immediate release cannot be cancelled.

If you cancel a standard release while it is still pending, Vobiz refunds the full release fee to your account balance.

Release fee

The amount charged for unrenting a number comes from your account’s pricing configuration. It is separate from the recurring monthly rental fee that stops after release.

The release operation is not free.
The fee can differ between Vobiz accounts.
The successful release response reports the charged amount in release_fee.
Cancelling a standard release during the 24-hour pending window refunds that fee.
An immediate release cannot be cancelled through the Cancel Release endpoint.

Path parameters

auth_id - Your account Auth ID.
e164 - The phone number to release in E.164 format. URL-encode + as %2B, such as %2B919876543210.
immediate - Optional boolean query parameter. Set it to true to skip the 24-hour cooldown.

This path uses the capital-A /Account/ casing. The e164 segment must include the URL-encoded +. No request body is required.

Request

Standard release

cURL Request

curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/%2B919876543210" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}"

Immediate release

cURL Request

curl -X DELETE "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/%2B919876543210?immediate=true" \
  -H "X-Auth-ID: {auth_id}" \
  -H "X-Auth-Token: {auth_token}"

Response

A standard release returns 200 OK with the cooldown, cancellation URL, and the account-specific fee charged for the release.

Response - 200 OK

{
  "cancel_url": "/api/v1/account/MA_XXXXXX/numbers/+919876543210/cancel-release",
  "cooldown_ends_at": "2026-07-21T09:18:26.785758533Z",
  "message": "number release initiated",
  "note": "Number will be in pending_release for 24 hours (cancellable), then quarantined for 45 days before becoming available.",
  "release_fee": 700,
  "status": "pending_release"
}

The release_fee value above is an example. Your response contains the fee configured for your Vobiz account.

Standard release: The number enters pending_release for 24 hours. You can cancel during this window.Immediate release: The number skips the cooldown and cannot be recovered through the Cancel Release endpoint.

Error Response (403 Forbidden): If account does not own this number:

Error Response - 403 Forbidden

{
  "error": "forbidden",
  "message": "account does not own this number"
}

Authorizations

X-Auth-ID

string

header

required

Your Vobiz account Auth ID

X-Auth-Token

string

header

required

Your Vobiz account Auth Token

Path Parameters

auth_id

string

required

Your account Auth ID

Example:

"MA_XXXXXX"

e164

string

required

The URL-encoded phone number in E.164 format. Encode + as %2B.

Example:

"%2B919876543210"

Query Parameters

immediate

boolean

default:false

Skip the 24-hour cooldown and release the number immediately.

Response

200 - application/json

Release initiated

cancel_url

string

required

cooldown_ends_at

string<date-time>

required

message

string

required

release_fee

number

required

The account-specific fee charged for releasing the number.

status

string

required

note

string

⌘I

Release a number

curl --request DELETE \
  --url https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164} \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164}"

headers = {
    "X-Auth-ID": "<api-key>",
    "X-Auth-Token": "<api-key>"
}

response = requests.delete(url, headers=headers)

print(response.text)

const options = {
  method: 'DELETE',
  headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};

fetch('https://api.vobiz.ai/api/v1/Account/{auth_id}/numbers/{e164}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "cancel_url": "/api/v1/account/MA_XXXXXX/numbers/+919876543210/cancel-release",
  "cooldown_ends_at": "2026-07-21T09:18:26.785758533Z",
  "message": "number release initiated",
  "note": "Number will be in pending_release for 24 hours (cancellable), then quarantined for 45 days before becoming available.",
  "release_fee": 700,
  "status": "pending_release"
}

​Release fee

​Path parameters

​Request

​Standard release

​Immediate release

​Response

Authorizations

Path Parameters

Query Parameters

Response

Release fee

Path parameters

Request

Standard release

Immediate release

Response