Send Call

curl --request POST \
  --url https://api.bland.ai/v1/calls \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_number": "<string>",
  "voice": "<string>",
  "pathway_id": "<string>",
  "pathway_version": 123,
  "task": "<string>",
  "first_sentence": "<string>",
  "persona_id": "<string>",
  "model": "<string>",
  "language": "<string>",
  "wait_for_greeting": true,
  "pronunciation_guide": [
    {}
  ],
  "temperature": 123,
  "interruption_threshold": 123,
  "resumption_speed": 123,
  "interruptibility": 123,
  "from": "<string>",
  "dialing_strategy": {},
  "timezone": "<string>",
  "start_time": "<string>",
  "transfer_phone_number": "<string>",
  "transfer_list": {},
  "max_duration": 123,
  "tools": [
    {}
  ],
  "background_track": "<string>",
  "noise_cancellation": true,
  "block_interruptions": true,
  "record": true,
  "voicemail": {},
  "citation_schema_ids": [
    "<string>"
  ],
  "include_post_transfer_transcript": true,
  "post_call_evals": {},
  "summary_prompt": "<string>",
  "retry": {},
  "dispositions": [
    "<string>"
  ],
  "request_data": {},
  "metadata": {},
  "webhook": "<string>",
  "webhook_events": [
    {}
  ],
  "dynamic_data": [
    {}
  ],
  "keywords": [
    "<string>"
  ],
  "ignore_button_press": true,
  "precall_dtmf_sequence": "<string>",
  "guard_rails": [
    {}
  ]
}
'

import requests

url = "https://api.bland.ai/v1/calls"

payload = {
    "phone_number": "<string>",
    "voice": "<string>",
    "pathway_id": "<string>",
    "pathway_version": 123,
    "task": "<string>",
    "first_sentence": "<string>",
    "persona_id": "<string>",
    "model": "<string>",
    "language": "<string>",
    "wait_for_greeting": True,
    "pronunciation_guide": [{}],
    "temperature": 123,
    "interruption_threshold": 123,
    "resumption_speed": 123,
    "interruptibility": 123,
    "from": "<string>",
    "dialing_strategy": {},
    "timezone": "<string>",
    "start_time": "<string>",
    "transfer_phone_number": "<string>",
    "transfer_list": {},
    "max_duration": 123,
    "tools": [{}],
    "background_track": "<string>",
    "noise_cancellation": True,
    "block_interruptions": True,
    "record": True,
    "voicemail": {},
    "citation_schema_ids": ["<string>"],
    "include_post_transfer_transcript": True,
    "post_call_evals": {},
    "summary_prompt": "<string>",
    "retry": {},
    "dispositions": ["<string>"],
    "request_data": {},
    "metadata": {},
    "webhook": "<string>",
    "webhook_events": [{}],
    "dynamic_data": [{}],
    "keywords": ["<string>"],
    "ignore_button_press": True,
    "precall_dtmf_sequence": "<string>",
    "guard_rails": [{}]
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number: '<string>',
    voice: '<string>',
    pathway_id: '<string>',
    pathway_version: 123,
    task: '<string>',
    first_sentence: '<string>',
    persona_id: '<string>',
    model: '<string>',
    language: '<string>',
    wait_for_greeting: true,
    pronunciation_guide: [{}],
    temperature: 123,
    interruption_threshold: 123,
    resumption_speed: 123,
    interruptibility: 123,
    from: '<string>',
    dialing_strategy: {},
    timezone: '<string>',
    start_time: '<string>',
    transfer_phone_number: '<string>',
    transfer_list: {},
    max_duration: 123,
    tools: [{}],
    background_track: '<string>',
    noise_cancellation: true,
    block_interruptions: true,
    record: true,
    voicemail: {},
    citation_schema_ids: ['<string>'],
    include_post_transfer_transcript: true,
    post_call_evals: {},
    summary_prompt: '<string>',
    retry: {},
    dispositions: ['<string>'],
    request_data: {},
    metadata: {},
    webhook: '<string>',
    webhook_events: [{}],
    dynamic_data: [{}],
    keywords: ['<string>'],
    ignore_button_press: true,
    precall_dtmf_sequence: '<string>',
    guard_rails: [{}]
  })
};

fetch('https://api.bland.ai/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v1/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number' => '<string>',
    'voice' => '<string>',
    'pathway_id' => '<string>',
    'pathway_version' => 123,
    'task' => '<string>',
    'first_sentence' => '<string>',
    'persona_id' => '<string>',
    'model' => '<string>',
    'language' => '<string>',
    'wait_for_greeting' => true,
    'pronunciation_guide' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'interruption_threshold' => 123,
    'resumption_speed' => 123,
    'interruptibility' => 123,
    'from' => '<string>',
    'dialing_strategy' => [
        
    ],
    'timezone' => '<string>',
    'start_time' => '<string>',
    'transfer_phone_number' => '<string>',
    'transfer_list' => [
        
    ],
    'max_duration' => 123,
    'tools' => [
        [
                
        ]
    ],
    'background_track' => '<string>',
    'noise_cancellation' => true,
    'block_interruptions' => true,
    'record' => true,
    'voicemail' => [
        
    ],
    'citation_schema_ids' => [
        '<string>'
    ],
    'include_post_transfer_transcript' => true,
    'post_call_evals' => [
        
    ],
    'summary_prompt' => '<string>',
    'retry' => [
        
    ],
    'dispositions' => [
        '<string>'
    ],
    'request_data' => [
        
    ],
    'metadata' => [
        
    ],
    'webhook' => '<string>',
    'webhook_events' => [
        [
                
        ]
    ],
    'dynamic_data' => [
        [
                
        ]
    ],
    'keywords' => [
        '<string>'
    ],
    'ignore_button_press' => true,
    'precall_dtmf_sequence' => '<string>',
    'guard_rails' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v1/calls"

	payload := strings.NewReader("{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/calls")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Call successfully queued.",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1",
  "batch_id": null
}

POST

calls

Send Call

