# 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,
    }
  ]
}

GET

api

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

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

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.

Show Phone Number Object

string

required

Unique identifier for the phone number.

number

string

required

The phone number in E.164 format.

country_code

string

required

Country code of the phone number.

formatted_number

string

required

Formatted phone number for display.

international_number

string

required

International formatted phone number.

type

string

required

Type of phone number. Options: voice, sms, whatsapp, mms, fax.

has_voice

boolean

required

Whether the phone number supports voice calls.

has_sms

boolean

required

Whether the phone number supports SMS.

has_mms

boolean

required

Whether the phone number supports MMS.

has_fax

boolean

required

Whether the phone number supports fax.

has_whatsapp

boolean

required

Whether the phone number supports WhatsApp.

current_status

string

required

Current status of the phone number. Options: active, inactive, pending, suspended.

is_sandbox

boolean

required

Whether this is a sandbox phone number.

current_price

number

required

Current price of the phone number.

currency

string

required

Currency of the price.

renewal_date

string

required

Date when the phone number will be renewed.

auto_renewal

boolean

required

Whether the phone number auto-renews.

created_at

string

required

ISO 8601 timestamp when the phone number was created.

updated_at

string

required

ISO 8601 timestamp when the phone number was last updated.

monthly_renewal_cost

number

required

Monthly renewal cost.

days_until_monthly_renewal

integer

required

Days until the next monthly renewal.

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

List Voice Templates: GET /api/v1/voice-templates
Generate Voice Template Demo: GET /api/v1/voice-templates/{voiceTemplate}/demo

Generate Voice Template Demo List Release Requests

​List Phone Numbers

​Endpoint

​Request headers

​Query parameters

​Example requests

​Response

​Success Response (200 OK)

​Response fields

​Error responses

​401 Unauthorized

​422 Validation Error

​500 Server Error

​Error codes

​Important notes

​Related endpoints

List Phone Numbers

Endpoint

Request headers

Query parameters

Example requests

Response

Success Response (200 OK)

Response fields

Error responses

401 Unauthorized

422 Validation Error

500 Server Error

Error codes

Important notes

Related endpoints