Bandwidth Emergency Calling API

openapi: 3.1.0
info:
  title: Bandwidth Emergency Calling 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/
externalDocs:
  description: Bandwidth Emergency Calling API Documentation
  url: https://dev.bandwidth.com/docs/emergency/emergencyCallingApi/
servers:
  - url: https://dashboard.bandwidth.com/api
    description: Production Server
tags:
  - name: Emergency Notification Recipients
    description: >-
      Configure notification recipients who receive alerts when 911
      calls are made from your endpoints.
  - name: Endpoints
    description: >-
      Manage 911 endpoints that represent end users of your service.
      Endpoints are identified by Alternate End User IDs (AEUIs) and
      are associated with locations for emergency routing.
  - name: Locations
    description: >-
      Provision and manage physical locations (addresses) for 911
      emergency services routing. Locations are validated against the
      Master Street Address Guide (MSAG) for accuracy.
security:
  - basicAuth: []
paths:
  /accounts/{accountId}/e911s:
    get:
      operationId: listEndpoints
      summary: List E911 endpoints
      description: >-
        Retrieves a list of all 911 endpoints provisioned for the account.
        Each endpoint represents an end user that may place emergency calls.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Endpoints retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/EndpointListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createEndpoint
      summary: Create an E911 endpoint
      description: >-
        Provisions a new 911 endpoint for an end user. The endpoint is
        identified by an Alternate End User ID (AEUI) and must be
        associated with a validated location for emergency routing.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Endpoint'
      responses:
        '201':
          description: Endpoint created successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: Invalid endpoint configuration
        '401':
          description: Unauthorized
  /accounts/{accountId}/e911s/{endpointId}:
    get:
      operationId: getEndpoint
      summary: Get E911 endpoint details
      description: >-
        Retrieves detailed information about a specific 911 endpoint
        including its associated location and configuration.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/endpointId'
      responses:
        '200':
          description: Endpoint details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
    put:
      operationId: updateEndpoint
      summary: Update an E911 endpoint
      description: >-
        Updates the configuration or location association for a specific
        911 endpoint.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/endpointId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Endpoint'
      responses:
        '200':
          description: Endpoint updated successfully
        '400':
          description: Invalid endpoint configuration
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
    delete:
      operationId: deleteEndpoint
      summary: Delete an E911 endpoint
      description: >-
        Removes a 911 endpoint from the account. The endpoint will no
        longer be able to route emergency calls.
      tags:
        - Endpoints
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/endpointId'
      responses:
        '200':
          description: Endpoint deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Endpoint not found
  /accounts/{accountId}/e911s/locations:
    get:
      operationId: listLocations
      summary: List E911 locations
      description: >-
        Retrieves a list of all validated locations provisioned for
        emergency calling within the account.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Locations retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/LocationListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createLocation
      summary: Create an E911 location
      description: >-
        Provisions a new location for emergency calling. The address is
        validated against the Master Street Address Guide (MSAG) to
        ensure it can be properly routed to the correct PSAP. Bandwidth
        can generate a location ID automatically, or you can provide your
        own custom location ID.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Location'
      responses:
        '201':
          description: Location created and validated successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Location'
        '400':
          description: Invalid location or address validation failed
        '401':
          description: Unauthorized
  /accounts/{accountId}/e911s/locations/{locationId}:
    get:
      operationId: getLocation
      summary: Get E911 location details
      description: >-
        Retrieves detailed information about a specific validated location.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/locationId'
      responses:
        '200':
          description: Location details retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Location'
        '401':
          description: Unauthorized
        '404':
          description: Location not found
    put:
      operationId: updateLocation
      summary: Update an E911 location
      description: >-
        Updates a specific location. The new address will be re-validated
        against the MSAG.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/locationId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Location'
      responses:
        '200':
          description: Location updated successfully
        '400':
          description: Invalid location or address validation failed
        '401':
          description: Unauthorized
        '404':
          description: Location not found
    delete:
      operationId: deleteLocation
      summary: Delete an E911 location
      description: >-
        Removes a location from the account. The location must not be
        currently associated with any active endpoints.
      tags:
        - Locations
      parameters:
        - $ref: '#/components/parameters/accountId'
        - $ref: '#/components/parameters/locationId'
      responses:
        '200':
          description: Location deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Location not found
  /accounts/{accountId}/e911s/notificationRecipients:
    get:
      operationId: listNotificationRecipients
      summary: List emergency notification recipients
      description: >-
        Retrieves a list of configured notification recipients who are
        alerted when 911 calls are placed from the account's endpoints.
      tags:
        - Emergency Notification Recipients
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Notification recipients retrieved successfully
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/NotificationRecipientListResponse'
        '401':
          description: Unauthorized
    post:
      operationId: createNotificationRecipient
      summary: Create a notification recipient
      description: >-
        Configures a new notification recipient to receive alerts when
        911 calls are placed from the account's endpoints.
      tags:
        - Emergency Notification Recipients
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/NotificationRecipient'
      responses:
        '201':
          description: Notification recipient created successfully
        '400':
          description: Invalid notification recipient configuration
        '401':
          description: Unauthorized
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using your Bandwidth Dashboard API
        credentials.
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
    endpointId:
      name: endpointId
      in: path
      required: true
      description: The unique identifier for the E911 endpoint
      schema:
        type: string
    locationId:
      name: locationId
      in: path
      required: true
      description: The unique identifier for the E911 location
      schema:
        type: string
  schemas:
    Endpoint:
      type: object
      description: An E911 endpoint representing an end user
      properties:
        endpointId:
          type: string
          description: The unique identifier for the endpoint
        alternateEndUserId:
          type: string
          description: >-
            The Alternate End User ID (AEUI) that identifies the end user
        callerName:
          type: string
          description: The name of the end user for PSAP display
        locationId:
          type: string
          description: >-
            The ID of the validated location associated with this endpoint
        telephoneNumber:
          type: string
          description: The phone number associated with this endpoint
        activated:
          type: boolean
          description: Whether the endpoint is currently active
    EndpointListResponse:
      type: object
      description: Response containing a list of E911 endpoints
      properties:
        totalCount:
          type: integer
          description: Total number of endpoints
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
    Location:
      type: object
      description: >-
        A validated physical location for E911 emergency routing
      properties:
        locationId:
          type: string
          description: The unique identifier for the location
        description:
          type: string
          description: A description of the location
        address:
          type: object
          properties:
            houseNumber:
              type: string
              description: The house or building number
            houseSuffix:
              type: string
              description: The house number suffix (e.g., A, B, 1/2)
            prefixDirectional:
              type: string
              description: The street prefix directional (N, S, E, W)
            streetName:
              type: string
              description: The street name
            streetSuffix:
              type: string
              description: The street suffix (St, Ave, Blvd, etc.)
            postDirectional:
              type: string
              description: The street post directional (N, S, E, W)
            addressLine2:
              type: string
              description: Secondary address line (suite, floor, etc.)
            city:
              type: string
              description: The city name
            stateCode:
              type: string
              description: The two-letter state code
            zip:
              type: string
              description: The five-digit ZIP code
            plusFour:
              type: string
              description: The ZIP+4 extension
            country:
              type: string
              description: The country code
        status:
          type: string
          enum:
            - VALID
            - INVALID
            - GEOCODED
          description: The validation status of the location
        latitude:
          type: number
          format: double
          description: The latitude coordinate of the location
        longitude:
          type: number
          format: double
          description: The longitude coordinate of the location
    LocationListResponse:
      type: object
      description: Response containing a list of E911 locations
      properties:
        totalCount:
          type: integer
          description: Total number of locations
        locations:
          type: array
          items:
            $ref: '#/components/schemas/Location'
    NotificationRecipient:
      type: object
      description: A recipient for emergency call notifications
      properties:
        id:
          type: string
          description: The unique identifier for the notification recipient
        emailAddress:
          type: string
          format: email
          description: The email address for notifications
        phoneNumber:
          type: string
          description: The phone number for SMS notifications
        description:
          type: string
          description: A description of the notification recipient
    NotificationRecipientListResponse:
      type: object
      description: Response containing a list of notification recipients
      properties:
        notificationRecipients:
          type: array
          items:
            $ref: '#/components/schemas/NotificationRecipient'