curl --request POST \
  --url https://api.bland.ai/v1/calls \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '
{
  "phone_number": "<string>",
  "voice": "<string>",
  "pathway_id": "<string>",
  "pathway_version": 123,
  "task": "<string>",
  "first_sentence": "<string>",
  "persona_id": "<string>",
  "model": "<string>",
  "language": "<string>",
  "wait_for_greeting": true,
  "pronunciation_guide": [
    {}
  ],
  "temperature": 123,
  "interruption_threshold": 123,
  "resumption_speed": 123,
  "interruptibility": 123,
  "from": "<string>",
  "dialing_strategy": {},
  "timezone": "<string>",
  "start_time": "<string>",
  "transfer_phone_number": "<string>",
  "transfer_list": {},
  "max_duration": 123,
  "tools": [
    {}
  ],
  "background_track": "<string>",
  "noise_cancellation": true,
  "block_interruptions": true,
  "record": true,
  "voicemail": {},
  "citation_schema_ids": [
    "<string>"
  ],
  "include_post_transfer_transcript": true,
  "post_call_evals": {},
  "summary_prompt": "<string>",
  "retry": {},
  "dispositions": [
    "<string>"
  ],
  "request_data": {},
  "metadata": {},
  "webhook": "<string>",
  "webhook_events": [
    {}
  ],
  "dynamic_data": [
    {}
  ],
  "keywords": [
    "<string>"
  ],
  "ignore_button_press": true,
  "precall_dtmf_sequence": "<string>",
  "guard_rails": [
    {}
  ]
}
'

import requests

url = "https://api.bland.ai/v1/calls"

payload = {
    "phone_number": "<string>",
    "voice": "<string>",
    "pathway_id": "<string>",
    "pathway_version": 123,
    "task": "<string>",
    "first_sentence": "<string>",
    "persona_id": "<string>",
    "model": "<string>",
    "language": "<string>",
    "wait_for_greeting": True,
    "pronunciation_guide": [{}],
    "temperature": 123,
    "interruption_threshold": 123,
    "resumption_speed": 123,
    "interruptibility": 123,
    "from": "<string>",
    "dialing_strategy": {},
    "timezone": "<string>",
    "start_time": "<string>",
    "transfer_phone_number": "<string>",
    "transfer_list": {},
    "max_duration": 123,
    "tools": [{}],
    "background_track": "<string>",
    "noise_cancellation": True,
    "block_interruptions": True,
    "record": True,
    "voicemail": {},
    "citation_schema_ids": ["<string>"],
    "include_post_transfer_transcript": True,
    "post_call_evals": {},
    "summary_prompt": "<string>",
    "retry": {},
    "dispositions": ["<string>"],
    "request_data": {},
    "metadata": {},
    "webhook": "<string>",
    "webhook_events": [{}],
    "dynamic_data": [{}],
    "keywords": ["<string>"],
    "ignore_button_press": True,
    "precall_dtmf_sequence": "<string>",
    "guard_rails": [{}]
}
headers = {
    "authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    phone_number: '<string>',
    voice: '<string>',
    pathway_id: '<string>',
    pathway_version: 123,
    task: '<string>',
    first_sentence: '<string>',
    persona_id: '<string>',
    model: '<string>',
    language: '<string>',
    wait_for_greeting: true,
    pronunciation_guide: [{}],
    temperature: 123,
    interruption_threshold: 123,
    resumption_speed: 123,
    interruptibility: 123,
    from: '<string>',
    dialing_strategy: {},
    timezone: '<string>',
    start_time: '<string>',
    transfer_phone_number: '<string>',
    transfer_list: {},
    max_duration: 123,
    tools: [{}],
    background_track: '<string>',
    noise_cancellation: true,
    block_interruptions: true,
    record: true,
    voicemail: {},
    citation_schema_ids: ['<string>'],
    include_post_transfer_transcript: true,
    post_call_evals: {},
    summary_prompt: '<string>',
    retry: {},
    dispositions: ['<string>'],
    request_data: {},
    metadata: {},
    webhook: '<string>',
    webhook_events: [{}],
    dynamic_data: [{}],
    keywords: ['<string>'],
    ignore_button_press: true,
    precall_dtmf_sequence: '<string>',
    guard_rails: [{}]
  })
};

fetch('https://api.bland.ai/v1/calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bland.ai/v1/calls",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number' => '<string>',
    'voice' => '<string>',
    'pathway_id' => '<string>',
    'pathway_version' => 123,
    'task' => '<string>',
    'first_sentence' => '<string>',
    'persona_id' => '<string>',
    'model' => '<string>',
    'language' => '<string>',
    'wait_for_greeting' => true,
    'pronunciation_guide' => [
        [
                
        ]
    ],
    'temperature' => 123,
    'interruption_threshold' => 123,
    'resumption_speed' => 123,
    'interruptibility' => 123,
    'from' => '<string>',
    'dialing_strategy' => [
        
    ],
    'timezone' => '<string>',
    'start_time' => '<string>',
    'transfer_phone_number' => '<string>',
    'transfer_list' => [
        
    ],
    'max_duration' => 123,
    'tools' => [
        [
                
        ]
    ],
    'background_track' => '<string>',
    'noise_cancellation' => true,
    'block_interruptions' => true,
    'record' => true,
    'voicemail' => [
        
    ],
    'citation_schema_ids' => [
        '<string>'
    ],
    'include_post_transfer_transcript' => true,
    'post_call_evals' => [
        
    ],
    'summary_prompt' => '<string>',
    'retry' => [
        
    ],
    'dispositions' => [
        '<string>'
    ],
    'request_data' => [
        
    ],
    'metadata' => [
        
    ],
    'webhook' => '<string>',
    'webhook_events' => [
        [
                
        ]
    ],
    'dynamic_data' => [
        [
                
        ]
    ],
    'keywords' => [
        '<string>'
    ],
    'ignore_button_press' => true,
    'precall_dtmf_sequence' => '<string>',
    'guard_rails' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bland.ai/v1/calls"

	payload := strings.NewReader("{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bland.ai/v1/calls")
  .header("authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bland.ai/v1/calls")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"<string>\",\n  \"voice\": \"<string>\",\n  \"pathway_id\": \"<string>\",\n  \"pathway_version\": 123,\n  \"task\": \"<string>\",\n  \"first_sentence\": \"<string>\",\n  \"persona_id\": \"<string>\",\n  \"model\": \"<string>\",\n  \"language\": \"<string>\",\n  \"wait_for_greeting\": true,\n  \"pronunciation_guide\": [\n    {}\n  ],\n  \"temperature\": 123,\n  \"interruption_threshold\": 123,\n  \"resumption_speed\": 123,\n  \"interruptibility\": 123,\n  \"from\": \"<string>\",\n  \"dialing_strategy\": {},\n  \"timezone\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"transfer_phone_number\": \"<string>\",\n  \"transfer_list\": {},\n  \"max_duration\": 123,\n  \"tools\": [\n    {}\n  ],\n  \"background_track\": \"<string>\",\n  \"noise_cancellation\": true,\n  \"block_interruptions\": true,\n  \"record\": true,\n  \"voicemail\": {},\n  \"citation_schema_ids\": [\n    \"<string>\"\n  ],\n  \"include_post_transfer_transcript\": true,\n  \"post_call_evals\": {},\n  \"summary_prompt\": \"<string>\",\n  \"retry\": {},\n  \"dispositions\": [\n    \"<string>\"\n  ],\n  \"request_data\": {},\n  \"metadata\": {},\n  \"webhook\": \"<string>\",\n  \"webhook_events\": [\n    {}\n  ],\n  \"dynamic_data\": [\n    {}\n  ],\n  \"keywords\": [\n    \"<string>\"\n  ],\n  \"ignore_button_press\": true,\n  \"precall_dtmf_sequence\": \"<string>\",\n  \"guard_rails\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "status": "success",
  "message": "Call successfully queued.",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1",
  "batch_id": null
}

