Search Phone Numbers - Burki Voice AI Docs

This endpoint allows you to search for available phone numbers for purchase from Twilio or Telnyx. You can filter results by country, area code, location, or number patterns to find the perfect number for your assistant.

How It Works

Provider Selection: Choose between Twilio or Telnyx as your search provider
Filter Application: Apply location, pattern, or feature-based filters
Results with Pricing: Get available numbers with cost information and capabilities
Direct Purchase: Use the returned phone numbers in the purchase endpoint

Multi-Provider Comparison: Search both Twilio and Telnyx separately to compare pricing and availability across providers for the same region.

Request Body

The request body is a JSON object containing search criteria.

country_code (string, optional): Country code to search in. Defaults to "US"
area_code (string, optional): Specific area code to search within
contains (string, optional): Pattern or digits the number should contain
locality (string, optional): City or locality name to search in
region (string, optional): State or region to search within
limit (integer, optional): Maximum number of results (1-50). Defaults to 10
provider (string, optional): Provider to search ("twilio" or "telnyx"). Defaults to "telnyx"

Request

{
  "country_code": "US",
  "area_code": "415",
  "locality": "San Francisco",
  "region": "CA",
  "limit": 20,
  "provider": "telnyx"
}

Response

A successful request returns a 200 OK status with available phone numbers.

Response

{
  "success": true,
  "numbers": [
    {
      "phone_number": "+14155551234",
      "friendly_name": "+14155551234",
      "locality": "San Francisco",
      "region": "CA",
      "country_code": "US",
      "capabilities": {
        "voice": true,
        "sms": true,
        "mms": true,
        "fax": false
      },
      "cost": "$1.00",
      "setup_cost": "$0.00",
      "provider": "telnyx"
    }
  ],
  "total_found": 15,
  "provider": "telnyx"
}

Response Fields

success (boolean): Whether the search completed successfully
numbers (array): List of available phone numbers with details
- phone_number (string): The phone number in E.164 format
- friendly_name (string): Display name for the number
- locality (string): City/locality where the number is located
- region (string): State/region where the number is located
- country_code (string): Country code
- capabilities (object): Features supported by this number
  - voice (boolean): Supports voice calls
  - sms (boolean): Supports SMS messages
  - mms (boolean): Supports MMS messages
  - fax (boolean): Supports fax transmissions
- cost (string): Monthly cost for the number (Telnyx only)
- setup_cost (string): One-time setup fee (Telnyx only)
- provider (string): Provider name (“twilio” or “telnyx”)
total_found (integer): Total number of results found
provider (string): Provider used for the search

Error Responses

400 Bad Request

Returned when the request contains invalid parameters.

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

Common causes:

Invalid provider value
limit outside of 1-50 range
Invalid country code format

500 Internal Server Error

Returned when the provider API fails or is unavailable.

{
  "detail": "Internal error: Provider API unavailable"
}

Search Examples

Basic Area Code Search

Search for numbers in the 415 area code:

{
  "area_code": "415",
  "provider": "telnyx",
  "limit": 10
}

Location-Based Search

Find numbers in a specific city:

{
  "locality": "New York",
  "region": "NY",
  "country_code": "US",
  "provider": "twilio"
}

Pattern-Based Search

Search for numbers containing specific digits:

{
  "contains": "777",
  "area_code": "212",
  "provider": "telnyx"
}

International Search

Search for numbers in other countries:

{
  "country_code": "GB",
  "locality": "London",
  "provider": "telnyx",
  "limit": 5
}

Provider Comparison

Twilio vs Telnyx

Feature	Twilio	Telnyx
Search Filters	Area code, locality, region, contains	Area code, locality, region, contains
Pricing Info	Not included in search	Monthly + setup costs shown
Global Coverage	Provider-dependent and changes by product	Provider-dependent and changes by product
API Speed	Fast	Very fast
Features	Voice, SMS, MMS, Fax	Voice, SMS, MMS

Cost Optimization Tips

Compare Providers: Search both providers for the same criteria
Check Setup Fees: Telnyx shows setup costs upfront
Consider Features: Ensure the number supports required capabilities
Location Matters: Local numbers may have better rates

# Compare pricing between providers
curl -X POST "https://api.burki.dev/api/v1/phone-numbers/search" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415", "provider": "telnyx"}'

curl -X POST "https://api.burki.dev/api/v1/phone-numbers/search" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415", "provider": "twilio"}'

Use Cases

Sales Team Numbers

Search for memorable numbers for sales teams:

{
  "contains": "SALE",
  "area_code": "800",
  "provider": "telnyx"
}

