Phone Number Management

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')}")

curl -X POST "https://dev.voice.ai/api/v1/agent/search-phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "country_code": "US",
    "area_code": "415"
  }'

const response = await fetch('https://dev.voice.ai/api/v1/agent/search-phone-numbers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ country_code: 'US', area_code: '415' })
});

const data = await response.json();
console.log(`Found ${data.results.length} available numbers`);
data.results.slice(0, 5).forEach((num: any) => {
  console.log(`  ${num.phone_number} - ${num.locality || 'N/A'}, ${num.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']}")

curl -X POST "https://dev.voice.ai/api/v1/agent/select-phone-number" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551001"
  }'

const response = await fetch('https://dev.voice.ai/api/v1/agent/select-phone-number', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ phone_number: '+14155551001' })
});

const data = await response.json();
console.log(`Selected: ${data.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)

# Update agent with phone number (agent must be paused first)
curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X PUT "https://dev.voice.ai/api/v1/agent/{agent_id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "phone_number": "+14155551001"
    }
  }'

curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/deploy" \
  -H "Authorization: Bearer YOUR_API_KEY"

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

// Option 1: Include phone_number when creating agent
await fetch('https://dev.voice.ai/api/v1/agent/', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'My Agent',
    config: { prompt: 'You are a helpful assistant.', phone_number: '+14155551001' }
  })
});

// Option 2: Update existing agent (must pause first)
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/pause`, { method: 'POST', headers });
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}`, {
  method: 'PUT',
  headers,
  body: JSON.stringify({ config: { phone_number: '+14155551001' } })
});
await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/deploy`, { method: 'POST', 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']}")

# Pause agent first
curl -X POST "https://dev.voice.ai/api/v1/agent/{agent_id}/pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Release phone number
curl -X POST "https://dev.voice.ai/api/v1/agent/release-phone-number" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551001"
  }'

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

await fetch(`https://dev.voice.ai/api/v1/agent/${agentId}/pause`, { method: 'POST', headers });

const response = await fetch('https://dev.voice.ai/api/v1/agent/release-phone-number', {
  method: 'POST',
  headers,
  body: JSON.stringify({ phone_number: '+14155551001' })
});

const data = await response.json();
console.log(`Released: ${data.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')}")

curl -X GET "https://dev.voice.ai/api/v1/agent/phone-numbers" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch('https://dev.voice.ai/api/v1/agent/phone-numbers', {
  method: 'GET',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

const data = await response.json();
data.phone_numbers.forEach((num: any) => {
  console.log(`${num.phone_number} - ${num.status} - ${num.assigned_to_agent_name || 'Unassigned'}`);
});

Next Steps

Agent Quickstart - Create your first agent
API Reference - Complete API reference

Get started

Text-to-Speech

Voice Agents

SDKs

Search Phone Numbers

Select a Phone Number

Assign Phone Number to Agent

Release a Phone Number

List Your Phone Numbers

Next Steps

​Search Phone Numbers

​Select a Phone Number

​Assign Phone Number to Agent

​Release a Phone Number

​List Your Phone Numbers

​Next Steps

Search Phone Numbers

Select a Phone Number

Assign Phone Number to Agent

Release a Phone Number

List Your Phone Numbers

Next Steps