Overview

Send an AI phone call with a custom objective and actions. This endpoint can be used to create dynamic phone calls where the AI agent can follow instructions, use tools, and follow a conversation pathway.

Headers

string

required

Your API key for authentication.

string

A special key for using a BYOT (Bring Your Own Twilio) account. Only required for sending calls from your own Twilio account.Learn more about BYOT here.

Body Parameters

Basic Parameters

string

required

The phone number to call. Must be a valid phone number in E.164 format.

string

The voice of the AI agent to use. Accepts any form of voice ID, including custom voice clones and voice presets.Default voices can be referenced directly by their name instead of an id.Usage example: voice: “maya”Bland Curated voices:

Josh
Florian
Derek
June
Nat
Paige

string

This is the pathway ID for the pathway you have created on our dev portal. You can access the ID of your pathways by clicking the ‘Copy ID’ button of your pathway hereNote: Certain parameters do not apply when using pathways.Example Simple Request body:

{
  "phone_number": "+1975934749",
  "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7"
}

integer

The version number of the pathway to use for the call. Defaults to the production version.

string

required

Note: Do not specify if using a pathway.Provide instructions, relevant information, and examples of the ideal conversation flow.This is your prompt where you are telling the agent what to do.Recommendations:

Include context and a background/persona for the agent like "You are {name}, a customer service agent at {company} calling {name} about {reason}.
Phrase instructions like you are speaking to the agent before the call.
Any time you tell the agent not to do something, provide an example of what they should do instead.
Keep the prompt under 2,000 characters where possible.

string

Makes your agent say a specific phrase or sentence for it’s first response.

string

The ID of the persona to use for the call.Personas act as pre-configured templates that automatically apply a configuration when you pass a persona_id to an outbound call. Think of them as “call presets” that you can reuse across multiple calls.When using a persona_id, any parameters specified in your request body will override the corresponding parameters from the persona’s configuration.You can access your persona IDs by clicking the “Personas” button at the bottom of the Send Call page, and then “Use and Manage”.

Model Parameters

string

default:"base"

Select a model to use for your call.Options: base or turbo.In nearly all cases, base is the best choice.

Model Differences

There are two different ways to use Bland:

model: base
- The original, follows scripts/procedures most effectively.
- Supports all features and capabilities.
- Best for Custom Tools
model: turbo
- The absolute fastest latency possible, can be verbose at times
- Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools)
- Extremely realistic conversation capabilities

string

default:"babel-en"

Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.

Expand to view language options

The available language options are as follows:

babel - Babel (All Languages) - Experimental¹
fluent - Fluent (Multilingual)²
en - English
babel-en - English (Babel)
en-US - English (US)
en-GB - English (UK)
en-AU - English (Australia)
en-NZ - English (New Zealand)
en-IN - English (India)
es - Spanish
babel-es - Spanish (Babel)
es-419 - Spanish (Latin America)
fr - French
babel-fr - French (Babel)
fr-CA - French (Canada)
de - German
babel-de - German (Babel)
el - Greek
hi - Hindi
hi-Latn - Hindi (Latin script)
hu - Hungarian
ja - Japanese
ko - Korean
ko-KR - Korean (Korea)
vi - Vietnamese
pt - Portuguese
pt-BR - Portuguese (Brazil)
pt-PT - Portuguese (Portugal)
zh - Chinese (Mandarin, Simplified)
zh-CN - Chinese (Mandarin, Simplified, China)
zh-Hans - Chinese (Mandarin, Simplified, Hans)
zh-TW - Chinese (Mandarin, Traditional)
zh-Hant - Chinese (Mandarin, Traditional, Hant)
it - Italian
nl - Dutch
pl - Polish
ru - Russian
sv - Swedish
sv-SE - Swedish (Sweden)
da - Danish
da-DK - Danish (Denmark)
fi - Finnish
no - Norwegian
id - Indonesian
ms - Malay
tr - Turkish
uk - Ukrainian
bg - Bulgarian
cs - Czech
ro - Romanian
sk - Slovak
auto - Auto Detect (English & Spanish)

¹ The Bland Babel Transcription Engine (BETA) is our new proprietary transcription engine! Babel can handle multilingual conversations by identifying and switching languages on the fly. It’s now in beta and available under the “babel” language mode. Note: For pathway calls and prompts, make sure to prompt your agent to respond in the language they are spoken to.² The fluent mode is a multilingual option that auto-detects the spoken language and switches between languages on the fly, powered by a multilingual transcription model. Note: For pathway calls and prompts, make sure to prompt your agent to respond in the language they are spoken to.

boolean

default:"false"

By default, the agent starts talking as soon as the call connects.When wait_for_greeting is set to true, the agent will wait for the call recipient to speak first before responding.

array

The pronunciation guide is an array of objects that guides the agent on how to say specific words. Use this to improve clarity for acronyms, names, brand terms, or jargon.

  [
    {
      "word": "example",
      "pronunciation": "ex-am-ple",
      "case_sensitive": "false",
      "spaced": "false"
  },
  {
    "word": "API",
    "pronunciation": "A P I",
    "case_sensitive": "true",
    "spaced": "true"
  }
]

Object Parameters

word — the word you want to guide the LLM on how to pronounce
pronunciation — how the AI should pronounce the word, using syllables or space-separated characters. For example, "A P I" ensures each letter is spoken clearly rather than read as a word.
case_sensitive — whether or not to consider case. Particularly useful with names. EG: ‘Max’ the name versus ‘max’ the word. Defaults to false. Not required.
spaced — whether to match whole words only. When true, “high” will match “high” but not “hightop”. When false, it will match any word that contains “high”. Defaults to true. Not required.

float

A value between 0 and 1 that controls the randomness of the LLM. 0 will cause more deterministic outputs while 1 will cause more random.Example Values: “0.9”, “0.3”, “0.5”

number

default:"500"

Adjusts how patient the AI is when waiting for the user to finish speaking.Lower values mean the AI will respond more quickly, while higher values mean the AI will wait longer before responding.

integer

default:"2"

Controls how quickly the AI starts speaking again after the caller finishes a turn. A lower value responds sooner; a higher value waits longer, leaving more room for the caller to continue.

