Skip to main content
Search, select, and manage phone numbers for your voice agents. Your plan includes a certain number of phone number slots that you can use.
Prerequisites: API key
Note: Phone numbers are currently only available for inbound calling. For outbound calling support, please contact us.
Phone Number Allocation: Your plan includes phone number slots. Search and select numbers to fill your available slots. Releasing a number frees up the slot.

​
Search Phone Numbers

Search for available phone numbers by country code and optional area code. See the Search Available Phone Numbers endpoint for details. 
import requests

response = requests.post(
    'https://dev.voice.ai/api/v1/agent/search-phone-numbers',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={'country_code': 'US', 'area_code': '415'}
)

data = response.json()
print(f"Found {len(data['results'])} available numbers")
for num in data['results'][:5]:
    print(f"  {num['phone_number']} - {num.get('locality', 'N/A')}, {num.get('region', 'N/A')}")
Response: 
{
  "results": [
    {
      "phone_number": "+14155551001",
      "locality": "San Francisco",
      "region": "CA",
      "country_code": "US"
    }
  ],
  "total_results": 1
}

​
Select a Phone Number

Select a phone number from the search results to claim one of your allocated slots. See the Select Phone Number endpoint for details. 
import requests

response = requests.post(
    'https://dev.voice.ai/api/v1/agent/select-phone-number',
    headers={'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'},
    json={'phone_number': '+14155551001'}
)

print(f"Selected: {response.json()['phone_number']}")
Rate Limiting: 2 selections per hour per IP address.

​
Assign Phone Number to Agent

Assign a selected phone number to an agent by including it in the agent configuration. 
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'}

# Option 1: Include phone_number when creating agent
requests.post(
    'https://dev.voice.ai/api/v1/agent/',
    headers=headers,
    json={'name': 'My Agent', 'config': {'prompt': 'You are a helpful assistant.', 'phone_number': '+14155551001'}}
)

# Option 2: Update existing agent (must pause first)
requests.post(f'https://dev.voice.ai/api/v1/agent/{agent_id}/pause', headers=headers)
requests.put(
    f'https://dev.voice.ai/api/v1/agent/{agent_id}',
    headers=headers,
    json={'config': {'phone_number': '+14155551001'}}
)
requests.post(f'https://dev.voice.ai/api/v1/agent/{agent_id}/deploy', headers=headers)

​
Release a Phone Number

Release a phone number to free up the slot. The slot becomes available for selecting a different number. Note: You must pause any agents using the number before releasing it. See the Release Phone Number endpoint for details. 
import requests

headers = {'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json'}

requests.post(f'https://dev.voice.ai/api/v1/agent/{agent_id}/pause', headers=headers)
response = requests.post(
    'https://dev.voice.ai/api/v1/agent/release-phone-number',
    headers=headers,
    json={'phone_number': '+14155551001'}
)
print(f"Released: {response.json()['phone_number']}")

​
List Your Phone Numbers

Get all phone numbers you own, including their assignment status. See the List Phone Number Details and Get Available Phone Numbers endpoints for details. 
import requests

response = requests.get(
    'https://dev.voice.ai/api/v1/agent/phone-numbers',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

data = response.json()
for num in data['phone_numbers']:
    print(f"{num['phone_number']} - {num['status']} - {num.get('assigned_to_agent_name', 'Unassigned')}")

​
Next Steps