The Bandwidth Voice API enables developers to programmatically make and receive phone calls, manage call recordings, and create multi-party conferences. It supports advanced call control features including call transfers, bridging, DTMF detection, and text-to-speech. The API uses BXML (Bandwidth XML) verbs for call flow control and provides webhooks for real-time event notifications on call state changes.
openapi: 3.1.0
info:
title: Bandwidth Voice API
description: >-
The Bandwidth Voice API enables developers to programmatically make and
receive phone calls, manage call recordings, and create multi-party
conferences. It supports advanced call control features including call
transfers, bridging, DTMF detection, and text-to-speech. The API uses
BXML (Bandwidth XML) verbs for call flow control and provides webhooks
for real-time event notifications on call state changes. Bandwidth
operates its own tier-1 network, providing direct carrier connectivity.
version: '2.0'
contact:
name: Bandwidth Support
url: https://support.bandwidth.com
termsOfService: https://www.bandwidth.com/legal/
externalDocs:
description: Bandwidth Voice API Documentation
url: https://dev.bandwidth.com/docs/voice/
servers:
- url: https://voice.bandwidth.com/api/v2
description: Production Server
tags:
- name: Calls
description: >-
Create, retrieve, and manage phone calls. Supports outbound call
creation, call state queries, and in-progress call modifications
using BXML or redirect URLs.
- name: Conferences
description: >-
Create and manage multi-party conference calls. Supports adding and
removing members, muting, holding, and playing audio to conferences.
- name: Recordings
description: >-
Manage call recordings including retrieval of recording metadata,
audio files, and transcription of recorded audio content.
security:
- basicAuth: []
paths:
/accounts/{accountId}/calls:
post:
operationId: createCall
summary: Create a call
description: >-
Creates an outbound phone call. The call will be initiated from the
specified Bandwidth number to the destination number. The answerUrl
will receive a webhook when the call is answered, and your application
should respond with BXML to control the call flow.
tags:
- Calls
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCallRequest'
responses:
'201':
description: Call created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Call'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
'403':
description: Forbidden
/accounts/{accountId}/calls/{callId}:
get:
operationId: getCall
summary: Get call information
description: >-
Retrieves the current state and metadata for a specific call
identified by its call ID.
tags:
- Calls
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
responses:
'200':
description: Call information retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Call'
'401':
description: Unauthorized
'404':
description: Call not found
post:
operationId: updateCall
summary: Update a call
description: >-
Modifies an in-progress call by redirecting it to a new BXML
document URL or by completing the call. This enables advanced
call control scenarios such as transferring, bridging, or
terminating calls programmatically.
tags:
- Calls
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateCallRequest'
responses:
'200':
description: Call updated successfully
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized
'404':
description: Call not found
/accounts/{accountId}/calls/{callId}/recordings:
get:
operationId: getCallRecordings
summary: List call recordings
description: >-
Retrieves a list of all recordings associated with a specific call.
Each recording includes metadata such as duration, file format, and
media URL for downloading the audio file.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
responses:
'200':
description: Recordings retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Recording'
'401':
description: Unauthorized
'404':
description: Call not found
/accounts/{accountId}/calls/{callId}/recordings/{recordingId}:
get:
operationId: getCallRecording
summary: Get a specific recording
description: >-
Retrieves metadata for a specific recording associated with a call.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
- $ref: '#/components/parameters/recordingId'
responses:
'200':
description: Recording metadata retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Recording'
'401':
description: Unauthorized
'404':
description: Recording not found
delete:
operationId: deleteCallRecording
summary: Delete a recording
description: >-
Permanently deletes a specific call recording and its associated
media file.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
- $ref: '#/components/parameters/recordingId'
responses:
'204':
description: Recording deleted successfully
'401':
description: Unauthorized
'404':
description: Recording not found
/accounts/{accountId}/calls/{callId}/recordings/{recordingId}/media:
get:
operationId: getCallRecordingMedia
summary: Download recording media
description: >-
Downloads the audio file for a specific call recording. Returns
the binary audio content in the format specified during recording.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
- $ref: '#/components/parameters/recordingId'
responses:
'200':
description: Recording audio file
content:
audio/wav:
schema:
type: string
format: binary
audio/mpeg:
schema:
type: string
format: binary
'401':
description: Unauthorized
'404':
description: Recording not found
/accounts/{accountId}/calls/{callId}/recordings/{recordingId}/transcription:
post:
operationId: createRecordingTranscription
summary: Transcribe a recording
description: >-
Initiates a transcription job for a specific call recording. The
transcription result will be delivered via a webhook callback to
the URL specified in the request or the application's default
callback URL.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
- $ref: '#/components/parameters/recordingId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TranscriptionRequest'
responses:
'200':
description: Transcription initiated
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Recording not found
get:
operationId: getRecordingTranscription
summary: Get recording transcription
description: >-
Retrieves the transcription result for a specific call recording.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- $ref: '#/components/parameters/callId'
- $ref: '#/components/parameters/recordingId'
responses:
'200':
description: Transcription retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Transcription'
'401':
description: Unauthorized
'404':
description: Transcription not found
/accounts/{accountId}/recordings:
get:
operationId: listAccountRecordings
summary: List account recordings
description: >-
Retrieves a list of all recordings across all calls for the account.
Supports filtering by date range and pagination.
tags:
- Recordings
parameters:
- $ref: '#/components/parameters/accountId'
- name: from
in: query
description: Filter recordings created on or after this date
schema:
type: string
format: date-time
- name: to
in: query
description: Filter recordings created on or before this date
schema:
type: string
format: date-time
- name: minStartTime
in: query
description: Minimum start time for filtering recordings
schema:
type: string
format: date-time
- name: maxStartTime
in: query
description: Maximum start time for filtering recordings
schema:
type: string
format: date-time
responses:
'200':
description: Recordings list retrieved successfully
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Recording'
'401':
description: Unauthorized
/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:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic Authentication using your Bandwidth API credentials.
Use your API username and password from the Bandwidth Dashboard.
parameters:
accountId:
name: accountId
in: path
required: true
description: The unique identifier for the Bandwidth account
schema:
type: string
callId:
name: callId
in: path
required: true
description: The unique identifier for the call
schema:
type: string
recordingId:
name: recordingId
in: path
required: true
description: The unique identifier for the recording
schema:
type: string
conferenceId:
name: conferenceId
in: path
required: true
description: The unique identifier for the conference
schema:
type: string
schemas:
CreateCallRequest:
type: object
required:
- from
- to
- answerUrl
- applicationId
properties:
from:
type: string
description: >-
The Bandwidth phone number that will make the outbound call,
in E.164 format
example: '+19195551234'
to:
type: string
description: >-
The destination phone number for the outbound call, in E.164 format
example: '+19195554321'
answerUrl:
type: string
format: uri
description: >-
The URL to send the answer webhook to when the call is answered.
The endpoint should return BXML to control the call flow.
answerMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method to use for the answer webhook
answerFallbackUrl:
type: string
format: uri
description: >-
Fallback URL for the answer webhook if the primary URL fails
answerFallbackMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method for the fallback answer webhook
disconnectUrl:
type: string
format: uri
description: >-
The URL to send the disconnect webhook to when the call ends
disconnectMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method for the disconnect webhook
applicationId:
type: string
description: >-
The ID of the Bandwidth application associated with this call
tag:
type: string
maxLength: 256
description: >-
A custom string to attach to the call for tracking purposes
callTimeout:
type: number
minimum: 1
maximum: 300
default: 30
description: >-
The timeout in seconds for the outbound call to be answered
callbackTimeout:
type: number
minimum: 1
maximum: 25
default: 15
description: >-
The timeout in seconds for webhook callback requests
UpdateCallRequest:
type: object
properties:
state:
type: string
enum:
- active
- completed
description: >-
Set to completed to hang up the call
redirectUrl:
type: string
format: uri
description: >-
The URL to redirect the call to for new BXML instructions
redirectMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method for the redirect webhook
redirectFallbackUrl:
type: string
format: uri
description: >-
Fallback URL if the primary redirect URL fails
redirectFallbackMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method for the fallback redirect webhook
tag:
type: string
maxLength: 256
description: >-
A custom string to attach to the call for tracking purposes
Call:
type: object
properties:
callId:
type: string
description: The unique identifier for the call
accountId:
type: string
description: The Bandwidth account ID
applicationId:
type: string
description: The application ID associated with the call
to:
type: string
description: The destination phone number
from:
type: string
description: The originating phone number
direction:
type: string
enum:
- inbound
- outbound
description: The direction of the call
state:
type: string
enum:
- initiated
- answered
- completed
description: The current state of the call
startTime:
type: string
format: date-time
description: The time the call was initiated
answerTime:
type: string
format: date-time
description: The time the call was answered
endTime:
type: string
format: date-time
description: The time the call ended
disconnectCause:
type: string
description: The reason the call was disconnected
tag:
type: string
description: Custom tag attached to the call
callUrl:
type: string
format: uri
description: The URL for this call resource
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'
TranscriptionRequest:
type: object
properties:
callbackUrl:
type: string
format: uri
description: >-
The URL to send the transcription completed webhook to
callbackMethod:
type: string
enum:
- POST
- GET
default: POST
description: The HTTP method for the transcription webhook
tag:
type: string
description: Custom tag for the transcription request
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
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'
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
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
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
Error:
type: object
properties:
type:
type: string
description: The error type URI
description:
type: string
description: A human-readable description of the error
id:
type: string
description: The unique error identifier