1: Fast. Responds sooner after the caller pauses.
2: Medium (default).
3: Slow. Waits longer before responding.

Supersedes interruption_threshold. When both are sent, resumption_speed takes precedence.

integer

default:"2"

Controls how readily the AI stops speaking when the caller talks over it. A higher value yields more easily; a lower value holds the turn through more of the caller’s speech.

0: Block. The AI ignores interruptions and finishes speaking (same as block_interruptions: true).
1: Difficult. Harder to interrupt.
2: Balanced (default).
3: Easy. The AI stops quickly when the caller begins speaking.

Dispatch Parameters

string

Specify a phone number to call from that you own or have uploaded from your Twilio account. Country code is required, spaces or parentheses must be excluded.By default, calls are initiated from a separate pool of numbers owned by Bland. If you are using your own twilio numbers, you must specify a matching encrypted_key in the create call request headers.

object

Controls how the caller number (from) is selected when placing an outbound call.Use this field to influence how the system chooses a number that appears local or relevant to the callee, improving pickup rates. There are two supported strategies:

1. `local`

Automatically selects a from number that matches the callee’s area code for US-based calls. You must have purchased a local dialing add-on in the add-ons section.Example:

{
  "dialing_strategy": { "type": "local" }
}

2. `custom_pooling`

Selects a number from your own pre-configured pool of phone numbers. Designed for organizations that want full control over the caller IDs being used.This is an enterprise only feature, to use this feature contact your Bland representative or reach out to sales.Example:

{
  "dialing_strategy": {
    "type": "custom_pooling",
    "pool_id": "bd039087-decb-435a-a6e3-ca1ffbf89974"
  }
}

By default, Bland will choose a US-based number from our own pool of numbers.

string

default:"America/Los_Angeles"

Set the timezone for the call. Handled automatically for calls in the US.This helps significantly with use cases that rely on appointment setting, scheduling, or behaving differently based on the time of day.Timezone options are here in the TZ identifier column.

string

The time you want the call to start. If you don’t specify a time (or the time is in the past), the call will send immediately.Set your time in the format YYYY-MM-DD HH:MM:SS -HH:MM (ex. 2021-01-01 12:00:00 -05:00).The timezone is optional, and defaults to UTC if not specified.Note: Scheduled calls can be cancelled with the POST /v1/calls/:call_id/stop endpoint.

string

A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor. This option will be ignored for pathways.

Prompting Notes

For best results:

Specify conditions that the agent should transfer to a human under (examples are great!)
In the task, refer to the action solely as “transfer” or “transferring”.
Alternate phrasing such as “swap” or “switch” can mislead the agent, causing the action to be ignored.

object

Give your agent the ability to transfer calls to a set of phone numbers. This option will be ignored for pathways.Overrides transfer_phone_number if a transfer_list.default is specified.Will default to transfer_list.default, or the chosen phone number.Example usage to route calls to different departments:

{
  "transfer_list": {
      "default": "+12223334444",
      "sales": "+12223334444",
      "support": "+12223334444",
      "billing": "+12223334444"
  }
}

integer

default:"30"

When the call starts, a timer is set for the max_duration minutes. At the end of that timer, if the call is still active it will be automatically ended.Example Values: 20, 2

Knowledge Parameters

array

Add custom tools and knowledge bases to your call for your agent to call upon.Example:

{
  "tools": [
    "TL-ba6c4237-67c2-40e8-868b-60d429a84eda",
    "KB-30d465c0-22d0-41e0-a63d-61bcacc277e7"
  ]
}

Audio Parameters

string

Select an audio track that you’d like to play in the background during the call. The audio will play continuously when the agent isn’t speaking, and is incorporated into it’s speech as well.Use this to provide a more natural, seamless, engaging experience for the conversation. We’ve found this creates a significantly smoother call experience by minimizing the stark differences between total silence and the agent’s speech.Options:

null - Default, will play audible but quiet phone static.
office - Office-style soundscape. Includes faint typing, chatter, clicks, and other office sounds.
cafe - Cafe-like soundscape. Includes faint talking, clinking, and other cafe sounds.
restaurant - Similar to cafe, but more subtle.
none - Minimizes background noise

boolean

default:"false"

Toggles noise filtering or suppression in the audio stream to filter out background noise.

boolean

default:"false"

When set to true, the AI will not respond or process interruptions from the user.

boolean

default:"false"

To record your phone call, set record to true. When your call completes, you can access through the recording_url field in the call details or your webhook.

Voicemail Parameters

object

Configuration for handling voicemails during outbound calls. This object controls how the AI behaves when it encounters a voicemail, including whether to leave a message, send an SMS notification, or detect voicemails more intelligently using AI.It has the following parameters:

message (string): The message the AI will leave if a voicemail is detected. This message will be played after the beep, then the call will end. This field is required if action is set to leave_message.

action (enum): What the AI should do when it detects a voicemail. The default is "hangup". Available options:
- "hangup": Immediately end the call without leaving a message.
- "leave_message": Play the message and then end the call.
- "ignore": Continue the call as if no voicemail was detected (used for IVRs or special routing).

sms (object): Optional. Configuration for sending an SMS notification when a voicemail is left. Contains:
- to (string): The phone number to send the SMS to (usually the same as the original callee).
- from (string): The phone number to send the SMS from (must be a number you own and have SMS permissions for).
- message (string): The body of the SMS message. Keep concise and clear.

sensitive (boolean): When true, uses LLM-based analysis to detect frequent voicemails. The default is false.

Example:

{
  "voicemail": {
    "message": "Hi, just calling to follow up. Please call us back when you can.",
    "action": "leave_message",
    "sms": {
      "to": "+18005550123",
      "from": "+18005550678",
      "message": "We just left you a voicemail. Call us back anytime!"
    },
    "sensitive": true
  }
}

Analysis Parameters

string[]

The citation schema is an incredibly powerful tool for running post call analysis, including specific variable extractions, conditional logic, and more.You can build a citation schema here.After building the citation schema (or schemas), you can copy their UUIDs and reference them in your API request for outgoing calls (and you can also attach them to your inbound phone numbers).Here’s an example:

{
  "citation_schema_ids": ["b7c2e1d4-8f3a-4c9e-9a2b-1e5f6d7c8a9b", "f2d3c4b5-6a7e-8d9c-0b1a-2c3d4e5f6a7b"]
}

Note: Citation schemas are very powerful and accurate, but also are more resource intensive to run. As such, for the time being, they are an enterprise-only feature.

boolean

default:"false"

