Cancel a Number Release

POST

api

account

{account_id}

numbers

{e164}

cancel-release

Cancel a number release

curl --request POST \
  --url https://api.vobiz.ai/api/v1/account/{account_id}/numbers/{e164}/cancel-release \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://api.vobiz.ai/api/v1/account/{account_id}/numbers/{e164}/cancel-release"

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

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

print(response.text)

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

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

{
  "message": "release cancelled, number restored to active status",
  "status": "active",
  "currency": "INR",
  "refund_amount": 700
}

Cancels a pending number release during the 24-hour cooldown and restores the number to active.

Cancelling a pending release refunds the full release fee to your account balance. The response reports the refund in refund_amount and currency.

POST https://api.vobiz.ai/api/v1/account/{account_id}/numbers/{e164}/cancel-release

You can cancel only while the number is in pending_release. After the 24-hour cooldown ends, this endpoint returns 400 and recovery requires manual intervention.

Authentication

The API playground uses the same authentication fields as the other Vobiz API pages:

X-Auth-ID - Your account Auth ID.
X-Auth-Token - Your account Auth Token.

The endpoint also accepts HTTP Basic authentication in direct requests. Use your Auth ID as the username and your Auth Token as the password, as shown in the cURL example below.

Do not send the Auth Token as Authorization: Bearer {auth_token}. Bearer authentication is for JWT access tokens and returns 401 Invalid token when used with an account Auth Token.

Path parameters

Parameter	Required	Description
`account_id`	Yes	Your account Auth ID, such as `MA_XXXXXX`.
`e164`	Yes	The phone number in E.164 format. URL-encode `+` as `%2B`, such as `%2B919876543210`.

Request

curl -X POST \
  "https://api.vobiz.ai/api/v1/account/{account_id}/numbers/%2B919876543210/cancel-release" \
  -u "{account_id}:{auth_token}"

curl -X POST \
  "https://api.vobiz.ai/api/v1/account/{account_id}/numbers/%2B919876543210/cancel-release" \
  -H "X-Auth-ID: {account_id}" \
  -H "X-Auth-Token: {auth_token}"

Behavior

When the number belongs to your account and is still in pending_release, Vobiz:

Verifies that your account owns the number.
Changes its status from pending_release to active and clears the cooldown timer.
Refunds the release fee to your account balance.
Returns 200 OK.

The original release already detached the trunk and voice application. Cancellation does not re-attach them. Assign the number to a trunk or attach it to an application before routing calls again.

Responses

HTTP	Meaning
`200`	The release was cancelled and the number was restored to `active`. The response includes the refunded amount and currency.
`400`	The number is not in `pending_release`, so there is nothing to cancel.
`401`	Authentication failed. Verify the authentication method and credentials.
`403`	The number does not belong to this account.
`404`	The number was not found.

Release cancelled and refunded

Response - 200 OK

{
  "currency": "INR",
  "message": "release cancelled, number restored to active status",
  "refund_amount": 700,
  "status": "active"
}

Number restored but refund failed

The number is active even when the refund fails. Contact Vobiz Support with the number and account details.

Response - 200 OK

{
  "message": "release cancelled, number restored to active status",
  "status": "active",
  "refund_status": "failed",
  "refund_error": "could not process refund, please contact support"
}

Error examples

{
  "error": "number is not pending release"
}

{
  "error": {
    "code": 401,
    "message": "Invalid token"
  }
}

{
  "error": "access denied"
}

{
  "error": "number not found"
}

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

account_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"

Response

Release cancelled and number restored to active

message

string

required

status

enum<string>

required

Available options:

active

currency

string

refund_amount

number

refund_status

enum<string>

Available options:

success,

failed

refund_error

string

Present when the refund could not be processed.

⌘I

Cancel a number release

curl --request POST \
  --url https://api.vobiz.ai/api/v1/account/{account_id}/numbers/{e164}/cancel-release \
  --header 'X-Auth-ID: <api-key>' \
  --header 'X-Auth-Token: <api-key>'

import requests

url = "https://api.vobiz.ai/api/v1/account/{account_id}/numbers/{e164}/cancel-release"

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

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

print(response.text)

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

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

{
  "message": "release cancelled, number restored to active status",
  "status": "active",
  "currency": "INR",
  "refund_amount": 700
}

​Authentication

​Path parameters

​Request

​Behavior

​Responses

​Release cancelled and refunded

​Number restored but refund failed

​Error examples

Authorizations

Path Parameters

Response

Authentication

Path parameters

Request

Behavior

Responses

Release cancelled and refunded

Number restored but refund failed

Error examples