openapi: 3.1.0
info:
  title: Bandwidth Emergency Calling Available Numbers Conferences 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: Conferences
  description: Create and manage multi-party conference calls. Supports adding and removing members, muting, holding, and playing audio to conferences.
paths:
  /accounts/{accountId}/conferences:
    get:
      operationId: listConferences
      summary: List conferences
      description: Retrieves a list of conferences associated with the account, including active and completed conferences.
      tags:
      - Conferences
      parameters:
      - $ref: '#/components/parameters/accountId'
      - name: name
        in: query
        description: Filter conferences by name
        schema:
          type: string
      - name: minCreatedTime
        in: query
        description: Minimum creation time for filtering
        schema:
          type: string
          format: date-time
      - name: maxCreatedTime
        in: query
        description: Maximum creation time for filtering
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Conferences retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Conference'
        '401':
          description: Unauthorized
  /accounts/{accountId}/conferences/{conferenceId}:
    get:
      operationId: getConference
      summary: Get conference information
      description: Retrieves detailed information about a specific conference including its current state and list of members.
      tags:
      - Conferences
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/conferenceId'
      responses:
        '200':
          description: Conference information retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conference'
        '401':
          description: Unauthorized
        '404':
          description: Conference not found
    post:
      operationId: updateConference
      summary: Update a conference
      description: Modifies an active conference. Can be used to mute all members, set the conference status to completed (ending the conference), or redirect the conference to a new callback URL.
      tags:
      - Conferences
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/conferenceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConferenceRequest'
      responses:
        '204':
          description: Conference updated successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Conference not found
  /accounts/{accountId}/conferences/{conferenceId}/members/{memberId}:
    put:
      operationId: updateConferenceMember
      summary: Update a conference member
      description: Modifies a specific member of an active conference. Supports muting, unmuting, holding, and removing individual members.
      tags:
      - Conferences
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/conferenceId'
      - name: memberId
        in: path
        required: true
        description: The unique identifier of the conference member
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConferenceMemberRequest'
      responses:
        '204':
          description: Conference member updated successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Member not found
  /accounts/{accountId}/conferences/{conferenceId}/recordings:
    get:
      operationId: getConferenceRecordings
      summary: List conference recordings
      description: Retrieves a list of all recordings associated with a specific conference.
      tags:
      - Conferences
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/conferenceId'
      responses:
        '200':
          description: Conference recordings retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Recording'
        '401':
          description: Unauthorized
        '404':
          description: Conference not found
components:
  schemas:
    Recording:
      type: object
      properties:
        recordingId:
          type: string
          description: The unique identifier for the recording
        accountId:
          type: string
          description: The Bandwidth account ID
        callId:
          type: string
          description: The call ID associated with this recording
        applicationId:
          type: string
          description: The application ID
        duration:
          type: string
          description: The duration of the recording in ISO 8601 format
        channels:
          type: integer
          description: The number of audio channels in the recording
        startTime:
          type: string
          format: date-time
          description: The time the recording started
        endTime:
          type: string
          format: date-time
          description: The time the recording ended
        fileFormat:
          type: string
          enum:
          - wav
          - mp3
          description: The audio format of the recording
        status:
          type: string
          enum:
          - complete
          - partial
          - error
          description: The status of the recording
        mediaUrl:
          type: string
          format: uri
          description: The URL to download the recording media
        transcription:
          $ref: '#/components/schemas/Transcription'
    UpdateConferenceRequest:
      type: object
      properties:
        status:
          type: string
          enum:
          - active
          - completed
          description: Set to completed to end the conference and disconnect all members
        redirectUrl:
          type: string
          format: uri
          description: URL to redirect the conference to for new BXML instructions
        redirectMethod:
          type: string
          enum:
          - POST
          - GET
          default: POST
          description: The HTTP method for the redirect webhook
        tag:
          type: string
          description: Custom tag for the conference
    Conference:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the conference
        name:
          type: string
          description: The user-defined name of the conference
        createdTime:
          type: string
          format: date-time
          description: The time the conference was created
        completedTime:
          type: string
          format: date-time
          description: The time the conference ended
        tag:
          type: string
          description: Custom tag attached to the conference
        activeMembers:
          type: array
          description: List of currently active conference members
          items:
            $ref: '#/components/schemas/ConferenceMember'
    UpdateConferenceMemberRequest:
      type: object
      properties:
        mute:
          type: boolean
          description: Whether to mute the member
        hold:
          type: boolean
          description: Whether to place the member on hold
        callIdsToCoach:
          type: array
          items:
            type: string
          description: List of call IDs that this member should coach
    ConferenceMember:
      type: object
      properties:
        callId:
          type: string
          description: The call ID of the conference member
        conferenceId:
          type: string
          description: The conference ID
        memberUrl:
          type: string
          format: uri
          description: The URL for this member resource
        mute:
          type: boolean
          description: Whether the member is muted
        hold:
          type: boolean
          description: Whether the member is on hold
        callIdsToCoach:
          type: array
          items:
            type: string
          description: List of call IDs that this member is coaching
    Transcription:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the transcription
        status:
          type: string
          enum:
          - none
          - available
          - error
          description: The status of the transcription
        completedTime:
          type: string
          format: date-time
          description: The time the transcription was completed
        url:
          type: string
          format: uri
          description: The URL of the transcription result
  parameters:
    conferenceId:
      name: conferenceId
      in: path
      required: true
      description: The unique identifier for the conference
      schema:
        type: string
    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/