When true and the call is cold-transferred to a human, Bland transcribes the conversation after the transfer and delivers it two ways: live over the Post-Transfer Transcript Stream WebSocket while the transferred conversation is happening, and post-call as a post_transfer_transcript property (plus transfer_offset_seconds) on the citations webhook event.Requires call recording: record is enabled automatically when unset, and passing record: false alongside this option returns a 400.The post-call delivery rides on the citations webhook, so to receive it you also need at least one schema in citation_schema_ids and "citations" in webhook_events.

This feature is in limited rollout. If it is not enabled for your organization, the option has no effect.

object

Attach an evals workbench to this call. When the call completes, Bland automatically runs the workbench’s eval configuration against the call — no separate eval-run submission needed.Provide at least one of:

workbench_setup_id (string): The workbench setup to attach. Bland pins the setup’s current published version at call creation, so editing the workbench mid-call does not change what gets evaluated.
workbench_setup_version_id (string): An exact published workbench setup version to pin.

Attaching evals requires the call to be recorded. If you set record: false alongside post_call_evals, the request is rejected; otherwise recording is enabled automatically.The post-call webhook acknowledges the attachment with post_call_evals: { workbench_setup_id, workbench_setup_version_id, status: "pending" }. Eval scores arrive later on a separate evals webhook event once the run completes.Example:

{
  "post_call_evals": {
    "workbench_setup_id": "b7c2e1d4-8f3a-4c9e-9a2b-1e5f6d7c8a9b"
  }
}

Post Call Parameters

string

(Optional) Custom instructions for how the call summary should be generated after the call completes. Use this to provide specific guidance or context for the AI when writing the post-call summary. Maximum length: 2000 characters.Example:

{
  "summary_prompt": "Summarize the call in 2-3 sentences, focusing on the customer's main concern and any next steps discussed."
}

object

If the call goes to voicemail, you can set up the call to retry, after a configurable delay. You can also update the voicemail_action, and voicemail_message in the retry object, for the re-tried call.Takes in the following parameters:

wait (integer): The delay in seconds before the call is retried.
voicemail_action (enum): The action to take when the call goes to voicemail. Options: hangup, leave_message, ignore.
voicemail_message (string): The message to leave when the call goes to voicemail.

Example:

{
    "retry": {
        "wait": 10,
        "voicemail_action": "leave_message",
        "voicemail_message": "Hello, this is a test message."
    }
}

string[]

A list of possible outcome tags (dispositions) you define. After the call ends, the AI reviews the transcript and picks one of these tags to describe how the call went.Tag selection is based only on the transcript, no metadata or external inputs are used.The chosen tag will appear in the disposition_tag field of the call data.

Built-in Disposition Tags

If no custom dispositions are provided, the AI will automatically select from these built-in tags:

INTERESTED - Customer shows clear interest in the offering
NOT_INTERESTED - Customer expresses lack of interest
FOLLOW_UP_REQUIRED - Customer needs additional follow-up
CALL_BACK_SCHEDULED - A callback appointment was scheduled
TRANSFERRED - Call was transferred to another agent/department
OBJECTION_RAISED - Customer raised concerns or objections
NEEDS_MORE_INFO - Customer requires additional information
NOT_QUALIFIED - Customer does not meet qualification criteria
NO_CONTACT_MADE - Unable to establish meaningful contact
COMPLETED_ACTION - Customer completed the desired action
DO_NOT_CONTACT - Customer requested no future contact
AGENT_ENDED_CALL - Call ended by AI (auto-assigned for calls >2 minutes without transcript)
NO_ANSWER - Call was not answered (auto-assigned by system)
BUSY - Number was busy (auto-assigned by system)
CANCELED - Call was canceled (auto-assigned by system)
FAILED - Call failed to connect (auto-assigned by system)

Example:

  {
    "dispositions": ["got_full_name_and_number", "no_information_provided", "transferred_to_agent"]
  }

Advanced Parameters

object

Custom key-value data you send with the call. This information is available as variables inside your prompt, pathway, or tools — but only if the call is answered.

  {
    "task": "Say hello to the user, who's name is {{name}}",
    "request_data": {
      "name": "John Doe"
    }
  }

In this case, the AI would say: “Hello, John”.

object

Add any additional information you want to associate with the call. This data is accessible for all calls, regardless of if they are picked up or not. This can be used to track calls or add custom data to the call.Anything that you put here will be returned in the post call webhook under metadata.Example:

{
  "metadata": {
    "campaign_id": "1234",
    "source": "web"
  }
}

string

When the call ends, call information is sent to this webhook URL.

array

Specify which events you want to stream to the webhook, during the call.

Citation Webhook Requirements:

Include citations for any citation webhooks (sent separately after call completion)
For delayed post-call webhooks with citations, you need citations + dashboard delay toggle enabled

See the Citations documentation for complete setup instructions.

Options:

queue
call
latency
webhook
tool
dynamic_data
citations (Required for any citation webhooks)

Example payloads:

// ex 1
{
  "message": "Call enqueued",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "queue",
  "log_level": "info"
}

// ex 1
{
  "message": "Call connected",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "call",
  "log_level": "info"
}
// ex 2
{
  "message": "Sending first sentence: Hello, thank you for reaching out. I'd like to get to know you a bit better. How are you feeling today?",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "call",
  "log_level": "info"
}
// ex 3
{
  "message": "Agent speech: Hello, thank you for reaching out.",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "call",
  "log_level": "info"
}
// ex 4
{
  "message": "Handling user speech: Yeah. I'm thirty six. And I'm five foot nine.",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "call",
  "log_level": "info"
}
// ex 5
{
  "message": "Webhook Response: 200  | Webhook Response Data: [object Object] | Response Time: 689ms",
  "call_id": "87654321-4321-4321-4321-cba987654321",
  "category": "call",
  "log_level": "info"
}

// ex 1
{
  "message": "TTS: 218ms",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "latency",
  "log_level": "performance"
}
// ex 2
{
  "message": "LLM: 266ms",
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "category": "latency",
  "log_level": "performance"
}

{
  "message": "Storing dynamic data messages: \n\n answer : \"true\"",
  "call_id": "87654321-4321-4321-4321-cba987654321",
  "category": "call",
  "log_level": "info"
}

{
  "message": "Executing custom tool: Test Tool 4 with input: [object Object]",
  "call_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "category": "call",
  "log_level": "info"
}

{
  "message": "Storing dynamic data: \n\n vector_data : {\"data\":{\"results\":[{\"id\":\"fedcba98-7654-3210-fedc-ba9876543210\",\"input_text\":\"Here are details on the restaurant...\",\"similarity\":0.103339002763233,\"chunk_index\":0}]},\"errors\":null}",
  "call_id": "abcdef12-3456-7890-abcd-ef1234567890",
  "category": "call",
  "log_level": "info"
}

