Bandwidth Phone Numbers API

openapi: 3.1.0
info:
  title: Bandwidth Emergency Calling Available Numbers Phone Numbers API
  description: The Bandwidth Emergency Calling API provides programmatic access to provision and manage 911 endpoints and locations for emergency services routing. It supports Dynamic Location Routing (DLR) for real-time address validation and location updates, ensuring compliance with Kari's Law and RAY BAUM's Act requirements. Bandwidth is the only CPaaS provider that also operates its own emergency services network, providing direct connectivity to public safety answering points (PSAPs) across the United States and Canada.
  version: '1.0'
  contact:
    name: Bandwidth Support
    url: https://support.bandwidth.com
  termsOfService: https://www.bandwidth.com/legal/
servers:
- url: https://dashboard.bandwidth.com/api
  description: Production Server
security:
- basicAuth: []
tags:
- name: Phone Numbers
  description: Search and manage phone numbers currently assigned to your account, including configuring number features and assignments.
paths:
  /accounts/{accountId}/tns:
    get:
      operationId: listPhoneNumbers
      summary: List phone numbers
      description: Retrieves a list of phone numbers assigned to the account. Supports filtering by various criteria including city, state, and LATA.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/accountId'
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          minimum: 1
      - name: size
        in: query
        description: Number of results per page
        schema:
          type: integer
          minimum: 1
          maximum: 500
      - name: city
        in: query
        description: Filter by city
        schema:
          type: string
      - name: state
        in: query
        description: Filter by state abbreviation
        schema:
          type: string
      - name: lata
        in: query
        description: Filter by LATA code
        schema:
          type: string
      responses:
        '200':
          description: Phone numbers retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PhoneNumberListResponse'
        '401':
          description: Unauthorized
  /accounts/{accountId}/tns/{phoneNumber}:
    get:
      operationId: getPhoneNumber
      summary: Get phone number details
      description: Retrieves detailed information about a specific phone number including its assignment, features, and configuration.
      tags:
      - Phone Numbers
      parameters:
      - $ref: '#/components/parameters/accountId'
      - name: phoneNumber
        in: path
        required: true
        description: The phone number to look up (digits only)
        schema:
          type: string
      responses:
        '200':
          description: Phone number details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PhoneNumber'
        '401':
          description: Unauthorized
        '404':
          description: Phone number not found
components:
  schemas:
    PhoneNumberListResponse:
      type: object
      description: Response containing a list of phone numbers
      properties:
        totalCount:
          type: integer
          description: Total number of phone numbers
        telephoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
    PhoneNumber:
      type: object
      description: A phone number assigned to the account
      properties:
        fullNumber:
          type: string
          description: The full phone number
        city:
          type: string
          description: The city associated with the number
        state:
          type: string
          description: The state associated with the number
        lata:
          type: string
          description: The LATA code
        rateCenter:
          type: string
          description: The rate center
        status:
          type: string
          description: The current status of the number
        siteId:
          type: string
          description: The site the number is assigned to
        sipPeerId:
          type: string
          description: The SIP peer the number is assigned to
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using your Bandwidth Dashboard API credentials.
externalDocs:
  description: Bandwidth Emergency Calling API Documentation
  url: https://dev.bandwidth.com/docs/emergency/emergencyCallingApi/