Local Presence

Establish local presence in multiple markets:

{
  "locality": "Chicago",
  "region": "IL",
  "limit": 5,
  "provider": "twilio"
}

Toll-Free Numbers

Search for toll-free numbers:

{
  "area_code": "800",
  "country_code": "US",
  "provider": "telnyx"
}

Integration Examples

Node.js

const axios = require('axios');

async function searchPhoneNumbers(criteria) {
  try {
    const response = await axios.post('https://api.burki.dev/api/v1/phone-numbers/search', {
      ...criteria,
      provider: 'telnyx'
    }, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    return response.data.numbers;
  } catch (error) {
    console.error('Search failed:', error.response.data);
    throw error;
  }
}

// Usage
const numbers = await searchPhoneNumbers({
  area_code: '415',
  locality: 'San Francisco',
  limit: 10
});

Python

import requests

def search_phone_numbers(criteria, provider='telnyx'):
    url = "https://api.burki.dev/api/v1/phone-numbers/search"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    
    payload = {**criteria, "provider": provider}
    
    response = requests.post(url, json=payload, headers=headers)
    
    if response.status_code == 200:
        return response.json()['numbers']
    else:
        raise Exception(f"Search failed: {response.json()['detail']}")

# Usage
numbers = search_phone_numbers({
    'area_code': '415',
    'locality': 'San Francisco',
    'limit': 10
})

PHP

<?php
function searchPhoneNumbers($criteria, $provider = 'telnyx') {
    $url = 'https://api.burki.dev/api/v1/phone-numbers/search';
    $headers = [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json'
    ];
    
    $data = array_merge($criteria, ['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)['numbers'];
    } else {
        throw new Exception("Search failed: " . $response);
    }
}

// Usage
$numbers = searchPhoneNumbers([
    'area_code' => '415',
    'locality' => 'San Francisco',
    'limit' => 10
]);
?>

Best Practices

Search Strategy

Start Broad: Begin with area code only, then add filters
Multiple Searches: Try different combinations to find the best options
Provider Comparison: Always compare both Twilio and Telnyx
Capability Check: Verify the number supports your required features

Performance Tips

Reasonable Limits: Use appropriate limit values (10-20 for UI, 5 for automation)
Cache Results: Cache search results for a few minutes to avoid repeated calls
Parallel Searches: Search multiple providers simultaneously for comparison

Error Handling

Always implement proper error handling for provider outages:

async function robustSearch(criteria) {
  const providers = ['telnyx', 'twilio'];
  
  for (const provider of providers) {
    try {
      return await searchPhoneNumbers({...criteria, provider});
    } catch (error) {
      console.warn(`${provider} search failed, trying next provider`);
    }
  }
  
  throw new Error('All providers failed');
}

Rate Limits: Search requests are subject to rate limits. For high-volume applications, implement appropriate throttling and retry logic.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request model for searching available phone numbers.

country_code

string

default:US

Country code (e.g., US, GB)

area_code

string | null

Area code to search in

contains

string | null

Pattern the number should contain

locality

string | null

City/locality to search in

region

string | null

State/region to search in

limit

integer

default:10

Maximum number of results

Required range: 1 <= x <= 50

provider

string

default:telnyx

Provider to search ('twilio', 'telnyx', or 'byo-sip-trunk')

Response

Successful Response

Response model for phone number search.

success

boolean

required

numbers

AvailablePhoneNumber · object[]

required

Show child attributes

total_found

integer

required

provider

string

required

​How It Works

​Request Body

​Response

​Response Fields

​Error Responses

​400 Bad Request

​500 Internal Server Error

​Search Examples

​Basic Area Code Search

​Location-Based Search

​Pattern-Based Search

​International Search

​Provider Comparison

​Twilio vs Telnyx

​Cost Optimization Tips

​Use Cases

​Sales Team Numbers

​Local Presence

​Toll-Free Numbers

​Integration Examples

​Node.js

​Python

​PHP

​Best Practices

​Search Strategy

​Performance Tips

​Error Handling

Authorizations

Body

Response

How It Works

Request Body

Response

Response Fields

Error Responses

400 Bad Request

500 Internal Server Error

Search Examples

Basic Area Code Search

Location-Based Search

Pattern-Based Search

International Search

Provider Comparison

Twilio vs Telnyx

Cost Optimization Tips

Use Cases

Sales Team Numbers

Local Presence

Toll-Free Numbers

Integration Examples

Node.js

Python

PHP

Best Practices

Search Strategy

Performance Tips

Error Handling