Skip to main content
POST
/
v1
/
voice
/
phone-numbers
/
create
Create Phone Number
curl --request POST \
  --url https://api.example.com/v1/voice/phone-numbers/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <x-api-key>' \
  --data '
{
  "area_code": "<string>",
  "user_id": "<string>",
  "organization_id": "<string>",
  "tenant_id": "<string>",
  "nickname": "<string>"
}
'
{
  "success": true,
  "phone_number": "<string>",
  "phone_number_pretty": "<string>",
  "area_code": "<string>",
  "phone_number_type": "<string>",
  "powered_by": "<string>"
}

​
Description

Provisions a new voice-enabled phone number for your organization. Phone numbers are provisioned through Teli Voice and can be used for voice campaigns and inbound/outbound calls. Ownership: Phone numbers are owned by individual users (user-level ownership).

​
Authentication

​
X-API-Key
string
required
Your Teli API key

​
Request Body

​
area_code
string
required
3-digit area code for the phone number (e.g., “313”, “415”, “212”)
​
user_id
string
required
User unique_id who will own this phone number
​
organization_id
string
required
Organization unique_id
​
tenant_id
string
required
Tenant identifier for multi-tenant isolation
​
nickname
string
Optional friendly name for the phone numberExample: "Main Sales Line"

​
Response Fields

​
success
boolean
Whether the phone number was provisioned successfully
​
phone_number
string
Phone number in E.164 format (e.g., “+13137316433”)
​
phone_number_pretty
string
Formatted phone number (e.g., “+1 313-731-6433”)
​
area_code
string
Area code (3 digits)
​
phone_number_type
string
Phone number type/provider identifier (e.g., “teli-voice”)
​
powered_by
string
Always returns “Teli”

​
Example Request

cURL
curl -X POST "https://api.teli.ai/v1/voice/phone-numbers/create" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "313",
    "user_id": "1762896366429x599348279945132448",
    "organization_id": "1762896364768x389173798861431550",
    "tenant_id": "your_tenant"
  }'
JavaScript
const response = await fetch('https://api.teli.ai/v1/voice/phone-numbers/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    area_code: '313',
    user_id: userId,
    organization_id: orgId,
    tenant_id: tenantId
  })
});

const data = await response.json();
console.log(data.phone_number);
Python
import requests

response = requests.post(
    'https://api.teli.ai/v1/voice/phone-numbers/create',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={
        'area_code': '313',
        'user_id': user_id,
        'organization_id': org_id,
        'tenant_id': tenant_id
    }
)

data = response.json()
print(data['phone_number'])

​
Example Response

200
{
  "success": true,
  "phone_number": "+13137316433",
  "phone_number_pretty": "+1 313-731-6433",
  "area_code": "313",
  "phone_number_type": "teli-voice",
  "powered_by": "Teli"
}
400
{
  "error": "area_code and user_id required",
  "success": false,
  "powered_by": "Teli"
}
500
{
  "error": "Failed to provision phone number",
  "message": "No numbers available in area code 999",
  "success": false,
  "powered_by": "Teli"
}

​
Ownership Model

  • User-Level: Phone numbers are owned by individual users
  • Organization Visibility: Admin users can see all organization phone numbers
  • Regular Users: See only their own phone numbers

​
After Provisioning

Once provisioned, the phone number will:
  1. Appear in GET /v1/voice/phone-numbers (user-level or org-level for admins)
  2. Be available for use in voice campaigns
  3. Be available for linking to voice agents (inbound/outbound)

​
Agent Linking

After creating a phone number, you can link it to voice agents: 
POST /v1/voice/phone-numbers/{number}/update-agent
{
  "outbound_agent_id": "74014854-b110-46c8-b037-18f0149baae6",
  "inbound_agent_id": "c43fc766-9e49-46aa-9a46-325c8c894a58"
}

​
Notes

  • Phone numbers are provisioned through Teli Voice infrastructure
  • Provisioning is instant (no approval required)
  • Area codes must be valid US/Canada area codes
  • Each user can own multiple phone numbers
  • Phone numbers can be released via the dashboard
  • Monthly billing applies per phone number
  • GET /v1/voice/phone-numbers - List phone numbers
  • POST /v1/voice/phone-numbers/{number}/update-agent - Link to agent
  • POST /v1/voice/campaigns - Create campaign with phone number
  • GET /v1/voice/calls - View call history