openapi: 3.1.0
info:
  title: Bandwidth Emergency Calling Available Numbers Sites 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: Sites
  description: Manage sites (sub-accounts) within a Bandwidth account. Sites represent logical groupings for organizing telephony resources.
paths:
  /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
components:
  schemas:
    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'
    Address:
      type: object
      description: A physical address
      properties:
        houseNumber:
          type: string
          description: The house/building number
        streetName:
          type: string
          description: The street name
        city:
          type: string
          description: The city
        stateCode:
          type: string
          description: The two-letter state code
        zip:
          type: string
          description: The ZIP code
        country:
          type: string
          description: The country code
    SiteListResponse:
      type: object
      description: Response containing a list of sites
      properties:
        sites:
          type: array
          items:
            $ref: '#/components/schemas/Site'
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
    siteId:
      name: siteId
      in: path
      required: true
      description: The unique identifier for the site
      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/