Skip to main content
POST
Send Call with an Agent

​
Overview

Send an AI phone call with one of your agents. The agent’s published version supplies the conversation, its prompt, scenarios, nodes and tools, so this request names the agent and sets anything you want to override for this one call.
International calls need a completed purchase: buy at least $5 of credits in the dashboard under Billing, or turn on auto-recharge. Numbers on the Agent Phone Plan call the US and Canada only, regardless of your credit balance.
Every setting below is optional and falls back to the agent’s own configuration. A value you send always wins over the agent’s.

​
Headers

​
string
required
Your API key for authentication. Send it as Bearer YOUR_API_KEY. A bare Authorization: YOUR_API_KEY with no prefix is also accepted, so older examples keep working. x-api-key is not read and does not authenticate.Get a key from the dashboard. An autonomous agent with no dashboard session can mint its own with the Agent onboarding API.
​
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
default:"Karen"
The voice of the AI agent to use. Accepts any form of voice ID, including custom voice clones and voice presets. If you omit it, the call uses Karen.Default voices can be referenced directly by their name instead of an id.Usage example: voice: “Karen”For Bland’s recommended voices, call List voices and pick voices tagged "Bland Curated" whose service is BTTS_V3.
​
string
required
The agent to call, as a UUID from List Agents. The agent’s published version supplies the prompt, scenarios, nodes and tools that run the conversation.Cannot be combined with pathway_id or persona_id. Sending more than one is rejected with AGENT_PARAM_CONFLICT, a value that is not a UUID with AGENT_ID_INVALID, and an agent your organization does not own with AGENT_NOT_FOUND.
​
string
default:"production"
Which version of the agent runs the call. Omit it and the call runs the version pinned to production. Requires agent_id, and must be a string: a bare number is rejected.
A string in none of these forms is rejected before the call is placed, with a message naming the accepted forms.
A semver or a branch selector runs the call as the dev environment, so {{env.KEY}} references resolve against dev’s values. The two environment labels run as themselves.The agent’s own tools always drive the call, so the call-level tools parameter is rejected for agent calls.An environment with no pinned version returns AGENT_ENV_UNPINNED. A missing version or branch returns AGENT_VERSION_NOT_FOUND or AGENT_BRANCH_NOT_FOUND.
Only calls that omit agent_version are eligible for experiments. Any explicit selector bypasses assignment, including "production", and is never attributed to a variant.

​
Model Parameters

​
string
default:"en"
Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.
The available language options are as follows:
  • babel - Babel (All Languages) - Experimental1
  • fluent - Fluent (Multilingual)2
  • 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)
1 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: prompt your agent to respond in the language it is spoken to.2 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: prompt your agent to respond in the language it is 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: 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
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”
​
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 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:

​
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:
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.
For best results:
  • Specify conditions that the agent should transfer to a human under (examples are great!)
  • In the agent’s prompt, 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.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:
​
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

​
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:"true"
Toggles noise filtering or suppression in the audio stream to filter out background noise.This parameter was previously documented as defaulting to false. The server has been applying true when the field is omitted, so send it explicitly whenever the behavior matters to you.
​
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

​
boolean
default:"false"
Set to true when the number you are calling answers with a phone menu rather than a person.IVR mode changes two things. The agent stops responding on the conversational timing it uses with a human, so it does not talk over a menu’s prompts or fill its pauses. And voicemail handling is suppressed: the effective voicemail action becomes "ignore" no matter what you passed, because a phone tree has no voicemail to leave a message on.Pair it with precall_dtmf_sequence to play a fixed sequence of digits before the call starts, or leave the agent to navigate the menu from its own prompt.
amd is a legacy alias for this parameter. It sets the same switch, and passing ivr_mode: true sets amd for you. Prefer ivr_mode: the name says what it does.
​
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.
    • "leave_message_and_sms": Play the message, end the call, and send the SMS configured in sms. Supply both message and sms: with no sms config this falls back to leave_message.
    • "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:
    • message (string): Required. The body of the SMS message. Keep concise and clear.
    • from (string): Optional. The phone number to send the SMS from (must be a number you own and have SMS permissions for).
    The destination is resolved by Bland rather than set on the request. There is no to field, and passing one has no effect.

  • sensitive (boolean): When true, uses LLM-based analysis to detect frequent voicemails. The default is false.
The effective action is derived from the whole request, not from action alone. Supplying a message implies leaving one, so "action": "hangup" sent alongside a message leaves the message. And ivr_mode forces ignore regardless of action, since a phone menu has no voicemail. See Voicemail for the full precedence.
Example:

​
Analysis Parameters

​
boolean
default:"false"
When true and the call is transferred to a human, Bland transcribes the conversation after the transfer live and streams it over the Post-Transfer Transcript Stream WebSocket while the transferred conversation is happening. Works for both cold and warm transfers.This option controls the live stream only. To receive the post-transfer transcript in the post-call webhook, subscribe with "post_transfer_transcript" in webhook_events. The two are independent: you can use either one or both.
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 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:
​
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, leave_message_and_sms, ignore.
  • voicemail_message (string): The message to leave when the call goes to voicemail.
Example:

​
Advanced Parameters