{
  "call_id": "12345678-1234-1234-1234-123456789abc",
  "user_id": "11111111-2222-3333-4444-555555555555",
  "event_type": "citations",
  "timestamp": "2025-07-03T16:41:15.231Z",
  "citations": [
    {
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "variable_name": "User height",
      "variable_type": "boolean",
      "value": true,
      "cited_utterances": [
        {
          "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "idx": 3,
          "start_time": 24.096,
          "end_time": 27.424,
          "confidence": 0.17166666666666666,
          "channel": 1,
          "transcript": "I am 36 and I am 5'9\".",
          "speaker_id": "SPEAKER_1_0",
          "speaker_name": null,
          "speaker_description": null,
          "topics": [
            "customer_information_provided"
          ],
          "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}",
          "utterance_type": "answer"
        }
      ],
      "schema_id": "99999999-8888-7777-6666-555555555555"
    },
    {
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "variable_name": "Caller Age",
      "variable_type": "number",
      "value": 36,
      "cited_utterances": [
        {
          "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
          "idx": 3,
          "start_time": 24.096,
          "end_time": 27.424,
          "confidence": 0.17166666666666666,
          "channel": 1,
          "transcript": "I am 36 and I am 5'9\".",
          "speaker_id": "SPEAKER_1_0",
          "speaker_name": null,
          "speaker_description": null,
          "topics": [
            "customer_information_provided"
          ],
          "topics_meta": "{\"customer_information_provided\":\"customer providing personal details\"}",
          "utterance_type": "answer"
        },
        {
          "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
          "idx": 4,
          "start_time": 30.56,
          "end_time": 35.455,
          "confidence": 0.5672727272727273,
          "channel": 0,
          "transcript": "All right. So you're 36 years old and five foot nine. That's great. How's your day been so far? Anything exciting happened?",
          "speaker_id": "SPEAKER_0_0",
          "speaker_name": null,
          "speaker_description": null,
          "topics": [
            "day_review_inquiry"
          ],
          "topics_meta": "{\"day_review_inquiry\":\"agent inquiring about the customer's day and any exciting events\"}",
          "utterance_type": "question"
        }
      ],
      "schema_id": "99999999-8888-7777-6666-555555555555"
    },
    {
      "call_id": "12345678-1234-1234-1234-123456789abc",
      "variable_name": "Caller feeling",
      "variable_type": "string",
      "value": null,
      "cited_utterances": [],
      "schema_id": "99999999-8888-7777-6666-555555555555"
    }
  ]
}

object[]

Integrate data from external APIs into your agent’s knowledge.Set to null or an empty string to clear dynamic data settings.

  "dynamic_data": [
    {
      "url": "endpoint",
      "method": "GET",
      "body": [],
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/json"
        }
      ],
      "query": [],
      "cache": true,
      "response_data": [
        {
          "context": "",
          "data": "$",
          "name": ""
        }
      ]
    }
  ],

string[]

default:"[]"

These words will be boosted in the transcription engine - recommended for proper nouns or words that are frequently mis-transcribed.For example, if the word Blandy is frequently transcribed as a homonym like “Reese” you could do this:

  {
    "keywords": ["Blandy"]
  }

For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2.

  {
    "keywords": ["Blandy:3"]
  }

boolean

default:"false"

