Numbers
Release a number
Cancels a number you bought through Vobiz and removes it from your account. The number stops sending and receiving messages immediately, and monthly rental stops.
POST
/
numbers
/
{e164}
/
release
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/numbers/{e164}/release \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.numbers.release_number(
e164="+14155550100",
)
const options = {
method: 'POST',
headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};
fetch('https://api.vobiz.ai/api/v1/sms/numbers/{e164}/release', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"purchase": {
"id": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"accountId": "MA_XXXXXXXX",
"provider": "internal",
"e164": "+14155550100",
"countryCode": "US",
"type": "VIRTUAL_LONG_NUMBER",
"capabilities": [
"VOICE",
"SMS",
"MMS"
],
"setupAmount": 1,
"monthlyAmount": 1,
"currency": "USD",
"status": "released",
"purchasedAt": "2026-10-12T09:06:44Z",
"nextBillingAt": null,
"releasedAt": "2026-10-20T14:02:10Z",
"createdAt": "2026-10-12T09:06:42Z",
"updatedAt": "2026-10-20T14:02:10Z",
"charges": [
{
"purchaseId": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"kind": "purchase",
"periodStart": "2026-10-12T09:06:42Z",
"amount": 2,
"currency": "USD",
"status": "paid",
"reference": "sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"attempts": 1,
"attemptedAt": "2026-10-12T09:06:42Z"
}
]
}
}
Authorizations
Your Vobiz account Auth ID (MA_XXXXXXXX).
Your Vobiz account Auth Token.
Path Parameters
The number to release, in E.164 format, for example +14155550100. In raw HTTP requests, URL-encode the + as %2B; the SDKs encode it for you. A value that is not an E.164 number returns 400, and a number that is not on your account returns 404.
Response
The number is released. status is released, releasedAt is set and nextBillingAt is null.
The result of releasing a number.
The purchase record after release, with status: released, releasedAt set and nextBillingAt set to null.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
cURL
curl --request POST \
--url https://api.vobiz.ai/api/v1/sms/numbers/{e164}/release \
--header 'X-Auth-ID: <api-key>' \
--header 'X-Auth-Token: <api-key>'from vobiz import Vobiz
client = Vobiz(api_key="MA_XXXXXXXX", auth_token="YOUR_AUTH_TOKEN")
client.sms.numbers.release_number(
e164="+14155550100",
)
const options = {
method: 'POST',
headers: {'X-Auth-ID': '<api-key>', 'X-Auth-Token': '<api-key>'}
};
fetch('https://api.vobiz.ai/api/v1/sms/numbers/{e164}/release', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"purchase": {
"id": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"accountId": "MA_XXXXXXXX",
"provider": "internal",
"e164": "+14155550100",
"countryCode": "US",
"type": "VIRTUAL_LONG_NUMBER",
"capabilities": [
"VOICE",
"SMS",
"MMS"
],
"setupAmount": 1,
"monthlyAmount": 1,
"currency": "USD",
"status": "released",
"purchasedAt": "2026-10-12T09:06:44Z",
"nextBillingAt": null,
"releasedAt": "2026-10-20T14:02:10Z",
"createdAt": "2026-10-12T09:06:42Z",
"updatedAt": "2026-10-20T14:02:10Z",
"charges": [
{
"purchaseId": "5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"kind": "purchase",
"periodStart": "2026-10-12T09:06:42Z",
"amount": 2,
"currency": "USD",
"status": "paid",
"reference": "sms_number_purchase:5c2d9e7a-1b4f-4a8c-9e3d-6f7a0b1c2d3e",
"attempts": 1,
"attemptedAt": "2026-10-12T09:06:42Z"
}
]
}
}