Unassign DID (15-Day Cool-Off)

DELETE

api

account

{auth_id}

numbers

{e164}

assign-subaccount

Unassign DID (15-day cool-off enforced)

curl --request DELETE \
  --url https://api.vobiz.ai/api/v1/account/{auth_id}/numbers/{e164}/assign-subaccount \
  --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}/assign-subaccount"

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}/assign-subaccount', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "did_cool_off_in_effect",
  "cool_off_until": "2026-06-09T10:00:00Z",
  "cool_off_remaining_seconds": 1209600
}

Moves a DID back to the parent account’s pool from a sub-account.

Authenticate with X-Auth-ID / X-Auth-Token (the parent account’s credentials).

Path casing: this endpoint uses lowercase /account/ and the singular assign-subaccount segment (the same path as the assign call, with DELETE). The other number endpoints use capital-A /Account/. Copy it verbatim or you will get a 404.

URL-encode the number. Replace the + in the E.164 path segment with %2B (e.g. %2B919876543210).

Path parameters

auth_id - the parent (MA_) account’s Auth ID.
e164 - the DID in E.164 format, URL-encoded (%2B for +).

Query parameters

Field	Type	Required	Description
`force`	boolean	No	Admin-only cool-off bypass. Requires an admin-role account; writes a `did_assignment_audit` row.

Response

On success the DID returns to the parent pool and the endpoint responds with 200 or 204 (no body).

15-day cool-off

To prevent a number that was actively used by one customer from being reassigned to another too quickly, unassignment enforces a 15-day cool-off:

Situation	Behavior
DID had a call within the last 15 days	Rejected with `409` and `did_cool_off_in_effect`.
DID never used (`last_call_at` is `NULL`)	Moves back to the parent pool immediately.

The 409 response tells you exactly how long is left:

{
  "error": "did_cool_off_in_effect",
  "cool_off_until": "2026-06-09T10:00:00Z",
  "cool_off_remaining_seconds": 1209600
}

Admin bypass

Admins can override the cool-off with the force=true query parameter:

curl -X DELETE \
  "https://api.vobiz.ai/api/v1/account/{auth_id}/numbers/%2B919876543210/assign-subaccount?force=true" \
  -H "X-Auth-ID: {admin_auth_id}" \
  -H "X-Auth-Token: {admin_auth_token}"

force=true requires an admin-role account (enforced at the gateway) and writes a did_assignment_audit row. A non-admin account using force=true is rejected with 403.

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 number in E.164, URL-encoded (use %2B instead of +).

Example:

"%2B919876543210"

Query Parameters

force

boolean

Admin-only cool-off bypass. Requires an admin-role account (enforced at the gateway) and writes a did_assignment_audit row.

Example:

true

Response

DID moved back to the parent pool

Unassign DID (15-day cool-off enforced)

curl --request DELETE \
  --url https://api.vobiz.ai/api/v1/account/{auth_id}/numbers/{e164}/assign-subaccount \
  --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}/assign-subaccount"

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}/assign-subaccount', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "api_id": "<string>",
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "did_cool_off_in_effect",
  "cool_off_until": "2026-06-09T10:00:00Z",
  "cool_off_remaining_seconds": 1209600
}

​Path parameters

​Query parameters

​Response

​15-day cool-off

​Admin bypass

Authorizations

Path Parameters

Query Parameters

Response

Path parameters

Query parameters

Response

15-day cool-off

Admin bypass