Bandwidth Phone Numbers API

openapi: 3.1.0
info:
  title: Bandwidth Phone Numbers API
  description: >-
    The Bandwidth Phone Numbers API provides programmatic access to search,
    order, and manage phone numbers across the United States and Canada.
    Developers can search for available local, toll-free, and short code
    numbers, initiate number porting requests, and configure number features
    such as CNAM, directory listings, and line features. The API also
    supports managing sites, SIP peers, and number assignments for
    organizing telephony resources within an account. This API uses
    XML request and response bodies and Basic Authentication.
  version: '1.0'
  contact:
    name: Bandwidth Support
    url: https://support.bandwidth.com
  termsOfService: https://www.bandwidth.com/legal/
externalDocs:
  description: Bandwidth Phone Numbers API Documentation
  url: https://dev.bandwidth.com/docs/numbers/
servers:
  - url: https://dashboard.bandwidth.com/api
    description: Production Server
tags:
  - name: Available Numbers
    description: >-
      Search for available phone numbers by area code, NPA-NXX, rate center,
      city, state, or ZIP code. Returns numbers available for ordering.
  - name: Disconnects
    description: >-
      Disconnect and release phone numbers that are no longer needed.
  - name: Number Features
    description: >-
      Configure phone number features including CNAM (Caller Name),
      directory listings, and line features for numbers in your inventory.
  - name: Orders
    description: >-
      Create and manage phone number orders. Supports ordering new numbers
      from available inventory and tracking order status.
  - name: Phone Numbers
    description: >-
      Search and manage phone numbers currently assigned to your account,
      including configuring number features and assignments.
  - name: Port-Ins
    description: >-
      Initiate and manage phone number porting requests to bring existing
      numbers from other carriers to Bandwidth.
  - name: SIP Peers
    description: >-
      Manage SIP peers (locations) within sites. SIP peers define
      the network endpoints for call routing and number assignment.
  - name: Sites
    description: >-
      Manage sites (sub-accounts) within a Bandwidth account. Sites
      represent logical groupings for organizing telephony resources.
security:
  - basicAuth: []
