> ## 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 filtering options

# 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

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer talq_your_environment_token_here`
</ParamField>

## Query parameters

<ParamField query="type" type="string" required={false}>
  Filter by phone number type. Options: `voice`, `sms`, `whatsapp`, `mms`, `fax`
</ParamField>

<ParamField query="has_voice" type="boolean" required={false}>
  Filter by voice capability. Options: `true`, `false`
</ParamField>

<ParamField query="has_whatsapp" type="boolean" required={false}>
  Filter by WhatsApp capability. Options: `true`, `false`
</ParamField>

<ParamField query="search" type="string" required={false}>
  Search by phone number or ID
</ParamField>

## Example requests

<RequestExample>
  ```bash theme={null}
  # 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"
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

<RequestExample>
  ```bash theme={null}
  # 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"
  ```

  ```javascript theme={null}
  // 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);
  ```
</RequestExample>

## Response

### Success Response (200 OK)

<ResponseExample>
  ```json theme={null}
  {
    "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,
      }
    ]
  }
  ```
</ResponseExample>

### Response fields

<ResponseField name="success" type="boolean" required>
  Indicates if the operation was successful.
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of phone number objects.

  <Expandable title="Phone Number Object">
    <ResponseField name="id" type="string" required>
      Unique identifier for the phone number.
    </ResponseField>

    <ResponseField name="number" type="string" required>
      The phone number in E.164 format.
    </ResponseField>

    <ResponseField name="country_code" type="string" required>
      Country code of the phone number.
    </ResponseField>

    <ResponseField name="formatted_number" type="string" required>
      Formatted phone number for display.
    </ResponseField>

    <ResponseField name="international_number" type="string" required>
      International formatted phone number.
    </ResponseField>

    <ResponseField name="type" type="string" required>
      Type of phone number. Options: `voice`, `sms`, `whatsapp`, `mms`, `fax`.
    </ResponseField>

    <ResponseField name="has_voice" type="boolean" required>
      Whether the phone number supports voice calls.
    </ResponseField>

    <ResponseField name="has_sms" type="boolean" required>
      Whether the phone number supports SMS.
    </ResponseField>

    <ResponseField name="has_mms" type="boolean" required>
      Whether the phone number supports MMS.
    </ResponseField>

    <ResponseField name="has_fax" type="boolean" required>
      Whether the phone number supports fax.
    </ResponseField>

    <ResponseField name="has_whatsapp" type="boolean" required>
      Whether the phone number supports WhatsApp.
    </ResponseField>

    <ResponseField name="current_status" type="string" required>
      Current status of the phone number. Options: `active`, `inactive`, `pending`, `suspended`.
    </ResponseField>

    <ResponseField name="is_sandbox" type="boolean" required>
      Whether this is a sandbox phone number.
    </ResponseField>

    <ResponseField name="current_price" type="number" required>
      Current price of the phone number.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Currency of the price.
    </ResponseField>

    <ResponseField name="renewal_date" type="string" required>
      Date when the phone number will be renewed.
    </ResponseField>

    <ResponseField name="auto_renewal" type="boolean" required>
      Whether the phone number auto-renews.
    </ResponseField>

    <ResponseField name="created_at" type="string" required>
      ISO 8601 timestamp when the phone number was created.
    </ResponseField>

    <ResponseField name="updated_at" type="string" required>
      ISO 8601 timestamp when the phone number was last updated.
    </ResponseField>

    <ResponseField name="monthly_renewal_cost" type="number" required>
      Monthly renewal cost.
    </ResponseField>

    <ResponseField name="days_until_monthly_renewal" type="integer" required>
      Days until the next monthly renewal.
    </ResponseField>

    <ResponseField name="is_due_for_monthly_renewal" type="boolean" required>
      Whether the phone number is due for monthly renewal.
    </ResponseField>
  </Expandable>
</ResponseField>

## Error responses

### 401 Unauthorized

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Unauthorized"
  }
  ```
</ResponseExample>

### 422 Validation Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "The given data was invalid.",
    "errors": {

      "type": [
        "The selected type is invalid."
      ]
    }
  }
  ```
</ResponseExample>

### 500 Server Error

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "message": "Internal server error."
  }
  ```
</ResponseExample>

## 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

<Info>
  **Filtering capabilities.** Use query parameters to filter phone numbers by type, and capabilities.
</Info>

<Info>
  **Pricing information.** Each phone number includes current pricing and renewal information.
</Info>

<Info>
  **Status tracking.** Monitor phone number status and renewal dates to avoid service interruptions.
</Info>

## Related endpoints

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