Send Call

authorization

string

required

Your API key for authentication.

encrypted_key

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.

phone_number

string

required

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

voice

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

pathway_id

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"
}

pathway_version

integer

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

task

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.

first_sentence

string

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

persona_id

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

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

language

string

default:"en-US"

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

wait_for_greeting

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.

pronunciation_guide

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

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”

interruption_threshold

number

default:"100"

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.Recommended range: 50-200 • 50: Extremely quick, back and forth conversation • 100: Balanced to respond at a natural pace • 200: Very patient, allows for long pauses and interruptions. Ideal for collecting detailed information.Try to start with 100 and make small adjustments in increments of ~10 as needed for your use case.

from

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.

dialing_strategy

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_pool`

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_pool",
    "pool_id": "bd039087-decb-435a-a6e3-ca1ffbf89974"
  }
}

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

timezone

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.

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.

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. This option will be ignored for pathways.

Prompting Notes

transfer_list

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"
  }
}

max_duration

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

tools

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"
  ]
}

Read more about custom tools here

background_track

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

noise_cancellation

boolean

default:"false"

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

block_interruptions

boolean

default:"false"

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

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.

voicemail

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
  }
}

citation_schema_ids

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": ["dcad76eb-57b6-4be6-922f-8a5a95e2ffrt"]
}

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.

analysis_preset

string

The analysis preset UUID used to analyze the call, must be created on the analysis presets page.All fields in the preset configuration are filled at the end of the call by analyzing the transcript.Example:

  {
    "analysis_preset": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7"
  }

summary_prompt

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."
}

retry

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."
    }
}

dispositions

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.Example:

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

request_data

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

metadata

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"
  }
}

webhook

string

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

webhook_events

string[]

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

queue
call
latency
webhook
tool
dynamic_data
citations (Sent separately, Enterprise only)

Example payloads:

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

dynamic_data

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": ""
        }
      ]
    }
  ],

keywords

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"]
  }

ignore_button_press

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.

precall_dtmf_sequence

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"
  }

status

string

Can be success or error.

message

string

A message explaining the status of the call.

call_id

string

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

batch_id

string

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

errors

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."
    ]
}

Basic Tutorials

Calls

Text to Speech

Intelligence

Conversational Pathways

Vector Knowledge Bases

Numbers

Blocked Numbers

Voices

Custom Tools

Memory

Web Agents

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

SMS

Custom Dialing Pools

Citation Schemas

Overview

Headers

Body Parameters

Basic Parameters

Model Parameters

Dispatch Parameters

1. `local`

2. `custom_pool`

Knowledge Parameters

Audio Parameters

Voicemail Parameters

Analysis Parameters

Post Call Parameters

Advanced Parameters

Response

Basic Tutorials

Calls

Text to Speech

Intelligence

Conversational Pathways

Vector Knowledge Bases

Numbers

Blocked Numbers

Voices

Custom Tools

Memory

Web Agents

Custom Twilio Accounts

Batches

Prompts

Account

Organizations

SMS

Custom Dialing Pools

Citation Schemas

​Overview

​Headers

​Body Parameters

​Basic Parameters

​Model Parameters

​Dispatch Parameters

​1. local

​2. custom_pool

​Knowledge Parameters

​Audio Parameters

​Voicemail Parameters

​Analysis Parameters

​Post Call Parameters

​Advanced Parameters

​Response

Overview

Headers

Body Parameters

Basic Parameters

Model Parameters

Dispatch Parameters

1. `local`

2. `custom_pool`

Knowledge Parameters

Audio Parameters

Voicemail Parameters

Analysis Parameters

Post Call Parameters

Advanced Parameters

Response