paths:
  /accounts/{accountId}/availableNumbers:
    get:
      operationId: searchAvailableNumbers
      summary: Search available phone numbers
      description: >-
        Searches Bandwidth's inventory for available phone numbers matching
        the specified criteria. Supports searches by area code, NPA-NXX,
        rate center, city, state, ZIP code, and LATA. Returns up to the
        requested quantity of available numbers.
      tags:
        - Available Numbers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: areaCode
          in: query
          description: Three-digit area code to search
          schema:
            type: string
            pattern: '^\d{3}$'
        - name: npaNxx
          in: query
          description: Six-digit NPA-NXX combination to search
          schema:
            type: string
            pattern: '^\d{6}$'
        - name: rateCenter
          in: query
          description: Rate center name to search
          schema:
            type: string
        - name: city
          in: query
          description: City name to search
          schema:
            type: string
        - name: state
          in: query
          description: Two-letter state abbreviation
          schema:
            type: string
            pattern: '^[A-Z]{2}$'
        - name: zip
          in: query
          description: Five-digit ZIP code to search
          schema:
            type: string
            pattern: '^\d{5}$'
        - name: lata
          in: query
          description: LATA code to search
          schema:
            type: string
        - name: quantity
          in: query
          description: Number of results to return (1-5000, default 5000)
          schema:
            type: integer
            minimum: 1
            maximum: 5000
            default: 5000
        - name: tollFreeWildCardPattern
          in: query
          description: >-
            Toll-free number pattern using wildcards (e.g., 8**) for
            toll-free number searches
          schema:
            type: string
        - name: enableTNDetail
          in: query
          description: Include detailed information for each number
          schema:
            type: boolean
            default: false
        - name: localVanity
          in: query
          description: Vanity number search pattern
          schema:
            type: string
      responses:
        '200':
          description: Available numbers found
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/AvailableNumbersResponse'
        '400':
          description: Invalid search parameters
        '401':
          description: Unauthorized
  /accounts/{accountId}/orders:
    post:
      operationId: createOrder
      summary: Create a phone number order
      description: >-
        Creates a new order to purchase phone numbers from Bandwidth's
        available inventory. The order specifies which numbers to purchase
        and the site and SIP peer to assign them to. Order status can be
        tracked via the GET endpoint or webhook callbacks.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Order created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '400':
          description: Invalid order request
        '401':
          description: Unauthorized
    get:
      operationId: listOrders
      summary: List phone number orders
      description: >-
        Retrieves a list of phone number orders for the account. Supports
        filtering by order status, date range, and other criteria.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: status
          in: query
          description: Filter by order status
          schema:
            type: string
            enum:
              - RECEIVED
              - PROCESSING
              - COMPLETE
              - PARTIAL
              - FAILED
        - name: startDate
          in: query
          description: Filter orders created on or after this date
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter orders created on or before this date
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Orders retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          description: Unauthorized
  /accounts/{accountId}/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Get order details
      description: >-
        Retrieves detailed information about a specific phone number order
        including its current status and list of numbers ordered.
      tags:
        - Orders
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/orderId'
      responses:
        '200':
          description: Order details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/OrderResponse'
        '401':
          description: Unauthorized
        '404':
          description: Order not found
  /accounts/{accountId}/portins:
    post:
      operationId: createPortIn
      summary: Create a port-in request
      description: >-
        Initiates a number porting request to transfer phone numbers from
        another carrier to Bandwidth. The request includes subscriber
        information and the list of numbers to port.
      tags:
        - Port-Ins
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/PortInRequest'
      responses:
        '201':
          description: Port-in request created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PortInResponse'
        '400':
          description: Invalid port-in request
        '401':
          description: Unauthorized
    get:
      operationId: listPortIns
      summary: List port-in requests
      description: >-
        Retrieves a list of number porting requests for the account.
      tags:
        - Port-Ins
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: status
          in: query
          description: Filter by port-in status
          schema:
            type: string
        - name: startDate
          in: query
          description: Filter requests created on or after this date
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: Filter requests created on or before this date
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Port-in requests retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PortInListResponse'
        '401':
          description: Unauthorized
  /accounts/{accountId}/portins/{portInId}:
    get:
      operationId: getPortIn
      summary: Get port-in request details
      description: >-
        Retrieves detailed information about a specific number porting
        request including its current status and timeline.
      tags:
        - Port-Ins
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: portInId
          in: path
          required: true
          description: The unique identifier for the port-in request
          schema:
            type: string
      responses:
        '200':
          description: Port-in details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PortInResponse'
        '401':
          description: Unauthorized
        '404':
          description: Port-in request not found
  /accounts/{accountId}/disconnects:
    post:
      operationId: createDisconnect
      summary: Disconnect phone numbers
      description: >-
        Creates a request to disconnect and release phone numbers from
        the account. Disconnected numbers are returned to Bandwidth's
        available inventory.
      tags:
        - Disconnects
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/DisconnectRequest'
      responses:
        '201':
          description: Disconnect request created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/DisconnectResponse'
        '400':
          description: Invalid disconnect request
        '401':
          description: Unauthorized
  /accounts/{accountId}/sites:
    get:
      operationId: listSites
      summary: List sites
      description: >-
        Retrieves a list of all sites (sub-accounts) configured within
        the Bandwidth account.
      tags:
        - Sites
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Sites retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SiteListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createSite
      summary: Create a site
      description: >-
        Creates a new site (sub-account) within the Bandwidth account.
        Sites provide logical groupings for organizing telephony resources.
      tags:
        - Sites
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Site'
      responses:
        '201':
          description: Site created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Site'
        '400':
          description: Invalid site configuration
        '401':
          description: Unauthorized
  /accounts/{accountId}/sites/{siteId}:
    get:
      operationId: getSite
      summary: Get site details
      description: >-
        Retrieves detailed information about a specific site.
      tags:
        - Sites
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: Site details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Site'
        '401':
          description: Unauthorized
        '404':
          description: Site not found
    put:
      operationId: updateSite
      summary: Update a site
      description: >-
        Updates the configuration for a specific site.
      tags:
        - Sites
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Site'
      responses:
        '200':
          description: Site updated successfully
        '400':
          description: Invalid site configuration
        '401':
          description: Unauthorized
        '404':
          description: Site not found
    delete:
      operationId: deleteSite
      summary: Delete a site
      description: >-
        Deletes a specific site. The site must have no active SIP peers
        or phone numbers assigned to it.
      tags:
        - Sites
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: Site deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Site not found
  /accounts/{accountId}/sites/{siteId}/sippeers:
    get:
      operationId: listSipPeers
      summary: List SIP peers
      description: >-
        Retrieves a list of SIP peers (locations) configured within a
        specific site.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
      responses:
        '200':
          description: SIP peers retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SipPeerListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createSipPeer
      summary: Create a SIP peer
      description: >-
        Creates a new SIP peer (location) within a site. SIP peers define
        the network endpoints for call routing and number assignment.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/SipPeer'
      responses:
        '201':
          description: SIP peer created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SipPeer'
        '400':
          description: Invalid SIP peer configuration
        '401':
          description: Unauthorized
  /accounts/{accountId}/sites/{siteId}/sippeers/{sipPeerId}:
    get:
      operationId: getSipPeer
      summary: Get SIP peer details
      description: >-
        Retrieves detailed information about a specific SIP peer.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
        - $ref: '#/components/parameters/sipPeerId'
      responses:
        '200':
          description: SIP peer details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/SipPeer'
        '401':
          description: Unauthorized
        '404':
          description: SIP peer not found
    put:
      operationId: updateSipPeer
      summary: Update a SIP peer
      description: >-
        Updates the configuration for a specific SIP peer.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
        - $ref: '#/components/parameters/sipPeerId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/SipPeer'
      responses:
        '200':
          description: SIP peer updated successfully
        '400':
          description: Invalid SIP peer configuration
        '401':
          description: Unauthorized
        '404':
          description: SIP peer not found
    delete:
      operationId: deleteSipPeer
      summary: Delete a SIP peer
      description: >-
        Deletes a specific SIP peer. The SIP peer must have no active
        phone numbers assigned to it.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
        - $ref: '#/components/parameters/sipPeerId'
      responses:
        '200':
          description: SIP peer deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: SIP peer not found
  /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
  /accounts/{accountId}/sites/{siteId}/sippeers/{sipPeerId}/tns:
    get:
      operationId: listSipPeerPhoneNumbers
      summary: List SIP peer phone numbers
      description: >-
        Retrieves a list of phone numbers assigned to a specific SIP peer
        within a site.
      tags:
        - SIP Peers
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/siteId'
        - $ref: '#/components/parameters/sipPeerId'
      responses:
        '200':
          description: Phone numbers retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/PhoneNumberListResponse'
        '401':
          description: Unauthorized
  /accounts/{accountId}/tns/{phoneNumber}/tnfeatureorder:
    post:
      operationId: updateNumberFeatures
      summary: Update phone number features
      description: >-
        Creates a feature order to configure features such as CNAM,
        directory listings, and line features for a specific phone number.
      tags:
        - Number Features
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: phoneNumber
          in: path
          required: true
          description: The phone number to update features for
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/FeatureOrderRequest'
      responses:
        '201':
          description: Feature order created successfully
        '400':
          description: Invalid feature order request
        '401':
          description: Unauthorized
        '404':
          description: Phone number not found
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using your Bandwidth Dashboard API
        credentials (API username and password).
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
    orderId:
      name: orderId
      in: path
      required: true
      description: The unique identifier for the order
      schema:
        type: string
    siteId:
      name: siteId
      in: path
      required: true
      description: The unique identifier for the site
      schema:
        type: string
    sipPeerId:
      name: sipPeerId
      in: path
      required: true
      description: The unique identifier for the SIP peer
      schema:
        type: string
  schemas:
    AvailableNumbersResponse:
      type: object
      description: Response containing a list of available phone numbers
      properties:
        resultCount:
          type: integer
          description: The number of results returned
        telephoneNumberList:
          type: array
          items:
            $ref: '#/components/schemas/AvailableNumber'
    AvailableNumber:
      type: object
      description: An available phone number from Bandwidth inventory
      properties:
        fullNumber:
          type: string
          description: The full phone number in E.164 format
        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 for the number
        rateCenter:
          type: string
          description: The rate center for the number
    OrderRequest:
      type: object
      description: Request to order phone numbers
      properties:
        name:
          type: string
          maxLength: 50
          description: A name for the order (required, max 50 characters)
        siteId:
          type: string
          description: The site to assign the numbers to
        peerId:
          type: string
          description: The SIP peer to assign the numbers to
        existingTelephoneNumberOrderType:
          type: object
          properties:
            telephoneNumberList:
              type: array
              items:
                type: string
              description: List of specific phone numbers to order
    OrderResponse:
      type: object
      description: Response containing order details
      properties:
        orderId:
          type: string
          description: The unique identifier for the order
        orderStatus:
          type: string
          enum:
            - RECEIVED
            - PROCESSING
            - COMPLETE
            - PARTIAL
            - FAILED
          description: The current status of the order
        orderCreateDate:
          type: string
          format: date-time
          description: The date and time the order was created
        completedQuantity:
          type: integer
          description: Number of phone numbers successfully ordered
        failedQuantity:
          type: integer
          description: Number of phone numbers that failed to order
        completedNumbers:
          type: array
          items:
            type: string
          description: List of successfully ordered phone numbers
    OrderListResponse:
      type: object
      description: Response containing a list of orders
      properties:
        totalCount:
          type: integer
          description: Total number of orders
        orders:
          type: array
          items:
            $ref: '#/components/schemas/OrderResponse'
    PortInRequest:
      type: object
      description: Request to port phone numbers from another carrier
      properties:
        siteId:
          type: string
          description: The site to assign ported numbers to
        peerId:
          type: string
          description: The SIP peer to assign ported numbers to
        billingTelephoneNumber:
          type: string
          description: The billing telephone number for the account being ported
        subscriber:
          type: object
          properties:
            subscriberType:
              type: string
              enum:
                - BUSINESS
                - RESIDENTIAL
              description: The type of subscriber
            businessName:
              type: string
              description: The business name (for business subscribers)
            firstName:
              type: string
              description: The subscriber first name
            lastName:
              type: string
              description: The subscriber last name
            serviceAddress:
              $ref: '#/components/schemas/Address'
        losingCarrierName:
          type: string
          description: The name of the current carrier
        listOfPhoneNumbers:
          type: array
          items:
            type: string
          description: List of phone numbers to port
        requestedFocDate:
          type: string
          format: date
          description: Requested Firm Order Commitment date
    PortInResponse:
      type: object
      description: Response containing port-in request details
      properties:
        portInId:
          type: string
          description: The unique identifier for the port-in request
        status:
          type: string
          description: The current status of the port-in request
        requestedFocDate:
          type: string
          format: date
          description: The requested FOC date
        actualFocDate:
          type: string
          format: date
          description: The actual FOC date assigned by the carrier
    PortInListResponse:
      type: object
      description: Response containing a list of port-in requests
      properties:
        totalCount:
          type: integer
          description: Total number of port-in requests
        portIns:
          type: array
          items:
            $ref: '#/components/schemas/PortInResponse'
    DisconnectRequest:
      type: object
      description: Request to disconnect phone numbers
      properties:
        name:
          type: string
          description: A name for the disconnect order
        disconnectTelephoneNumberOrderType:
          type: object
          properties:
            telephoneNumberList:
              type: array
              items:
                type: string
              description: List of phone numbers to disconnect
    DisconnectResponse:
      type: object
      description: Response containing disconnect order details
      properties:
        orderId:
          type: string
          description: The unique identifier for the disconnect order
        orderStatus:
          type: string
          description: The current status of the disconnect order
    Site:
      type: object
      description: A site (sub-account) within a Bandwidth account
      properties:
        id:
          type: string
          description: The unique identifier for the site
        name:
          type: string
          description: The name of the site
        description:
          type: string
          description: A description of the site
        address:
          $ref: '#/components/schemas/Address'
    SiteListResponse:
      type: object
      description: Response containing a list of sites
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
    SipPeer:
      type: object
      description: A SIP peer (location) within a site
      properties:
        peerId:
          type: string
          description: The unique identifier for the SIP peer
        peerName:
          type: string
          description: The name of the SIP peer
        description:
          type: string
          description: A description of the SIP peer
        isDefaultPeer:
          type: boolean
          description: Whether this is the default SIP peer for the site
    SipPeerListResponse:
      type: object
      description: Response containing a list of SIP peers
      properties:
        sipPeers:
          type: array
          items:
            $ref: '#/components/schemas/SipPeer'
    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
    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'
    FeatureOrderRequest:
      type: object
      descript

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bandwidth/refs/heads/main/openapi/bandwidth-phone-numbers-api-openapi.yml