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

# Get Telephony Numbers

> Retrieve list of all telephony numbers

<ResponseExample>
  ```json Success Response (200) — With Org-Handle theme={null}
  {
    "status_code": 200,
    "message": "Telephony numbers fetched successfully.",
    "data": [
      {
        "id": 501,
        "number": "+15551234567",
        "state": "ASSIGNED",
        "active": true
      },
      {
        "id": 502,
        "number": "+15559876543",
        "state": "NOT_ASSIGNED",
        "active": true
      }
    ]
  }
  ```

  ```json Success Response (200) — Without Org-Handle theme={null}
  {
    "status_code": 200,
    "message": "Telephony numbers fetched successfully.",
    "data": [
      {
        "id": 502,
        "number": "+15559876543",
        "state": "NOT_ASSIGNED",
        "active": true
      }
    ]
  }
  ```

  ```json Error Response (401) theme={null}
  {
    "status_code": 401,
    "message": "Authentication credentials were not provided."
  }
  ```
</ResponseExample>

# Get Telephony Numbers

Retrieve a list of telephony numbers. Behavior depends on the `Org-Handle` header:

* **With Org-Handle** — returns your organization's own numbers (any state) plus the shared
  unassigned pool (`NOT_ASSIGNED`).
* **Without Org-Handle** — returns only the shared unassigned pool.

<Note>
  **Prerequisites:** Make sure you have your API Token ready. See [Authentication](/api/get-started/authentication) for details.
</Note>

### Headers

| Name          | Type   | Required | Description                     |
| ------------- | ------ | -------- | ------------------------------- |
| Authorization | string | Yes      | API Key format: `Token <token>` |
| Org-Handle    | string | No       | Organization domain handle      |

<Note>
  You can get the `Org-Handle` by hitting the [Get All Organizations](/api/space/organizations#get-all-organizations) API. The `domain_handle` field in the response is your Org-Handle.
</Note>

### Response Fields

| Field        | Type    | Description             |
| ------------ | ------- | ----------------------- |
| status\_code | integer | HTTP status code        |
| message      | string  | Response message        |
| data         | array   | Array of number objects |

### Number Object Fields

| Field  | Type    | Description                                 |
| ------ | ------- | ------------------------------------------- |
| id     | integer | Unique number id (use this in attach calls) |
| number | string  | Phone number in E.164 format                |
| state  | string  | `NOT_ASSIGNED` or `ASSIGNED`                |
| active | boolean | Whether the number is usable                |

## Common Error Codes

| Status Code | Description                                 |
| ----------- | ------------------------------------------- |
| 200         | Success - Numbers fetched successfully      |
| 401         | Unauthorized - Invalid or missing API token |
| 500         | Internal Server Error - Server-side error   |

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const axios = require('axios');

  const headers = {
    'Authorization': 'Token your-api-token',
    'Org-Handle': 'your-org-handle'  // optional — omit for pool numbers only
  };

  // Get org numbers + pool numbers
  const getTelephonyNumbers = async () => {
    const response = await axios.get(
      'https://unpod.ai/api/v2/platform/telephony/numbers/',
      { headers }
    );
    const numbers = response.data.data;
    console.log(`Total numbers: ${numbers.length}`);
    numbers.forEach(num => {
      console.log(`${num.number} - ${num.state}`);
    });
    return numbers;
  };

  // Get only unassigned pool numbers (no Org-Handle)
  const getPoolNumbers = async () => {
    const response = await axios.get(
      'https://unpod.ai/api/v2/platform/telephony/numbers/',
      { headers: { 'Authorization': headers.Authorization } }
    );
    return response.data.data;
  };

  // Example usage
  getTelephonyNumbers();
  ```

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

  headers = {
      'Authorization': 'Token your-api-token',
      'Org-Handle': 'your-org-handle'  # optional — omit for pool numbers only
  }

  def get_telephony_numbers():
      """Get org numbers + pool numbers"""
      url = 'https://unpod.ai/api/v2/platform/telephony/numbers/'
      response = requests.get(url, headers=headers)
      data = response.json()
      numbers = data['data']
      print(f"Total numbers: {len(numbers)}")
      for num in numbers:
          print(f"{num['number']} - {num['state']}")
      return numbers

  def get_pool_numbers():
      """Get only unassigned pool numbers (no Org-Handle)"""
      pool_headers = {k: v for k, v in headers.items() if k != 'Org-Handle'}
      url = 'https://unpod.ai/api/v2/platform/telephony/numbers/'
      response = requests.get(url, headers=pool_headers)
      return response.json()['data']

  # Example usage
  get_telephony_numbers()
  ```

  ```bash cURL theme={null}
  # With Org-Handle — org numbers + pool numbers
  curl -X GET "https://unpod.ai/api/v2/platform/telephony/numbers/" \
    -H "Authorization: Token your-api-token" \
    -H "Org-Handle: your-org-handle"

  # Without Org-Handle — pool numbers only
  curl -X GET "https://unpod.ai/api/v2/platform/telephony/numbers/" \
    -H "Authorization: Token your-api-token"
  ```
</CodeGroup>

## Best Practices

1. **Org Scoping**: Pass `Org-Handle` to see your org's numbers; omit it to see only pool numbers
2. **Number Assignment**: Use a number's `id` when attaching it to a [trunk](/telephony/trunks/attach-numbers)
3. **State Awareness**: Check `state` to know if a number is `NOT_ASSIGNED` (available) or `ASSIGNED` (in use)
4. **E.164 Format**: All numbers are returned in E.164 format — use this format consistently in all API calls
5. **Security**: Keep API tokens secure and rotate them regularly


## OpenAPI

````yaml GET /api/v2/platform/telephony/numbers/
openapi: 3.0.3
info:
  title: Unpod API
  description: REST API for Unpod Voice AI Platform
  version: 2.0.0
servers:
  - url: https://unpod.ai/
    description: QA
  - url: https://unpod.ai/
    description: Production
security: []
tags:
  - name: Organisation
  - name: Spaces
  - name: Agents
  - name: Tasks
  - name: Runs
  - name: Call Logs
  - name: Analytics
  - name: Providers
  - name: Bridges
  - name: Numbers
  - name: Trunks
  - name: Telephony
  - name: Billing
paths:
  /api/v2/platform/telephony/numbers/:
    get:
      tags:
        - Bridges
      summary: Get Telephony Numbers
      description: >
        List telephony numbers. With Org-Handle: org's own numbers (any state) +
        pool (NOT_ASSIGNED). Without Org-Handle: pool numbers only.
      operationId: getTelephonyNumbers
      parameters:
        - name: Org-Handle
          in: header
          required: false
          schema:
            type: string
          description: Organization domain handle. Omit to list pool numbers only.
      responses:
        '200':
          description: List of telephony numbers
          content:
            application/json:
              example:
                status_code: 200
                message: Telephony numbers fetched successfully.
                data:
                  - id: 501
                    number: '+15551234567'
                    state: ASSIGNED
                    active: true
                  - id: 502
                    number: '+15559876543'
                    state: NOT_ASSIGNED
                    active: true
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - TokenAuth: []
components:
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API token
      content:
        application/json:
          example:
            status_code: 401
            message: Authentication credentials were not provided.
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Format: Token <your-api-key>'

````