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

# List available phone numbers

> Retrieves all phone numbers from the connected Twilio account.
Each number includes an imported flag indicating whether it has already been imported into the system.
Use this endpoint to discover numbers before importing them.

## Phone Number Discovery

This endpoint connects to your Twilio account and retrieves all incoming phone numbers.

## Response Fields

Each phone number includes:

| Field            | Description                                  |
| ---------------- | -------------------------------------------- |
| **sid**          | Twilio Phone Number SID (used for import)    |
| **phoneNumber**  | E.164 formatted phone number                 |
| **friendlyName** | Human-readable name set in Twilio            |
| **imported**     | Whether the number has already been imported |

## Import Workflow

1. Call this endpoint to see available numbers
2. Note the `sid` values of numbers you want to import
3. Use the `/import-numbers` endpoint with those SIDs

## Already Imported Numbers

Numbers marked with `imported: true` are already in your system and linked to this provider. Attempting to import them again will result in a duplicate error.


## OpenAPI

````yaml https://blackbox.dasha.ai/swagger/v1/swagger.json get /api/v1/providers/twilio/{id}/available-numbers
openapi: 3.0.4
info:
  title: Dasha BlackBox Agent API
  description: API for managing AI agents and calls
  contact:
    name: DashaAI Team
    email: support@dasha.ai
  version: v1
servers:
  - url: https://blackbox.dasha.ai
    description: Dasha BlackBox Agent API
security:
  - ApiKey: []
  - OAuth: []
tags:
  - name: ActivityLogs
  - name: Agents
  - name: AgentTestCases
  - name: CallResults
  - name: Calls
  - name: Chats
  - name: Copilot
  - name: CustomerData
  - name: Mcp
  - name: Media
  - name: Misc
  - name: PronunciationDictionaries
  - name: Providers
  - name: SipAliases
  - name: SipCredentials
  - name: SipPhoneNumbers
  - name: TextChat
  - name: TwilioProvider
  - name: Voice
  - name: WebhookTest
  - name: WebIntegrations
  - name: WebSocket
    description: WebSocket endpoints for real-time communication
paths:
  /api/v1/providers/twilio/{id}/available-numbers:
    get:
      tags:
        - TwilioProvider
      summary: List available phone numbers
      description: >-
        Retrieves all phone numbers from the connected Twilio account.

        Each number includes an imported flag indicating whether it has already
        been imported into the system.

        Use this endpoint to discover numbers before importing them.
      parameters:
        - name: id
          in: path
          description: Provider identifier
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Returns available phone numbers with import status
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TwilioAvailablePhoneNumberDto'
        '401':
          description: Authentication failed or API key is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Access denied to the requested resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Provider with specified ID does not exist in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Server error occurred while retrieving phone numbers
components:
  schemas:
    TwilioAvailablePhoneNumberDto:
      required:
        - friendlyName
        - phoneNumber
        - sid
      type: object
      properties:
        sid:
          type: string
          description: >-
            Twilio Phone Number SID. Unique identifier for the phone number in
            Twilio.

            Format: PN[a-f0-9]{32} (e.g., PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx).
          nullable: true
        phoneNumber:
          type: string
          description: >-
            Phone number in E.164 format (e.g., +14155551234). The actual
            dialable phone number.
          nullable: true
        friendlyName:
          type: string
          description: >-
            Human-readable name for the phone number from Twilio. May include
            formatting or descriptive text.
          nullable: true
        imported:
          type: boolean
          description: |-
            Whether this phone number has already been imported into the system.
            True if imported, false if available for import.
      additionalProperties: false
      description: >-
        DTO representing an available phone number from a Twilio account that
        can be imported.

        Contains information about the phone number and whether it has already
        been imported into the system.
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
  securitySchemes:
    ApiKey:
      type: http
      description: API Key Authentication (Bearer {key})
      scheme: Bearer
    OAuth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://auth.dasha.ai/connect/authorize
          scopes:
            platform_api: Platform API

````