Create Call

Creates a new outbound phone call.

Request URL


Basic Authentication

Bandwidth's Voice API leverages Basic Authentication with your Dashboard API Credentials. Read more about how Bandwidth secures endpoints in the Security & Credentials document.

Supported Parameters

Parameter Description Mandatory
from A Bandwidth phone number on your account the call should come from (must be in E.164 format, like +15555551212, or be one of the following strings: Restricted, Anonymous, Private, or Unavailable). Yes
to The destination to call (must be an E.164 formatted number (e.g. +15555551212) or a SIP URI (e.g. Yes
applicationId The id of the application to associate this call with, for billing purposes. Yes
answerUrl The full URL to send the Answer event to when the called party answers. This endpoint should return the first BXML document to be executed in the call. Yes
answerMethod (optional) The HTTP method to use for the request to answerUrl. GET or POST. Default value is POST. No
disconnectUrl (optional) The URL to send the Disconnect event to when the call ends. This event does not expect a BXML as response. No
disconnectMethod (optional) The HTTP method to use for the request to disconnectUrl. GET or POST. Default value is POST. No
username (optional) The username to send in the HTTP request to answerUrl and disconnectUrl. No
password (optional) The password to send in the HTTP request to answerUrl and disconnectUrl. No
callTimeout (optional) The timeout (in seconds) for the callee to answer the call after it starts ringing. If the call does not start ringing within 30s, the call will be cancelled regardless of this value. Can be any numeric value (including decimals) between 1 and 300. Default: 30 No
tag (optional) A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared.

May be cleared by setting tag=""

Max length 256 characters.
answerFallbackUrl (optional) A fallback url which, if provided, will be used to retry the answer callback delivery in case answerUrl fails to respond No
answerFallbackMethod (optional) The HTTP method to use to deliver the answer callback to answerFallbackUrl. GET or POST. Default value is POST. No
fallbackUsername (optional) The username to send in the HTTP request to answerFallbackUrl No
fallbackPassword (optional) The password to send in the HTTP request to answerFallbackUrl No
callbackTimeout (optional) This is the timeout (in seconds) to use when delivering callbacks for the call. Can be any numeric value (including decimals) between 1 and 25. Default: 15 No
uui (optional) The value of the User-To-User header to send within the initial INVITE when calling a SIP URI. Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed. This value, including the encoding specifier, may not exceed 256 characters. No

NOTE: Any error that causes the call to be hung up (for example invalid BXML or rate limiting) will be delivered to the disconnectUrl via a Disconnect event. This is currently the only way to receive user errors, so while disconnectUrl is not mandatory, we highly recommend providing it so that user errors can be delivered.

Example 1 of 1: Create an outbound phone call

curl -X POST \
    --url '{accountId}/calls' \
    -u '{username}:{password}' \
    -H 'Content-type: application/json' \
    --data-raw '
      "from"          : "+15555551212",
      "to"            : "+15555551313",
      "answerUrl"     : "",
      "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"


HTTP/1.1 201
Content-type: application/json

    "accountId"            : "55555555",
    "from"                 : "+19195551212",
    "to"                   : "+19195551313",
    "applicationId"        : "7fc9698a-b04a-468b-9e8f-91238c0d0086",
    "callId"               : "c-95ac8d6e-1a31c52e-b38f-4198-93c1-51633ec68f8d",
    "startTime"            : "2019-06-20T15:54:22.234Z",
    "callUrl"              : "",
    "callTimeout"          : 30,
    "callbackTimeout"      : 15,
    "answerUrl"            : "",
    "answerMethod"         : "POST",
    "answerFallbackUrl"    : null,
    "answerFallbackMethod" : "POST",
    "disconnectUrl"        : null,
    "disconnectMethod"     : "POST",
    "username"             : null,
    "password"             : null,
    "fallbackUsername"     : null,
    "fallbackPassword"     : null,
    "tag"                  : null
ApiCreateCallRequest createCallRequest = new ApiCreateCallRequest();
createCallRequest.setApplicationId(VOICE_APPLICATION_ID); //String

try {
    ApiResponse<ApiCallResponse> response = voiceClient.createCall(VOICE_ACCOUNT_ID, createCallRequest);
} catch (ApiException | IOException e) {
ApiCreateCallRequest apiCreateCallRequest = new ApiCreateCallRequest();
apiCreateCallRequest.From = "+19195551212";
apiCreateCallRequest.To = "+19195551313";
apiCreateCallRequest.AnswerUrl = "";
apiCreateCallRequest.ApplicationId = VOICE_APPLICATION_ID; //string

var response = voiceClient.CreateCall(VOICE_ACCOUNT_ID, apiCreateCallRequest);
body =
body.from = "+19195551212" = "+19195551313"
body.answer_url = ""
body.application_id = "7fc9698a-b04a-468b-9e8f-91238c0d0086"

    result = voice_client.create_call(account_id, :body => body)
rescue Exception => e
    puts e
body = ApiCreateCallRequest()
body.mfrom = "+19195551212" = "+19195551313"
body.answer_url = ""
body.application_id = "7fc9698a-b04a-468b-9e8f-91238c0d0086"

    result = voice_client.create_call(account_id, body)
except Exception as e:
import { Client, ApiController } from '@bandwidth/voice';

const client = new Client({
    basicAuthUserName: username,
    basicAuthPassword: password

const controller = new ApiController(client);

const accountId = '1111111';

const response = await controller.createCall(accountId, {
    applicationId: 'abc12345-6def-abc1-2345-6defabc12345',
    to: '+19999999999',
    from: '+18888888888',
    answerUrl: '',
    answerMethod: 'POST',
    callTimeout: 30
$body = new BandwidthLib\Voice\Models\ApiCreateCallRequest();
$body->from = "+15554443333";
$body->to = "+15554442222";
$body->answerUrl = "";
$body->applicationId = "3-6-4-b-4";

try {
    $response = $voiceClient->createCall($accountId, $body);
} catch (BandwidthLib\APIException $e) {

results matching ""

    No results matching ""