> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Phone Numbers

> List all phone numbers in your account

## Request

Retrieve a list of all phone numbers associated with your account.

### Headers

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

### Query Parameters

<ParamField query="limit" type="integer" default="20">
  Number of phone numbers to return (1-100)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `active`, `pending`, `inactive`
</ParamField>

<ParamField query="country" type="string">
  Filter by country code (e.g., `US`, `GB`, `CA`)
</ParamField>

## Response

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

<ResponseField name="has_more" type="boolean">
  Whether there are more results available
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor for fetching the next page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of phone numbers
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.ringyo.ai/v1/phone-numbers?status=active" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.ringyo.ai/v1/phone-numbers?status=active',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.ringyo.ai/v1/phone-numbers',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'status': 'active'}
  )

  data = response.json()
  phone_numbers = data['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "data": [
      {
        "id": "pn_abc123",
        "phone_number": "+18005551234",
        "friendly_name": "Main Business Line",
        "country": "US",
        "region": "CA",
        "capabilities": {
          "voice": true,
          "sms": true
        },
        "status": "active",
        "default_agent_id": "agent_abc123",
        "created_at": "2024-01-10T08:00:00Z"
      },
      {
        "id": "pn_def456",
        "phone_number": "+14155559876",
        "friendly_name": "Sales Line",
        "country": "US",
        "region": "CA",
        "capabilities": {
          "voice": true,
          "sms": false
        },
        "status": "active",
        "default_agent_id": null,
        "created_at": "2024-01-12T10:30:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 2
  }
  ```
</ResponseExample>

## Phone Number Object

| Field              | Type   | Description                     |
| ------------------ | ------ | ------------------------------- |
| `id`               | string | Unique identifier               |
| `phone_number`     | string | E.164 formatted number          |
| `friendly_name`    | string | Display name                    |
| `country`          | string | Two-letter country code         |
| `region`           | string | State/region code               |
| `capabilities`     | object | Voice and SMS capabilities      |
| `status`           | string | `active`, `pending`, `inactive` |
| `default_agent_id` | string | Agent for incoming calls        |
| `created_at`       | string | ISO 8601 timestamp              |

## Error Codes

| Code              | Description                      |
| ----------------- | -------------------------------- |
| `invalid_cursor`  | The pagination cursor is invalid |
| `invalid_country` | Country code is not valid        |