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. 
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. 
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. 
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. 
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