Release Phone Number - Burki Voice AI Docs

This endpoint allows you to release (delete) a phone number from your Twilio or Telnyx account, making it available for others to purchase. The number is immediately removed from your account and all associated configurations are cleaned up.

How It Works

Provider Detection: The system automatically detects which provider owns the number
Account Removal: The number is released from your telephony provider account
Database Cleanup: The number is removed from your organization’s inventory
Immediate Effect: The number stops receiving calls and messages instantly

Permanent Action: Once released, a phone number cannot be recovered. The number becomes available for others to purchase and you cannot guarantee getting it back.

Request Body

The request body is a JSON object containing release details.

phone_number (string, required): The phone number to release in E.164 format
provider (string, optional): Provider to use ("twilio" or "telnyx"). Auto-detected if not provided

Request

{
  "phone_number": "+14155551234",
  "provider": "telnyx"
}

Auto-Detection Example

Request

{
  "phone_number": "+14155551234"
}

Provider Auto-Detection: If you don’t specify a provider, the system will automatically detect which provider owns the number based on your database records.

Response

A successful request returns a 200 OK status with release confirmation.

Response

{
  "success": true,
  "phone_number": "+14155551234",
  "provider": "telnyx",
  "message": "Successfully released phone number +14155551234 from telnyx"
}

Response Fields

success (boolean): Whether the release completed successfully
phone_number (string): The released phone number
provider (string): Provider from which the number was released
message (string): Human-readable confirmation message

Error Responses

400 Bad Request

Returned when the request contains invalid data.

{
  "detail": "Provider must be 'twilio' or 'telnyx'"
}

Common causes:

Invalid provider value
Invalid phone number format
Number not in E.164 format

404 Not Found

Returned when the phone number is not found.

{
  "detail": "Phone number +14155551234 not found in database"
}

This occurs when:

Number doesn’t exist in your account
Number was never purchased through Burki
Number already released

500 Internal Server Error

Returned when the release fails at the provider level.

{
  "detail": "Failed to release phone number from telnyx"
}

Common causes:

Provider API error
Network connectivity issues
Invalid provider credentials
Number has active calls/usage

Release Workflow

Standard Release Process

# 1. List your current numbers (optional)
curl -X GET "https://api.burki.dev/organization/phonenumbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Release a specific number
curl -X POST "https://api.burki.dev/phone-numbers/release" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234"
  }'

# 3. Number is immediately unavailable

Bulk Release Process

# Release multiple numbers
for number in "+14155551234" "+14155551235" "+14155551236"; do
  curl -X POST "https://api.burki.dev/phone-numbers/release" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"phone_number\": \"$number\"}"
done

Use Cases

Cost Optimization

Release unused numbers to reduce monthly costs:

{
  "phone_number": "+14155551234"
}

Account Cleanup

Remove test or temporary numbers:

{
  "phone_number": "+18005551234",
  "provider": "twilio"
}

Geographic Reorganization

Release numbers when closing regional offices:

{
  "phone_number": "+12125551234"
}

Provider Migration

Release numbers before switching providers:

{
  "phone_number": "+14155551234",
  "provider": "twilio"
}

Provider Behavior

Twilio Release

Immediate Deactivation: Number stops working instantly
Billing: Pro-rated refund may apply (check Twilio terms)
Reactivation: Number returns to Twilio’s available pool
Dependencies: All webhooks and configurations are removed

Telnyx Release

Immediate Deactivation: Number stops working instantly
Billing: Check Telnyx terms for refund policies
Reactivation: Number returns to available inventory
Order Status: Associated orders marked as released

Safety Considerations

Pre-Release Checklist

Before releasing a number, ensure:

No Active Calls: Number isn’t currently handling calls
No Dependencies: No critical integrations depend on this number
Customer Communication: Customers are notified of number changes
Documentation Updated: Internal docs reflect the change
Backup Plan: Alternative contact methods are available

Impact Assessment

Releasing a number affects:

Incoming Calls: All incoming calls will fail
SMS Messages: SMS/MMS will not be delivered
Assistant Assignment: Associated assistant becomes unreachable
Customer Experience: Customers lose ability to contact you

Integration Examples

Node.js

const axios = require('axios');

