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

# List Phone Numbers

Retrieve all phone numbers associated with your organization.

## Overview

This endpoint returns a list of all phone numbers configured for your organization, including their status, provider information, and associated metadata.

## Request

### Headers

| Header      | Value        | Required |
| ----------- | ------------ | -------- |
| `x-api-key` | Your API key | Yes      |
| `accept`    | `*/*`        | No       |

### Example Request

```bash theme={null}
curl -X 'GET' \
  'https://api.callhq.ai/api/phone-numbers' \
  -H 'accept: */*' \
  -H 'x-api-key: your_api_key_here'
```

## Response

### Success Response (200)

Returns an array of phone number objects.

```json theme={null}
{
  "phoneNumbers": [
    {
      "id": "1dc31d3f-8e0f-47dd-bfbd-4ac05017b570",
      "accountId": "up-xx-xxxx",
      "did": "91xxxxxx3166",
      "domain": "sip-xx-xx.pliwo.tv",
      "provider": "pliwo",
      "externalId": "aexxxxxx-xxxxxxxx-xxxxxx34579",
      "status": true,
      "createdAt": "2025-07-18T06:52:25.000Z",
      "updatedAt": "2025-07-18T06:52:25.000Z",
      "organization": {
        "id": "e5xxxxxxb-65f7-46cd-b5c3-3bcxxxxx24e",
        "name": "YOUR ORG NAME"
      }
    }
  ]
}
```

### Response Schema

| Field               | Type              | Description                                 |
| ------------------- | ----------------- | ------------------------------------------- |
| `phoneNumbers`      | Array             | Array of phone number objects               |
| `id`                | String            | Unique identifier for the phone number      |
| `accountId`         | String            | Account identifier                          |
| `did`               | String            | Direct inward dialing number                |
| `domain`            | String            | SIP domain for the phone number             |
| `provider`          | String            | Phone number provider (e.g., pliwo, telnyx) |
| `externalId`        | String            | External identifier from the provider       |
| `status`            | Boolean           | Active status of the phone number           |
| `createdAt`         | String (ISO 8601) | Creation timestamp                          |
| `updatedAt`         | String (ISO 8601) | Last update timestamp                       |
| `organization.id`   | String            | Organization identifier                     |
| `organization.name` | String            | Organization name                           |

### Error Responses

| Status Code | Description                  |
| ----------- | ---------------------------- |
| 500         | Error fetching phone numbers |

## Use Cases

* **Phone Number Management**: View all available phone numbers for your organization
* **Provider Integration**: Check which phone number providers are configured
* **Status Monitoring**: Verify the active status of phone numbers
* **Organization Setup**: Review phone number configurations across different accounts

## Related Endpoints

* [Setup Inbound Agent](/api-reference/phone/setup-inbound-agent) - Route inbound calls to an assistant
* [Place Outbound Call](/api-reference/calls/place-outbound-call) - Use a phone number to make outbound calls
* [List Calls](/api-reference/calls/list-calls) - View call history for specific phone numbers


## OpenAPI

````yaml get /phone-numbers
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.callhq.ai/api
security:
  - apiKeyAuth: []
paths:
  /phone-numbers:
    get:
      tags:
        - Phone Numbers
      summary: List Phone Numbers
      responses:
        '200':
          description: List of phone numbers retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  phoneNumbers:
                    type: array
                    items:
                      $ref: '#/components/schemas/PhoneNumber'
        '500':
          description: Error fetching phone numbers.
      security:
        - apiKeyAuth: []
components:
  schemas:
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the phone number
        accountId:
          type: string
          description: Account identifier
        did:
          type: string
          description: Direct inward dialing number
        domain:
          type: string
          description: SIP domain for the phone number
        provider:
          type: string
          description: Phone number provider (e.g., unpod, viva)
        externalId:
          type: string
          description: External identifier from the provider
        status:
          type: boolean
          description: Active status of the phone number
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
        organization:
          type: object
          properties:
            id:
              type: string
              description: Organization identifier
            name:
              type: string
              description: Organization name
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````