​
object
Custom key-value data you send with the call. The runtime interpolates these as {{variable}} inside the agent’s prompt, scenarios, nodes and tools.This is separate from the agent’s environment variables, which are written as {{env.KEY}} and resolve from the environment the call runs as. A referenced environment key with no value fails the call with AGENT_VARIABLE_UNRESOLVED.
An agent whose greeting reads Hello, {{name}} then opens with “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:
​
string
Your own identifier for the call, such as a CRM interaction ID or a contact center session ID. Use it to look the call up later without storing Bland’s call_id.Must be a non-empty string of at most 256 printable characters. The call is returned in Call details, List calls, and the post-call webhook with this external_id.
​
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)
  • evals (Eval scores from an attached evals workbench, sent as a separate webhook when the run completes)
  • post_transfer_transcript (Adds the post-transfer conversation to the post-call webhook when the call is transferred to a human; see Post-transfer transcript. Requires call recording: record is enabled automatically when unset, and passing record: false alongside this subscription returns a 400. In limited rollout: if not enabled for your organization, the subscription has no effect.)
Example payloads:
​
object[]
Integrate data from external APIs into your agent’s knowledge.Set to null or an empty string to clear dynamic data settings.
​
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:
For stronger keyword boosts, you can place a colon then a boost factor after the word. The default boost factor is 2.
​
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. Only available on calls that leave over Twilio, and rejected with a 400 on any other platform. Example:
​
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: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.
Custom guard rails with your own prompt. Enterprise customers can create up to 5 custom guard rails.
Each guard rail requires an actions array. Available action types:
Full example with multiple guard rails:

​
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:

​
Error Codes Reference

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
agent_id was sent alongside pathway_id or persona_id.
​
object
agent_version was not a semantic version, a branch:<name>, or one of the four labels. It must be a string; a bare number is rejected.
​
object
The environment named by agent_version has no version pinned to it.
​
object
No agent in your organization matches agent_id. A malformed id returns AGENT_ID_INVALID instead, and a missing version or branch returns AGENT_VERSION_NOT_FOUND or AGENT_BRANCH_NOT_FOUND.
​
object
Authentication failed due to missing or invalid API key.
Common causes:
  • Missing Authorization header
  • Invalid API key
  • Expired API key
​
object
Account has been flagged or banned for security purposes.
​
object
Calls sent too frequently to the same number.
​
object
Rate limit exceeded for your account.
​
object
Attempting to call a blacklisted number.
​
object
Rate limits for newly created accounts.
​
object
International calling rate limit exceeded.
​
object
Required parameters are missing from the request.
Required parameters:
  • phone_number (always required)
  • agent_id (names the agent that makes the call)
​
object
Field values are the wrong data type according to TypeBox validation.
Common type validation errors:
  • "Record must be a boolean"
  • "Max duration must be a number"
  • "Temperature must be a number"
  • "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.
​
object
Numeric values are outside their allowed ranges.
​
object
Precall DTMF sequence contains invalid characters.
Valid DTMF characters: 0-9, *, #, w (wait)
​
object
Start time must be a valid ISO date-time string.
​
object
Webhook URL format is invalid.
​
object
From number doesn’t match phone number pattern.
​
object
Transfer phone number format validation error.
​
object
Transfer list contains phone numbers with invalid format.
​
object
Request contains fields that are not allowed in the schema.
​
object
Phone number format is invalid, missing country code, or invalid length.
Other variations:
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
Language code is not supported.
​
object
Pronunciation guide format is incorrect.
​
object
Feature not supported on the specified platform.
​
object
The ‘from’ number is invalid or not owned by your account.
​
object
Attempting to call a number on the Do Not Call list.
​
object
Transfer list configuration errors.
​
object
Retry configuration must be an object.
​
object
Version number must be a valid number.
​
object
The ‘from’ number format is invalid.
​
object
Boolean parameters must be true/false or string equivalents.
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.
​
object
Voicemail message must be a string.
​
object
Voicemail SMS configuration errors.
​
object
Interruption threshold must be a number.
​
object
Webhook URL must be a valid HTTPS URL.
​
object
Request data must be an object.
​
object
Metadata must be an object.
​
object
Voice parameter must be a string.
​
object
Voicemail action must be one of the allowed values.
​
object
Keywords configuration errors.
​
object
Timezone validation errors.
​
object
Summary prompt validation errors.
​
object
Start time scheduling validation errors.
​
object
Background track validation errors.
​
object
Max duration validation errors.
​
object
Dynamic data or tools configuration is invalid.
​
object
Content failed moderation and was flagged as inappropriate.
​
object
Attempting to call emergency or sensitive numbers.
​
object
Server unable to save the request body or call data.
​
object
Call could not be queued for processing.
​
object
Parent call for warm transfer has already completed or doesn’t exist.
​
object
General server errors and catch-all error handlers.
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.
​
object
No billing record found for your account.
​
object
Account balance is insufficient for the call.
​
object
The objective parameter failed validation (returns validation details).
​
object
Failed to establish connection with Twilio services.
​
object
The encrypted key provided is invalid or corrupted.
​
object
General internal server error during call processing.
​
object
Error occurred during the content flagging process.
​
object
Error retrieving Bring Your Own Twilio (BYOT) phone number.
​
object
Error retrieving dialer data from encrypted key.
​
object
Error fetching user data for account verification.
Other variations:
​
object
Missing retry attempt information for retry calls.
​
object
Transfer phone number is invalid.
Docs for agents: llms.txt