POST
/
v1
/
calls
curl --request POST \
  --url https://api.bland.ai/v1/calls \
  --header 'Content-Type: application/json' \
  --header 'authorization: <authorization>' \
  --data '{
  "phone_number": "<string>",
  "task": "<string>",
  "transfer_list": {},
  "model": "<string>",
  "pronunciation_guide": [
    {}
  ],
  "temperature": 123,
  "tools": [
    {}
  ],
  "transfer_phone_number": "<string>",
  "answered_by_enabled": true,
  "from": "<string>",
  "reduce_latency": true,
  "voice_id": 123,
  "voice_preset_id": "<string>",
  "start_time": "<string>",
  "webhook": "<string>",
  "wait_for_greeting": true,
  "first_sentence": "<string>",
  "record": true,
  "voice_settings": {
    "stability": 123,
    "similarity": 123,
    "speed": 123
  },
  "language": "<string>",
  "max_duration": 123,
  "voicemail_action": {},
  "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 defaults to +1 (US) if not specified.

Formatting is flexible, however for the most predictable results use the E.164 format.

task
string
required

Provide instructions, relevant information, and examples of the ideal conversation flow.

transfer_list
object

Give your agent the ability to transfer calls to a set of phone numbers.

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"
}
model
string
default: "enhanced"

Select a model to use for your call.

Options: gpt4, base, turbo and enhanced.

In nearly all cases, enhanced is the best choice for now.

pronunciation_guide
array

The pronunciation guide is an array of objects that guides the LLM on how to say specific words. This is great for situations with complicated terms or names.

    [
      {
        "word": "example",
        "pronunciation": "ex-am-ple",
        "case_sensitive": "false",
        "spaced": "false"
      },
      {
        "word": "API",
        "pronunciation": "A P I",
        "case_sensitive": "true",
        "spaced": "true"
      }
    ]
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"

tools
array

Interact with the real world through API calls.

Detailed tutorial here: Custom Tools

transfer_phone_number
string

A phone number that the agent can transfer to under specific conditions - such as being asked to speak to a human or supervisor.

answered_by_enabled
boolean
default: false

Enables machine detection when the call starts to determine whether the call was answered by a person or a voicemail.

Best Practices (when enabled):

  • Since the determination is made at the beginning of the call, use wait_for_greeting to try and coax a human response.
  • If combined with first_sentence, try wording it so the person answering says something back - ex. "Hello?" or "Is this \{\{name\}\}?".

Price: $0.02 per call, however there is no charge for unanswered calls or calls that failed to send.

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.

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"

Determines the voice of the AI agent, in conjunction with reduce_latency.

Use the GET /v1/voices endpoint to see a full list of your available voices.

To create your own Voice Clone, visit our Custom Voice Cloning page.

voice_preset_id
string

Use a voice preset instead of specifying individual voice settings.

To create a voice preset, see Create a Voice Preset.

start_time
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.

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 through the recording_url field in the call details or your webhook.

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
integer
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: 20, 2

voicemail_action
enum
default: "hangup"

Voicemail action tells the AI what to do when encountering a voicemail. This has 96% accuracy. There is no such thing as a perfect VM detection, but this gets close.

  • hangup
  • leave_message

The default value is hangup to save money and keep most users in compliance.

Leaving voicemails is strongly discouraged.

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

Make dynamic requests to external APIs and use the data in your AI’s responses.

interruption_threshold
number
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).