When true, the system will ignore DTMF input (Dual-Tone Multi-Frequency) — the tones generated when a user presses keys on their phone keypad (e.g., 0-9, *, #).
This disables any in-call actions triggered by keypad input, such as menu navigation or transfers.
Useful when your agent should handle the entire call conversationally, without responding to button presses.

string

A sequence of DTMF digits that will be played before the call starts. Acceptable characters are 0-9, *, #, and w, where w is a pause of 0.5 seconds. Example:

  {
    "precall_dtmf_sequence": "1234567890*#w"
  }

array

Configure guard rails to monitor the call for compliance violations and trigger actions automatically. Guard rails continuously analyze AI and user responses during the call.Learn more about guard rails in the Guard Rails documentation.Each item in the array can be one of three types:

TCPA Guard Rails

tcpa:ai_disclosure - AI must disclose it’s an AI
tcpa:self_introduction - Must identify who is calling
tcpa:recording_disclosure - Must disclose the call is being recorded
tcpa:opt_out - This out-of-the-box guard rail is different as it’s not time-based and instead monitors the entire conversation to see if the agent continues to engage in the conversation after the user opts out. config.end_seconds is not needed for this type.

{
  "type": "tcpa:ai_disclosure",
  "actions": [
    { "type": "end_call" }
  ],
  "config": {
    "end_seconds": 30
  }
}

Field	Type	Description
`type`	string	One of: `tcpa:ai_disclosure`, `tcpa:self_introduction`, `tcpa:recording_disclosure`
`actions`	array	Actions to take if disclosure is NOT made within the time window
`config.end_seconds`	number	Time window in seconds (default: 30)

Custom Guard Rails (Enterprise)

Custom guard rails with your own prompt. Enterprise customers can create up to 5 custom guard rails.

{
  "type": "custom",
  "prompt": "Flag if the agent provides any medical advice or diagnosis...",
  "actions": [
    { "type": "transfer", "config": { "phone_number": "+15551234567" } }
  ]
}

Field	Type	Description
`type`	string	`custom`
`prompt`	string	Your custom detection prompt
`actions`	array	Actions to take when the guard rail triggers

Action Types

Each guard rail requires an actions array. Available action types:

Action Type	Description	Config
`end_call`	Immediately terminate the call	None
`transfer`	Transfer to a human agent	`{ "phone_number": "+15551234567" }`
`move_to_node`	Jump to a specific pathway node	`{ "node_id": "node-uuid" }`

Full example with multiple guard rails:

{
  "guard_rails": [
    {
      "type": "tcpa:ai_disclosure",
      "actions": [{ "type": "end_call" }],
      "config": { "end_seconds": 30 }
    },
    {
      "type": "tcpa:opt_out",
      "actions": [{ "type": "end_call" }]
    },
    {
      "type": "custom",
      "prompt": "Flag if the agent makes any investment recommendations",
      "actions": [
        { "type": "transfer", "config": { "phone_number": "+15551234567" } }
      ]
    }
  ]
}

Response

string

Can be success or error.

string

A message explaining the status of the call.

string

A unique identifier for the call (present only if status is success).

string

The batch ID of the call (present only if status is success).

array

For validation errors, a detailed list of each field with an error and it’s error message.Example:

{
    "status": "error",
    "message": "Invalid parameters",
    "errors": [
        "Missing required parameter: phone_number.",
        "Missing required parameter: task.",
        "Phone number must be a string or number.",
        "Task must be a string."
    ]
}

{
  "status": "success",
  "message": "Call successfully queued.",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1",
  "batch_id": null
}

Error Codes Reference

View All Error Codes

This section documents all possible error codes and HTTP status codes you can receive when making a POST request to /v1/calls.

Authentication & Authorization Errors

object

Authentication failed due to missing or invalid API key.

{
  "data": null,
  "errors": [
    {
      "error": "AUTH_FAILURE", 
      "message": "Unauthorized"
    }
  ]
}

Common causes:

Missing Authorization header
Invalid API key
Expired API key

object

Account has been flagged or banned for security purposes.

{
  "status": "error",
  "message": "The Bland Team has flagged your account for security purposes. As a precautionary measure against recent heightened malicious use cases, we have flagged your account for review and temporarily blocked from dispatching calls. If you need to be unblocked urgently, please email us at hello@bland.ai with your account phone number."
}

Rate Limiting Errors (HTTP 429)

object

Calls sent too frequently to the same number.

{
  "status": "error",
  "message": "Calls can only be sent every 10 seconds to the same number. Please try again in a few seconds."
}

object

Rate limit exceeded for your account.

{
  "status": "error",
  "message": "Rate limit exceeded"
}

object

Attempting to call a blacklisted number.

{
  "status": "error",
  "message": "This number is blacklisted."
}

object

Rate limits for newly created accounts.

{
  "status": "error",
  "message": "Rate limit exceeded for newly created accounts. Please try again soon."
}

object

International calling rate limit exceeded.

{
  "status": "error",
  "message": "International rate limit exceeded for your account type."
}

Parameter Validation Errors (HTTP 400)

object

Required parameters are missing from the request.

{
  "status": "error",
  "message": "Invalid parameters. Error: [\"Missing required parameter: phone_number.\"]",
  "errors": ["Missing required parameter: phone_number."]
}

Required parameters:

phone_number (always required)
task (required if pathway_id is not provided)

object

Field values are the wrong data type according to TypeBox validation.

{
  "status": "error", 
  "message": "Record must be a boolean"
}

Common type validation errors:

"Task must be a string"
"Record must be a boolean"
"Max duration must be a number"
"Temperature must be a number"
"Tools must be an array"
"Dynamic data must be an array"
"Metadata must be a record of string keys and any values"

object

Voicemail action must be one of the allowed values.

{
  "status": "error",
  "message": "Invalid voicemail action. Must be one of: hangup, leave_message, ignore"
}

object

Numeric values are outside their allowed ranges.

{
  "status": "error",
  "message": "Max duration must be at least 1"
}

object

Precall DTMF sequence contains invalid characters.

{
  "status": "error",
  "message": "Precall DTMF sequence must be a valid DTMF sequence"
}

Valid DTMF characters: 0-9, *, #, w (wait)

object

Start time must be a valid ISO date-time string.

{
  "status": "error",
  "message": "Start time must be a valid date-time format"
}

object

Webhook URL format is invalid.

{
  "status": "error",
  "message": "Webhook must be a valid URI"
}

object

From number doesn’t match phone number pattern.

{
  "status": "error",
  "message": "Invalid from number format"
}

object

Transfer phone number format validation error.

{
  "status": "error",
  "message": "Invalid transfer phone number format"
}

object

Transfer list contains phone numbers with invalid format.

{
  "status": "error",
  "message": "Invalid phone number format in transfer list"
}

object

Request contains fields that are not allowed in the schema.

{
  "status": "error", 
  "message": "Additional properties are not allowed"
}

object

Phone number format is invalid, missing country code, or invalid length.

{
  "status": "error",
  "message": "Invalid phone number. Please include a country code if outside the US."
}

Other variations:

{
  "status": "error", 
  "message": "Invalid phone number. `+1234567890123456789` has these validation errors: [specific errors]"
}

{
  "error": "Invalid phone number format"
}

Common causes:

Phone number too long (>15 digits) or too short (<7 digits)
Invalid characters in phone number
Missing country code for international numbers
Phone number fails Twilio validation

object

Transfer phone number is invalid.

{
  "status": "error",
  "message": "Invalid transfer_phone_number."
}

object

Language code is not supported.

{
  "status": "error",
  "message": "Invalid language code"
}

object

Pronunciation guide format is incorrect.

{
  "status": "error",
  "message": "Invalid pronunciation guide type."
}

object

Feature not supported on the specified platform.

{
  "status": "error",
  "message": "Precall DTMF sequence is not supported for this platform."
}

object

The ‘from’ number is invalid or not owned by your account.

{
  "status": "error",
  "message": "Invalid 'from' - must be a phone number string with 10 or 12 digits."
}

object

Attempting to call a number on the Do Not Call list.

{
  "status": "DNC Error",
  "message": "Number found in DNC list. You cannot dial sensitive numbers. More attempts will result in being blocked."
}

object

Transfer list configuration errors.

{
  "status": "error",
  "message": "Transfer list must be an object."
}

{
  "status": "error",
  "message": "Invalid transfer phone number."
}

{
  "status": "error", 
  "message": "Transfer phone number cannot be the same as the phone number."
}

object

Retry configuration must be an object.

{
  "status": "error",
  "message": "Retry must be an object."
}

object

Version number must be a valid number.

{
  "status": "error",
  "message": "version_number must be a number."
}

object

Pathway version must be a number or specific string value.

{
  "status": "error",
  "message": "pathway_version needs to either be a number, or a string of 'production' or 'staging'."
}

{
  "status": "error",
  "message": "version_number must be a number or string."
}

object

The ‘from’ number format is invalid.

{
  "status": "error",
  "message": "Invalid from phone number."
}

object

Boolean parameters must be true/false or string equivalents.

{
  "status": "error",
  "message": "wait_for_greeting must be a boolean."
}

Valid for parameters: wait_for_greeting, record, answered_by_enabled, block_interruptions, sensitive_voicemail_detection, ignore_button_press

object

First sentence must be a string.

{
  "status": "error",
  "message": "First sentence must be a string. type: [actual_type]"
}

object

Voicemail message must be a string.

{
  "status": "error",
  "message": "Voicemail message must be a string. type: [actual_type]"
}

object

Voicemail SMS configuration errors.

{
  "status": "error",
  "message": "voicemail_sms must be an object. type: [actual_type]"
}

{
  "status": "error",
  "message": "voicemail_sms.message must be a string. type: [actual_type]"
}

{
  "status": "error",
  "message": "voicemail_sms.from must be a string. type: [actual_type]"
}

object

Interruption threshold must be a number.

{
  "status": "error",
  "message": "interruption_threshold must be a number."
}

object

Webhook URL must be a valid HTTPS URL.

{
  "status": "error",
  "message": "webhook must be a string that starts with https://."
}

object

Request data must be an object.

{
  "status": "error",
  "message": "request_data must be an object."
}

object

Metadata must be an object.

{
  "status": "error",
  "message": "metadata must be an object."
}

object

Analysis schema must be an object.

{
  "status": "error",
  "message": "analysis_schema must be an object."
}

object

Voice parameter must be a string.

{
  "status": "error",
  "message": "Voice must be a string."
}

object

Voicemail action must be one of the allowed values.

{
  "status": "error",
  "message": "Invalid voicemail_action. Options are: [list_of_options]."
}

object

Keywords configuration errors.

{
  "status": "error",
  "message": "Keywords must be an array of strings."
}

{
  "status": "error",
  "message": "Keywords must be strings."
}

{
  "status": "error",
  "message": "Keywords each must be less than 100 characters: [keyword]"
}

{
  "status": "error",
  "message": "Keywords must be in the format 'string' or 'string:number'."
}

{
  "status": "error",
  "message": "Keyword boosts with a colon must have a valid integer for the boost rate."
}

{
  "status": "error",
  "message": "At most 20 keywords can be added."
}

object

Timezone validation errors.

{
  "status": "error",
  "message": "Timezone must be a string."
}

{
  "status": "error",
  "message": "Invalid timezone: [error_message]"
}

object

Summary prompt validation errors.

{
  "status": "error",
  "message": "Summary prompt must be a string."
}

{
  "status": "error",
  "message": "Summary prompt must be less than 2000 characters."
}

object

Start time scheduling validation errors.

{
  "status": "error",
  "message": "start_time must be a string."
}

{
  "status": "error",
  "message": "Invalid start_time."
}

{
  "status": "error",
  "message": "Calls must be scheduled at least 5 minutes in advance, or more"
}

object

Background track validation errors.

{
  "status": "error",
  "message": "background_track must be a string."
}

{
  "status": "error",
  "message": "Invalid background_track option. Options are: [list_of_options]."
}

object

Max duration validation errors.

{
  "status": "error",
  "message": "max_duration must be a number."
}

{
  "status": "error",
  "message": "max_duration must be a positive number."
}

{
  "status": "error",
  "message": "max_duration must be at most 12 hours."
}

object

Dynamic data or tools configuration is invalid.

{
  "status": "error",
  "message": "Unable to parse dynamic data/tools."
}

{
  "status": "error",
  "message": "Invalid tools: [error_message]"
}

{
  "status": "error",
  "message": "Invalid dynamic data: [error_message]"
}

object

Pathway configuration is invalid or missing required components.

{
  "status": "error",
  "message": "Invalid pathway data - no blocks or links found for pathway {pathway_id}"
}

Other variations:

{
  "status": "error",
  "message": "Invalid pathway data"
}

object

The specified start node ID does not exist in the pathway.

{
  "status": "error",
  "message": "Invalid start node ID: {start_node_id}"
}

object

Content failed moderation and was flagged as inappropriate.

{
  "status": "error",
  "message": "Flagged Node: [flagged content]"
}

object

Attempting to call emergency or sensitive numbers.

{
  "status": "error",
  "message": "Cannot dial sensitive numbers. More attempts will result in being blocked."
}

object

Server unable to save the request body or call data.

{
  "status": "error",
  "message": "Unable to save request body."
}

object

Call could not be queued for processing.

{
  "status": "error",
  "message": "Unable to queue call."
}

object

Parent call for warm transfer has already completed or doesn’t exist.

{
  "status": "error",
  "message": "Parent call has completed or does not exist. Warm Transfer Request Cancelled"
}

object

General server errors and catch-all error handlers.

{
  "status": "error",
  "message": "Internal server error during flagging process"
}

Typical scenarios:

Uncaught exceptions in call processing
Third-party service failures
Memory allocation or resource exhaustion errors
Network connectivity issues

object

Basic call parameters validation from the main validation function.

{
  "status": "error",
  "message": "Call parameters must be an object."
}

Business Logic Errors

object

No billing record found for your account.

{
  "status": "error",
  "message": "No billing record found."
}

object

Account balance is insufficient for the call.

{
  "status": "error",
  "message": "Insufficient balance."
}

object

The specified pathway ID does not exist or is not accessible.

{
  "status": "error",
  "message": "Pathway with ID \"{pathway_id}\" not found"
}

object

The specified pathway version does not exist.

{
  "status": "error",
  "message": "Pathway version with ID \"{version_number}\" not found"
}

object

The objective parameter failed validation (returns validation details).

{
  "error": "OBJECTIVE_VALIDATION_ERROR",
  "details": "Custom validation response"
}

Service Errors (HTTP 500)

object

Failed to establish connection with Twilio services.

{
  "status": "error",
  "message": "Error in creating Twilio connection."
}

object

The encrypted key provided is invalid or corrupted.

{
  "status": "error",
  "message": "Invalid `encrypted_key`. Please use the correct key for your account."
}

object

General internal server error during call processing.

{
  "status": "error",
  "message": "Error triggering call. Please check your twilio account for errors"
}

object

Error occurred during the content flagging process.

{
  "status": "error",
  "message": "Internal server error during flagging process"
}

object

Error retrieving Bring Your Own Twilio (BYOT) phone number.

{
  "status": "error",
  "message": "Error in getting BYOT Number"
}

object

Error retrieving dialer data from encrypted key.

{
  "status": "error",
  "message": "Error in getting dialer data from encrypted key"
}

object

Error fetching user data for account verification.

{
  "status": "error",
  "message": "Error in fetching user data"
}

Other variations:

{
  "status": "error",
  "message": "Error in fetching parent user data"
}

object

Missing retry attempt information for retry calls.

{
  "status": "error",
  "message": "Retry attempt not provided for retry call: {call_id}"
}

Docs for agents: llms.txt

Send Call With Task (Simple)Analyze Call with AI

⌘I

​Overview

​Headers

​Body Parameters

​Basic Parameters

​Model Parameters

​Dispatch Parameters

​1. local

​2. custom_pooling

​Knowledge Parameters

​Audio Parameters

​Voicemail Parameters

​Analysis Parameters

​Post Call Parameters

​Advanced Parameters

​Response

​Error Codes Reference

​Authentication & Authorization Errors

​Rate Limiting Errors (HTTP 429)

​Parameter Validation Errors (HTTP 400)

​Business Logic Errors

​Service Errors (HTTP 500)

Overview

Headers

Body Parameters

Basic Parameters

Model Parameters

Dispatch Parameters

1. `local`

2. `custom_pooling`

Knowledge Parameters

Audio Parameters

Voicemail Parameters

Analysis Parameters

Post Call Parameters

Advanced Parameters

Response

Error Codes Reference

Authentication & Authorization Errors

Rate Limiting Errors (HTTP 429)

Parameter Validation Errors (HTTP 400)

Business Logic Errors

Service Errors (HTTP 500)