# Request 1: Get all phone numbers
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all phone numbers
const response = await fetch('https://app.talkover.ai/api/v1/phone-numbers', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"data": [
{
"id": "phone-uuid-1",
"number": "+1234567890",
"country_code": "US",
"formatted_number": "(123) 456-7890",
"international_number": "+1 234 567 890",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
},
{
"id": "phone-uuid-2",
"number": "+1987654321",
"country_code": "US",
"formatted_number": "(987) 654-3210",
"international_number": "+1 987 654 321",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
}
]
}
Voice Templates & Phone Numbers
List Phone Numbers
Retrieve a list of available phone numbers with filtering options
GET
/
api
/
v1
/
phone-numbers
# Request 1: Get all phone numbers
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all phone numbers
const response = await fetch('https://app.talkover.ai/api/v1/phone-numbers', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
{
"success": true,
"data": [
{
"id": "phone-uuid-1",
"number": "+1234567890",
"country_code": "US",
"formatted_number": "(123) 456-7890",
"international_number": "+1 234 567 890",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
},
{
"id": "phone-uuid-2",
"number": "+1987654321",
"country_code": "US",
"formatted_number": "(987) 654-3210",
"international_number": "+1 987 654 321",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
}
]
}
List Phone Numbers
Retrieve a list of available phone numbers with various filtering options. This endpoint returns phone numbers with their capabilities, pricing, and status information.Endpoint
GET /api/v1/phone-numbers
Request headers
string
required
Bearer token for authentication. Format:
Bearer talq_your_environment_token_hereQuery parameters
string
Filter by phone number type. Options:
voice, sms, whatsapp, mms, faxboolean
Filter by voice capability. Options:
true, falseboolean
Filter by WhatsApp capability. Options:
true, falsestring
Search by phone number or ID
Example requests
# Request 1: Get all phone numbers
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 1: Get all phone numbers
const response = await fetch('https://app.talkover.ai/api/v1/phone-numbers', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# Request 2: Get phone numbers with voice capability
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers?has_voice=true" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 2: Get phone numbers with voice capability
const response = await fetch('https://app.talkover.ai/api/v1/phone-numbers?has_voice=true', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
# Request 3: Search for a specific phone number
curl -X GET "https://app.talkover.ai/api/v1/phone-numbers?search=+1234567890" \
-H "Authorization: Bearer talq_your_environment_token_here"
// Request 3: Search for a specific phone number
const response = await fetch('https://app.talkover.ai/api/v1/phone-numbers?search=+1234567890', {
method: 'GET',
headers: {
'Authorization': 'Bearer talq_your_environment_token_here'
}
});
const result = await response.json();
console.log(result);
Response
Success Response (200 OK)
{
"success": true,
"data": [
{
"id": "phone-uuid-1",
"number": "+1234567890",
"country_code": "US",
"formatted_number": "(123) 456-7890",
"international_number": "+1 234 567 890",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
},
{
"id": "phone-uuid-2",
"number": "+1987654321",
"country_code": "US",
"formatted_number": "(987) 654-3210",
"international_number": "+1 987 654 321",
"type": "voice",
"has_voice": true,
"has_sms": true,
"has_mms": false,
"has_fax": false,
"has_whatsapp": false,
"current_status": "active",
"is_sandbox": false,
"current_price": 1.00,
"currency": "USD",
"renewal_date": "2024-02-15",
"auto_renewal": true,
"created_at": "2024-01-15T11:00:00Z",
"updated_at": "2024-01-15T11:00:00Z",
"monthly_renewal_cost": 1.00,
"days_until_monthly_renewal": 15,
"is_due_for_monthly_renewal": false,
}
]
}
Response fields
boolean
required
Indicates if the operation was successful.
array
required
Array of phone number objects.
Show Phone Number Object
Show Phone Number Object
string
required
Unique identifier for the phone number.
string
required
The phone number in E.164 format.
string
required
Country code of the phone number.
string
required
Formatted phone number for display.
string
required
International formatted phone number.
string
required
Type of phone number. Options:
voice, sms, whatsapp, mms, fax.boolean
required
Whether the phone number supports voice calls.
boolean
required
Whether the phone number supports SMS.
boolean
required
Whether the phone number supports MMS.
boolean
required
Whether the phone number supports fax.
boolean
required
Whether the phone number supports WhatsApp.
string
required
Current status of the phone number. Options:
active, inactive, pending, suspended.boolean
required
Whether this is a sandbox phone number.
number
required
Current price of the phone number.
string
required
Currency of the price.
string
required
Date when the phone number will be renewed.
boolean
required
Whether the phone number auto-renews.
string
required
ISO 8601 timestamp when the phone number was created.
string
required
ISO 8601 timestamp when the phone number was last updated.
number
required
Monthly renewal cost.
integer
required
Days until the next monthly renewal.
boolean
required
Whether the phone number is due for monthly renewal.
Error responses
401 Unauthorized
{
"success": false,
"message": "Unauthorized"
}
422 Validation Error
{
"success": false,
"message": "The given data was invalid.",
"errors": {
"type": [
"The selected type is invalid."
]
}
}
500 Server Error
{
"success": false,
"message": "Internal server error."
}
Error codes
| Code | Description | HTTP Status |
|---|---|---|
INVALID_TOKEN | Authentication token is invalid or missing | 401 |
VALIDATION_ERROR | Query parameter validation failed | 422 |
SERVER_ERROR | Internal server error occurred | 500 |
Important notes
Filtering capabilities. Use query parameters to filter phone numbers by type, and capabilities.
Pricing information. Each phone number includes current pricing and renewal information.
Status tracking. Monitor phone number status and renewal dates to avoid service interruptions.
Related endpoints
- List Voice Templates:
GET /api/v1/voice-templates - Generate Voice Template Demo:
GET /api/v1/voice-templates/{voiceTemplate}/demo
Was this page helpful?