Bandwidth Locations API

openapi: 3.2.0
info:
  title: Bandwidth Emergency Calling Locations API
  description: The Bandwidth Emergency Calling API provides programmatic access to provision and manage 911 endpoints and locations for emergency services routing.
  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: 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.
paths:
  /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
components:
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      description: The unique identifier for the Bandwidth account
      schema:
        type: string
    locationId:
      name: locationId
      in: path
      required: true
      description: The unique identifier for the E911 location
      schema:
        type: string
  schemas:
    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'
    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
  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/