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

# List Phone Numbers

> Lists active phone numbers assigned to the API key's company. Use the returned `id` when referencing a phone number in an agent configuration. ATS keys must supply the `companyId` query parameter.

Lists all active phone numbers assigned to the API key's company.

## Overview

The list phone numbers endpoint returns all phone numbers currently assigned to your company. Use the phone number `id` field when configuring agents for outbound or inbound calls.

## Use Cases

* **Agent Configuration**: Retrieve phone number IDs before creating or updating agents
* **Number Inventory**: Audit which numbers are assigned to your company
* **Capability Check**: Verify whether numbers support outbound, inbound, or both call directions

## ATS Keys

ATS partner keys must supply the `companyId` query parameter to specify which child company's phone numbers to list. Regular company API keys automatically scope the response to their own company.

## Basic Usage

```
GET /phone-numbers
```

## With Pagination

```javascript theme={null}
// Get a specific page
GET /phone-numbers?page=2&limit=50

// Response includes pagination metadata
{
  "data": {
    "data": [...],
    "total": 5,
    "page": 2,
    "limit": 50,
    "totalPages": 1
  }
}
```

## Finding a Phone Number for an Agent

```javascript theme={null}
// Retrieve phone numbers and pick one for agent configuration
async function getPhoneNumberForAgent() {
  const response = await fetch("https://api.instaview.sk/phone-numbers", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

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

  // Use the `id` field when creating or updating an agent
  const outbound = data.data.find(
    (pn) =>
      pn.capabilities === "OUTBOUND" || pn.capabilities === "INBOUND_OUTBOUND",
  );
  return outbound?.id;
}
```

## ATS Key Example

```javascript theme={null}
// ATS partner key — scope to a specific child company
GET /phone-numbers?companyId=123e4567-e89b-12d3-a456-426614174000
```


## OpenAPI

````yaml GET /phone-numbers
openapi: 3.0.0
info:
  title: InstaView API
  description: |-
    InstaView API Documentation

    ## Authentication

    All endpoints require API key authentication using Bearer token:
    ```
    Authorization: Bearer sk_your_api_key_here
    ```

    ## API Key Management

    The API Key module provides comprehensive key management for:
    - **Direct Client Keys**: Company-scoped keys for your applications
    - **ATS Partner Keys**: Resource-scoped keys for ATS integrations

    ### Key Features
    - HMAC-SHA256 hashing for API key storage
    - Configurable rate limiting
    - Comprehensive audit logging
    - Company-level isolation
    - Resource scoping for ATS partners
  version: 1.0.0
  contact: {}
servers:
  - url: https://api.instaview.sk
    description: Production API Gateway
security: []
tags: []
paths:
  /phone-numbers:
    get:
      tags:
        - Phone Numbers
      summary: List phone numbers
      description: >-
        Lists active phone numbers assigned to the API key's company. Use the
        returned `id` when referencing a phone number in an agent configuration.
        ATS keys must supply the `companyId` query parameter.
      operationId: PublicPhoneNumbersController_listPhoneNumbers_v1
      parameters:
        - name: page
          required: false
          in: query
          description: Page number (1-based)
          schema:
            minimum: 1
            maximum: 10000
            default: 1
            example: 1
            type: integer
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            minimum: 1
            maximum: 100
            default: 20
            example: 20
            type: integer
        - name: companyId
          required: false
          in: query
          description: Company ID (required for ATS keys, optional for regular keys)
          schema:
            example: 123e4567-e89b-12d3-a456-426614174000
            type: string
            format: uuid
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicListPhoneNumbersResponseDto'
      security:
        - bearer: []
components:
  schemas:
    PublicListPhoneNumbersResponseDto:
      type: object
      properties:
        data:
          description: Array of phone numbers
          type: array
          items:
            $ref: '#/components/schemas/PublicPhoneNumberDto'
        total:
          type: number
          description: Total number of items
          example: 3
        page:
          type: number
          description: Current page number
          example: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
        totalPages:
          type: number
          description: Total number of pages
          example: 1
      required:
        - data
        - total
        - page
        - limit
        - totalPages
    PublicPhoneNumberDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Phone number assignment ID (use this when referencing in agents)
          example: 123e4567-e89b-12d3-a456-426614174000
        number:
          type: string
          description: E.164 formatted phone number
          example: '+14155552671'
        companyId:
          type: string
          format: uuid
          description: Company ID this phone number belongs to
          example: 123e4567-e89b-12d3-a456-426614174000
        capabilities:
          type: string
          description: Phone number capabilities
          enum:
            - UNDEFINED
            - OUTBOUND
            - INBOUND_OUTBOUND
          example: OUTBOUND
        custom:
          type: boolean
          description: Whether this is a custom phone number dedicated to a single company
          example: false
        location:
          type: string
          description: Location or city associated with this phone number
          example: New York, US
          nullable: true
        provider:
          type: string
          description: Phone number provider
          enum:
            - UNDEFINED
            - TWILIO
            - TELNYX
          example: TWILIO
        status:
          type: string
          description: Lifecycle status of the phone number
          enum:
            - UNDEFINED
            - AVAILABLE
            - PENDING_COMPLIANCE
            - IN_USE
            - DEVELOPMENT
          example: AVAILABLE
        numberType:
          type: string
          description: Phone number type
          enum:
            - UNDEFINED
            - NATIONAL
            - LOCAL
            - TOLL_FREE
            - MOBILE
          example: LOCAL
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 creation timestamp
          example: '2025-01-15T10:30:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 last-update timestamp
          example: '2025-06-01T08:00:00.000Z'
      required:
        - id
        - number
        - companyId
        - capabilities
        - custom
        - provider
        - status
        - numberType
        - createdAt
        - updatedAt
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: API key for authentication using Bearer scheme

````