Skip to main content
DELETE
/
v1
/
voice
/
phone-numbers
/
{phone_number}
Release Phone Number
curl --request DELETE \
  --url https://api.example.com/v1/voice/phone-numbers/{phone_number} \
  --header 'X-API-Key: <x-api-key>'
{
  "success": true,
  "phone_number": "<string>",
  "released_at": "<string>",
  "billing_stopped": true,
  "already_released": true,
  "message": "<string>",
  "powered_by": "<string>",
  "failed": "<string>"
}

​
Description

Releases a voice phone number from your organization. Upon success, the number is unlinked from Teli Voice, released back to the carrier, soft-deleted in Teli’s records, and excluded from all future billing cycles. Idempotent — if the number has already been released, a 200 is returned with already_released: true. Voice numbers only — this endpoint does not release SMS phone numbers. SMS numbers must be released through the SMS workflow.

​
Authentication

​
X-API-Key
string
required
Your Teli API key

​
Path Parameters

​
phone_number
string
required
Phone number in E.164 format (e.g., +13137316433)

​
Response Fields

​
success
boolean
true when the number was released on this request
​
phone_number
string
The released phone number (E.164)
​
released_at
string
ISO-8601 UTC timestamp when the number was released
​
billing_stopped
boolean
Always true on a successful release. Confirms no further billing cycles will be charged for this number.
​
already_released
boolean
Only present when the number was already released by a prior request. Returned with status 200 so the call can be safely retried.
​
message
string
Human-readable confirmation (e.g., “Phone number released. You will not be billed in the next cycle.”)
​
powered_by
string
Always returns “Teli”

​
Example Request

cURL
curl -X DELETE "https://api.teli.ai/v1/voice/phone-numbers/+13137316433" \
  -H "X-API-Key: YOUR_API_KEY"
JavaScript
const response = await fetch(
  `https://api.teli.ai/v1/voice/phone-numbers/${encodeURIComponent(phoneNumber)}`,
  {
    method: 'DELETE',
    headers: { 'X-API-Key': 'YOUR_API_KEY' }
  }
);

const data = await response.json();
if (data.success) {
  console.log(`Released ${data.phone_number} at ${data.released_at}`);
}
Python
import requests
from urllib.parse import quote

phone = "+13137316433"
response = requests.delete(
    f"https://api.teli.ai/v1/voice/phone-numbers/{quote(phone)}",
    headers={"X-API-Key": "YOUR_API_KEY"}
)

data = response.json()
print(data)

​
Example Responses

​
Success (first release)

200
{
  "success": true,
  "phone_number": "+13137316433",
  "released_at": "2026-04-22T18:11:27.014Z",
  "billing_stopped": true,
  "message": "Phone number released. You will not be billed in the next cycle.",
  "powered_by": "Teli"
}

​
Already released (idempotent retry)

200
{
  "already_released": true,
  "phone_number": "+13137316433",
  "released_at": "2026-04-22T18:11:27.014Z",
  "powered_by": "Teli"
}

​
Not a voice number

400
{
  "error": "This endpoint releases voice phone numbers only. SMS numbers must be released through the SMS workflow.",
  "powered_by": "Teli"
}

​
Not found / not owned by your tenant

404
{
  "error": "Phone number not found",
  "powered_by": "Teli"
}
For security, cross-tenant lookups also return 404. A 404 therefore means either “no such number exists” or “the number exists but belongs to a different tenant”.

​
Partial release failure

Returned when Teli Voice could not complete both the provider-unlink step and the carrier-release step. In this case the number has not been soft-deleted on Teli’s side and billing continues — retry the request.
502
{
  "error": "Upstream release failure: voice_provider",
  "phone_number": "+13137316433",
  "voice_provider_released": false,
  "voice_carrier_released": false,
  "failed": "voice_provider",
  "powered_by": "Teli"
}
​
failed
string
Which step failed: voice_provider or voice_carrier. Always retry the same DELETE call — the endpoint is idempotent.

​
State sync failure

Returned when the upstream release succeeded but Teli could not record the soft-delete locally. This is rare and indicates the operation needs manual reconciliation by Teli support.
500
{
  "error": "Release state sync failed — contact support",
  "phone_number": "+13137316433",
  "voice_provider_released": true,
  "voice_carrier_released": true,
  "powered_by": "Teli"
}

​
Behavior

  1. Tenant isolation — requests can only release numbers owned by the calling tenant. Numbers from other tenants return 404.
  2. Voice-only guard — SMS numbers are rejected with 400. Use the SMS release workflow for those.
  3. Idempotent — retrying a DELETE on an already-released number returns 200 with already_released: true. Safe to call repeatedly.
  4. Atomic at the release step — if either the provider-unlink or carrier-release step fails, the number is not marked released on Teli’s side. Billing continues until the retry succeeds.
  5. Billing stops immediately — once success: true is returned, no further weekly or monthly billing events are emitted for the number.
  6. Audit trail — every successful release is recorded in Teli’s usage logs with event type phone_number_released.

​
After Release

  • The number is removed from GET /v1/voice/phone-numbers by default.
  • The number is unlinked from any attached voice agents.
  • The number is released back to the carrier and may be re-provisioned by another customer after a cooldown period set by the carrier.
  • Call history for the released number is preserved and remains queryable.
  • POST /v1/voice/phone-numbers/create — provision a new voice number
  • GET /v1/voice/phone-numbers — list active numbers
  • POST /v1/voice/phone-numbers/{number}/update-agent — link a number to a voice agent