async function releasePhoneNumber(phoneNumber, provider = null) {
  try {
    const requestData = { phone_number: phoneNumber };
    if (provider) {
      requestData.provider = provider;
    }

    const response = await axios.post('https://api.burki.dev/phone-numbers/release', requestData, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    console.log(`Successfully released ${phoneNumber} from ${response.data.provider}`);
    return response.data;
  } catch (error) {
    console.error('Release failed:', error.response.data);
    throw error;
  }
}

// Usage with auto-detection
await releasePhoneNumber('+14155551234');

// Usage with explicit provider
await releasePhoneNumber('+14155551234', 'telnyx');

Python

import requests

def release_phone_number(phone_number, provider=None):
    url = "https://api.burki.dev/phone-numbers/release"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {"phone_number": phone_number}
    if provider:
        payload["provider"] = provider
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Release failed: {response.json()['detail']}")

# Usage examples
result = release_phone_number("+14155551234")  # Auto-detect provider
result = release_phone_number("+14155551234", "telnyx")  # Explicit provider

PHP

<?php
function releasePhoneNumber($phoneNumber, $provider = null) {
    $url = 'https://api.burki.dev/phone-numbers/release';
    $headers = [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ];
    
    $data = ['phone_number' => $phoneNumber];
    if ($provider) {
        $data['provider'] = $provider;
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Release failed: " . $response);
    }
}

// Usage
$result = releasePhoneNumber('+14155551234');
?>

Batch Operations

Release Multiple Numbers

async function releaseMultipleNumbers(phoneNumbers) {
  const results = [];
  
  for (const phoneNumber of phoneNumbers) {
    try {
      const result = await releasePhoneNumber(phoneNumber);
      results.push({ phoneNumber, success: true, result });
    } catch (error) {
      results.push({ phoneNumber, success: false, error: error.message });
    }
  }
  
  return results;
}

// Usage
const numbersToRelease = ['+14155551234', '+14155551235', '+14155551236'];
const results = await releaseMultipleNumbers(numbersToRelease);

Conditional Release

def release_unused_numbers(unused_threshold_days=30):
    """Release numbers that haven't been used for calls in X days"""
    
    # Get list of numbers and their last usage
    numbers = get_phone_number_usage()
    
    for number_info in numbers:
        if number_info['days_since_last_call'] > unused_threshold_days:
            try:
                result = release_phone_number(number_info['phone_number'])
                print(f"Released unused number: {number_info['phone_number']}")
            except Exception as e:
                print(f"Failed to release {number_info['phone_number']}: {e}")

Best Practices

Planning and Preparation

Audit First: Review which numbers are actually needed
Usage Analysis: Check call/SMS volume before releasing
Customer Impact: Assess impact on customer communications
Gradual Release: Release numbers in phases, not all at once

Error Handling

async function safeRelease(phoneNumber) {
  try {
    // Check if number has recent activity
    const usage = await checkNumberUsage(phoneNumber);
    if (usage.recentCalls > 0) {
      throw new Error('Number has recent activity, release cancelled');
    }
    
    return await releasePhoneNumber(phoneNumber);
  } catch (error) {
    console.error(`Failed to release ${phoneNumber}:`, error.message);
    // Log to monitoring system
    // Send alert to admin
    throw error;
  }
}

Cost Management

Regular Audits: Monthly review of number usage
Automated Cleanup: Script to release unused numbers
Approval Process: Require approval for number releases
Recovery Planning: Consider number porting instead of release

Documentation

Always document releases:

Which numbers were released
Reason for release
Date and time
Impact assessment
Rollback plan (if applicable)

Troubleshooting

Common Issues

Issue	Cause	Solution
”Number not found”	Number not in account	Verify number ownership
”Release failed”	Provider API error	Check provider status
”Active usage”	Number currently in use	Wait for calls to complete
”Permission denied”	Insufficient privileges	Check API key permissions

Recovery Options

If you accidentally release a critical number:

Immediate Search: Search for the number in available pools
Quick Purchase: Purchase it back if still available
Alternative Numbers: Find similar numbers in the same area
Customer Communication: Notify customers of temporary number changes

Monitoring

Set up monitoring for:

Number release events
Failed release attempts
Usage patterns before release
Customer impact metrics

Best Practice: Always test the release process with non-critical numbers first to understand the full impact and timing.

API Documentation

Assistants

Assistant Phone Numbers

Assistant Documents (RAG)

Calls

Messaging

Phone Number Management

Call Data

Organization

Webhooks & System

WebSockets

​How It Works

​Request Body

​Auto-Detection Example

​Response

​Response Fields

​Error Responses

​400 Bad Request

​404 Not Found

​500 Internal Server Error

​Release Workflow

​Standard Release Process

​Bulk Release Process

​Use Cases

​Cost Optimization

​Account Cleanup

​Geographic Reorganization

​Provider Migration

​Provider Behavior

​Twilio Release

​Telnyx Release

​Safety Considerations

​Pre-Release Checklist

​Impact Assessment

​Integration Examples

​Node.js

​Python

​PHP

​Batch Operations

​Release Multiple Numbers

​Conditional Release

​Best Practices

​Planning and Preparation

​Error Handling

​Cost Management

​Documentation

​Troubleshooting

​Common Issues

​Recovery Options

​Monitoring

How It Works

Request Body

Auto-Detection Example

Response

Response Fields

Error Responses

400 Bad Request

404 Not Found

500 Internal Server Error

Release Workflow

Standard Release Process

Bulk Release Process

Use Cases

Cost Optimization

Account Cleanup

Geographic Reorganization

Provider Migration

Provider Behavior

Twilio Release

Telnyx Release

Safety Considerations

Pre-Release Checklist

Impact Assessment

Integration Examples

Node.js

Python

PHP

Batch Operations

Release Multiple Numbers

Conditional Release

Best Practices

Planning and Preparation

Error Handling

Cost Management

Documentation

Troubleshooting

Common Issues

Recovery Options

Monitoring