POST
/
call
curl --request POST \
  --url https://api.bland.ai/call \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "phone_number": "<string>",
  "transfer_phone_number": "<string>",
  "from": "<string>",
  "task": "<string>",
  "reduce_latency": true,
  "voice_id": 123,
  "webhook": "<string>",
  "wait_for_greeting": true,
  "first_sentence": "<string>",
  "record": true,
  "language": "<string>",
  "max_duration": {},
  "temperature": 123,
  "amd": true,
  "request_data": {},
  "dynamic_data": [
    {
      "dynamic_data[i].response_data": [
        {}
      ]
    }
  ],
  "interruption_threshold": 123
}'
{
  "status": "success",
  "call_id": "9d404c1b-6a23-4426-953a-a52c392ff8f1"
}

Headers

authorization
string
required

Your API key for authentication.

Body

phone_number
string
required

The phone number to call. Country code required for non-US numbers.

Example: +12223334444, +44770090000, +61491550156.

transfer_phone_number
string

A phone number that the agent can transfer to under specific conditions, such as when the caller/callee asks to speak to a human.

For best results, specify the exact conditions to transfer under in the task parameter. Refer to the action as “transfer”, any other phrasing such as “swap” or “switch” can cause unexpected behavior.

Example: +12223334444, +44770090000, +61491550156.

from
string

Specify a purchased Outbound Number to call from. Country code is required, spaces or parentheses must be excluded.

By default, calls are initiated from a separate pool of numbers owned by Bland.

task
string
required

Define how the AI should behave. Provide instructions, relevant information, and examples of the ideal conversation flow.

Note: Concise prompts lead to higher performance and adherence to instructions. Overly verbose prompts ‘dilute’ the context if filled with unnecessary/irrelevant details.

reduce_latency
boolean
default: "true"

Reducing latency means that the agent will generate responses more quickly and have less of a delay. This must be set to true when using Voice Clones.

voice_id
number
default: "0"

When reduce latency is set to true (default):

  • 0: American male
  • 1: Australian female
  • 2: American female

When reduce latency is set to false:

  • 0: American female (southern accent)
  • 1: American male
  • 2: British female
  • 3: Indian male
webhook
string

The webhook should be a http / https callback url. We will send the call_id and transcript to this URL after the call completes. This can be useful if you want to have real time notifications when calls finish.

wait_for_greeting
boolean
default: "false"

Should the AI speak first or wait for someone else to talk?

Creates more realistic conversations when answered with “Hello?”, “This is {name} speaking.” and so on.

  • When false: The AI starts speaking shortly after the call is answered.

  • When true: The AI will wait for the answerer to speak.

first_sentence
string

A phrase that your call will start with instead of a generating one on the fly. This works both with and without wait_for_greeting. Can be more than one sentence, but must be less than 200 characters.

record
boolean
default: "false"

To record your phone call, set record to true. When your call completes, you can access the recording by requesting the /call/recording endpoint.

voice_settings
Voice Settings Object
language
string
default: "eng"

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

Supported Languages and their codes:

  • English: eng
  • Spanish: esp
  • French: fre
  • Polish: pol
max_duration
float or string
default: "30"

Set the longest you want the call to possibly go in minutes. After the max_duration minutes have passed, the call will automatically end.

Example Values: "45", "5.5", 20, 2.8

temperature
float
default: "0.7"

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"

amd
boolean
default: "false"

AMD mode helps our AI navigate phone trees and IVR systems. If you know your call will hit an automated system you should switch it on.

NOTE: AMD mode causes increased delay for the first response, even if answered by a human. Highly recommended to set to false in the majority of cases.

request_data
object

When you want your AI to “know” a specific fact - like the caller’s name or other relevant context.

The AI agent will be aware of both the key names as well as their corresponding values.

dynamic_data
array
interruption_threshold
integer
default: 50

When you increase the interruption latency, you force the AI phone agent to listen longer before responding. In practice, increasing the threshold results in less interruptions and more latency.

Try setting the threshold to 500 milliseconds. You’ll encounter higher latency, but you’ll be interrupted much less frequently.

Response

status
string

Can be success or error.

call_id
string

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