Skip to main content
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"

{
  "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,
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.talkover.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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

​
Authorization
string
required
Bearer token for authentication. Format: Bearer talq_your_environment_token_here

​
Query Parameters

​
type
string
Filter by phone number type. Options: voice, sms, whatsapp, mms, fax
​
has_voice
boolean
Filter by voice capability. Options: true, false
​
has_whatsapp
boolean
Filter by WhatsApp capability. Options: true, false
​
search
string
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 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 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"

​
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

​
success
boolean
required
Indicates if the operation was successful.
​
data
array
required
Array of phone number objects.

​
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

CodeDescriptionHTTP Status
INVALID_TOKENAuthentication token is invalid or missing401
VALIDATION_ERRORQuery parameter validation failed422
SERVER_ERRORInternal server error occurred500

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

​
Best Practices

  1. Filter by capabilities - Use has_voice, has_sms, etc. to find phone numbers with specific capabilities
  2. Monitor renewals - Check is_due_for_monthly_renewal to avoid service interruptions
  3. Use search - Use the search parameter to find specific phone numbers quickly
  4. Check status - Always verify current_status before using a phone number
  5. Consider pricing - Compare current_price and monthly_renewal_cost when selecting phone numbers
  • List Voice Templates: GET /api/v1/voice-templates
  • Generate Voice Template Demo: GET /api/v1/voice-templates/{voiceTemplate}/demo