> ## Documentation Index
> Fetch the complete documentation index at: https://docs.burki.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Phone Numbers

> Search available Twilio or Telnyx phone numbers by country, area code, locality, region, pattern, provider, and result limit.

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

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

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

## 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"`

```json Request theme={null}
{
  "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.

```json Response theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "detail": "Internal error: Provider API unavailable"
}
```

## Search Examples

### Basic Area Code Search

Search for numbers in the 415 area code:

```json theme={null}
{
  "area_code": "415",
  "provider": "telnyx",
  "limit": 10
}
```

### Location-Based Search

Find numbers in a specific city:

```json theme={null}
{
  "locality": "New York",
  "region": "NY",
  "country_code": "US",
  "provider": "twilio"
}
```

### Pattern-Based Search

Search for numbers containing specific digits:

```json theme={null}
{
  "contains": "777",
  "area_code": "212",
  "provider": "telnyx"
}
```

### International Search

Search for numbers in other countries:

```json theme={null}
{
  "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

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

```bash theme={null}
# 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:

```json theme={null}
{
  "contains": "SALE",
  "area_code": "800",
  "provider": "telnyx"
}
```

### Local Presence

Establish local presence in multiple markets:

```json theme={null}
{
  "locality": "Chicago",
  "region": "IL",
  "limit": 5,
  "provider": "twilio"
}
```

### Toll-Free Numbers

Search for toll-free numbers:

```json theme={null}
{
  "area_code": "800",
  "country_code": "US",
  "provider": "telnyx"
}
```

## Integration Examples

### Node.js

```javascript theme={null}
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

```python theme={null}
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 theme={null}
<?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

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

### Performance Tips

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

### Error Handling

Always implement proper error handling for provider outages:

```javascript theme={null}
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');
}
```

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


## OpenAPI

````yaml POST /api/v1/phone-numbers/search
openapi: 3.1.0
info:
  title: Burki
  description: A system that uses AI to answer customer Calls.
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/phone-numbers/search:
    post:
      summary: Search Phone Numbers
      description: >-
        Search for available phone numbers for purchase.


        This endpoint allows you to search for available phone numbers from
        Twilio or Telnyx or Vonage

        based on various criteria like area code, location, or number patterns.


        Args:
            search_data: Search criteria including country, area code, provider, etc.

        Returns:
            SearchPhoneNumbersResponse: List of available numbers with pricing and capabilities
      operationId: search_phone_numbers_api_v1_phone_numbers_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchPhoneNumbersRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchPhoneNumbersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    SearchPhoneNumbersRequest:
      properties:
        country_code:
          type: string
          title: Country Code
          description: Country code (e.g., US, GB)
          default: US
        area_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Area Code
          description: Area code to search in
        contains:
          anyOf:
            - type: string
            - type: 'null'
          title: Contains
          description: Pattern the number should contain
        locality:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality
          description: City/locality to search in
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: State/region to search in
        limit:
          type: integer
          maximum: 50
          minimum: 1
          title: Limit
          description: Maximum number of results
          default: 10
        provider:
          type: string
          title: Provider
          description: Provider to search ('twilio', 'telnyx', or 'byo-sip-trunk')
          default: telnyx
      type: object
      title: SearchPhoneNumbersRequest
      description: Request model for searching available phone numbers.
    SearchPhoneNumbersResponse:
      properties:
        success:
          type: boolean
          title: Success
        numbers:
          items:
            $ref: '#/components/schemas/AvailablePhoneNumber'
          type: array
          title: Numbers
        total_found:
          type: integer
          title: Total Found
        provider:
          type: string
          title: Provider
      type: object
      required:
        - success
        - numbers
        - total_found
        - provider
      title: SearchPhoneNumbersResponse
      description: Response model for phone number search.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AvailablePhoneNumber:
      properties:
        phone_number:
          type: string
          title: Phone Number
        friendly_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Friendly Name
        locality:
          anyOf:
            - type: string
            - type: 'null'
          title: Locality
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
        country_code:
          type: string
          title: Country Code
        capabilities:
          additionalProperties:
            type: boolean
          type: object
          title: Capabilities
        cost:
          anyOf:
            - type: string
            - type: 'null'
          title: Cost
        setup_cost:
          anyOf:
            - type: string
            - type: 'null'
          title: Setup Cost
        provider:
          type: string
          title: Provider
      type: object
      required:
        - phone_number
        - country_code
        - capabilities
        - provider
      title: AvailablePhoneNumber
      description: Model for an available phone number.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````