> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bland.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Call

> Send an AI phone call with a custom objective and actions.

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

> [!NOTE]
>
> International calls need a completed purchase: buy at least \$5 of credits in the [dashboard](https://app.bland.ai/dashboard/pay) under Billing, or turn on auto-recharge. Numbers on the [Agent Phone Plan](https://docs.bland.ai/platform/agent-phone-plan.md) call the US and Canada only, regardless of your credit balance.

## Choose what runs your call

Before sending, choose the resource you want to run. If you want the call associated with a Bland Agent in the current dashboard, use **`agent_id`**.

| Dispatch choice | What runs | Verify before sending |
| - | - | - |
| **Agent ID** (`agent_id`) | A saved Bland Agent version. | The exact agent ID, organization, and intended environment or version. Requires an organization API key. |
| **Persona ID** (`persona_id`) | A persona's reusable call configuration and routing. | The exact persona ID, selected persona version, configuration, and any pathway overrides. |
| **Pathway ID** (`pathway_id`) | A conversational pathway directly. | The exact pathway ID, intended pathway version, and required `request_data` variables. |

These IDs identify different objects. They are not interchangeable, even when names or prompts match. A pathway compiled from an agent does not make pathway dispatch equivalent to agent dispatch.

The caller ID (`from`) is a separate choice. Using a phone number assigned to an agent does not select that agent for an outbound call.

### Instructions for AI assistants

1. **Resolve the dispatch choice before sending.** If the user has not selected a resource type, ask: "Should I send this call through a dashboard agent, a persona, or a specific pathway?" Make the choices concrete with the resources you found. For example: "I found the dashboard agent Taylor and a pathway named Taylor - Cardholder status check. Which should run the call?" Recommend agent dispatch when the user wants the conversation under that dashboard agent.
2. **Honor an established choice.** If the user already chose a resource type and target, use it without asking again. Keep that choice for subsequent calls in the same agreed task unless the user changes it or a new ambiguity arises. A name alone is insufficient when it matches multiple resource types.
3. **Verify the exact resource.** Check its type, account or organization, name, ID, and environment or version. Read the current endpoint or tool schema. Do not substitute an agent's persona or pathway because its ID is easier to obtain, or combine selectors without checking the supported behavior below.
4. **Ask before changing routes.** If the requested route is unavailable, explain the limitation and ask whether the user wants an alternative. Do not silently fall back to another resource type.
5. **Verify the resulting conversation.** Save the `call_id`, check the actual source and destination numbers, and confirm the recorded resource and version. For agent dispatch, also check the intended agent's Conversations view. Report call success and an attribution problem separately. Do not place a duplicate call just to repair dashboard visibility.

### Request examples

Each example sends one call. Replace the example destination and resource ID with values you have verified in the intended organization. Export your key as `BLAND_API_KEY`. Supply any variables required by your agent, persona, or pathway in `request_data`.

> [tab] Bland Agent
>
> Use `agent_id` with an organization API key. This example explicitly selects the production pin and production environment variables. Do not include `persona_id` or `pathway_id`.
>
> ```bash theme={null}
> curl --request POST https://api.bland.ai/v1/calls \
>   --header "Authorization: Bearer $BLAND_API_KEY" \
>   --header "Content-Type: application/json" \
>   --data '{
>     "phone_number": "+14155550100",
>     "agent_id": "00000000-0000-4000-8000-000000000001",
>     "agent_version": "production"
>   }'
> ```
>
> Find the conversation under **your agent > Conversations**. Verify the recorded agent and version; a successful submission alone does not prove the intended version ran.

> [tab] Persona
>
> Use `persona_id` to run its reusable configuration. This example selects the production persona version.
>
> ```bash theme={null}
> curl --request POST https://api.bland.ai/v1/calls \
>   --header "Authorization: Bearer $BLAND_API_KEY" \
>   --header "Content-Type: application/json" \
>   --data '{
>     "phone_number": "+14155550100",
>     "persona_id": "00000000-0000-4000-8000-000000000002",
>     "persona_version": "production"
>   }'
> ```
>
> Find the call under **All agents > Conversations**, using its `call_id`. Do not assume it belongs to a Bland Agent because the persona uses a related pathway or number.

> [tab] Pathway
>
> Use `pathway_id` to run that pathway directly. This example selects its production version.
>
> ```bash theme={null}
> curl --request POST https://api.bland.ai/v1/calls \
>   --header "Authorization: Bearer $BLAND_API_KEY" \
>   --header "Content-Type: application/json" \
>   --data '{
>     "phone_number": "+14155550100",
>     "pathway_id": "00000000-0000-4000-8000-000000000003",
>     "pathway_version": "production"
>   }'
> ```
>
> Find the call under **All agents > Conversations**, using its `call_id`. A matching pathway name or a description referencing an agent ID does not establish agent attribution.

### Selector combinations and precedence

* `agent_id` cannot be combined with `persona_id` or `pathway_id`; the API rejects the combination. `agent_version` requires `agent_id`. The agent graph drives the call, so omit `task` on agent requests.
* Agent call settings supply defaults. Explicit call settings such as `voice`, `record`, and `max_duration` override their agent defaults. Explicit `request_data` and `metadata` replace their respective default objects, including when you pass `{}`.
* A persona can be combined with `pathway_id` and `pathway_version` to override its pathway routing. An explicit `persona_settings` object takes precedence over those pathway overrides. For versioned personas, stored call configuration is applied over matching top-level request fields. Legacy persona presets apply the request over the preset instead. Inspect the persona configuration rather than assuming all request fields win.
* A direct pathway request does not need `task`; its graph controls the conversation. `request_data` supplies call variables.

> [!WARNING]
>
> Call completion and agent attribution are separate checks. A persona or pathway call can complete and appear under All agents without appearing under the intended Bland Agent. Check the recorded association and dashboard view instead of inferring attribution from a name, prompt, description, or caller ID.

```bash Bland Agent theme={null}
curl --request POST https://api.bland.ai/v1/calls \
  --header "Authorization: Bearer $BLAND_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone_number": "+14155550100",
    "agent_id": "00000000-0000-4000-8000-000000000001",
    "agent_version": "production"
  }'
```

```bash Persona theme={null}
curl --request POST https://api.bland.ai/v1/calls \
  --header "Authorization: Bearer $BLAND_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone_number": "+14155550100",
    "persona_id": "00000000-0000-4000-8000-000000000002",
    "persona_version": "production"
  }'
```

```bash Pathway theme={null}
curl --request POST https://api.bland.ai/v1/calls \
  --header "Authorization: Bearer $BLAND_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "phone_number": "+14155550100",
    "pathway_id": "00000000-0000-4000-8000-000000000003",
    "pathway_version": "production"
  }'
```

***

## Headers

**authorization** `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](https://app.bland.ai/dashboard/settings). An autonomous agent with no dashboard session can mint its own with the [Agent onboarding API](https://docs.bland.ai/platform/connect-your-agent.md).

**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](https://docs.bland.ai/tutorials/custom-twilio.md).

***

## Body Parameters

### Basic Parameters

**phone\_number** `string` *required*

The phone number to call. Must be a valid phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.

**agent\_id** `string`

The UUID of a Bland Agent in the current organization. Requires an organization API key. Runs the agent's saved graph and records the agent/version association on the call.

Use this when the conversation should belong to a dashboard agent. Do not combine it with `persona_id` or `pathway_id`. Omit `task` because the agent graph supplies the instructions. See [Choose what runs your call](#choose-what-runs-your-call).

**agent\_version** `string`

Selects the agent version and environment. Requires `agent_id`.

| Value | Version selected | Environment variables |
| - | - | - |
| Omitted | Production pin, eligible for active experiment routing. | Production |
| `"production"` | Production pin, bypassing experiments. | Production |
| `"staging"` | Staging pin, bypassing experiments. | Staging |
| `"dev"` or `"latest"` | Latest saved version on the main line, bypassing experiments. | Dev |
| A semantic version such as `"1.2.0"` | That published version, bypassing experiments. | Dev |
| `"branch:<name>"` | The open branch's head, bypassing experiments. | Dev |

A semantic version or branch selector uses dev variables even if the same version is deployed to production or staging. Use an environment label when you need that environment's variables. Branch names contain 1 to 64 letters, digits, underscores, periods, or hyphens.

If the agent is unavailable, the selected environment has no deployed version, or preparation fails, inspect the API error before retrying. Do not replace the requested route with a persona or pathway without the user's choice.

**voice** `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](https://docs.bland.ai/api-v1/get/voices.md) and pick voices tagged `"Bland Curated"` whose `service` is `BTTS_V3`.

**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 [here](https://app.bland.ai/home?page=convo-pathways)

Note: Certain parameters do not apply when using pathways.

Example Simple Request body:

```json theme={null}
{
  "phone_number": "+1975934749",
  "pathway_id": "a0f0d4ed-f5f5-4f16-b3f9-22166594d7a7"
}
```

**pathway\_version** `integer | string`

Select a numeric pathway version, `"production"`, or `"staging"`. Omitted, `0`, and `"production"` select production. A missing numeric version can fall back to production, so verify the resolved version when an exact version matters.

**task** `string`

Required when you do not supply `agent_id`, `persona_id`, or `pathway_id`. Do not specify it for agent or pathway dispatch.

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.

Check the selected persona's stored configuration and [selector precedence](#selector-combinations-and-precedence) before applying overrides. `persona_id` cannot be combined with `agent_id`.

You can access your persona IDs by clicking the "Personas" button at the bottom of the Send Call page, and then "Use and Manage".

**persona\_version** `string` (default: production)

For versioned personas, selects `"production"` or `"draft"`. If `"draft"` is requested but no draft exists, the server uses production when available. Verify that the intended version exists before sending.

### Model Parameters

**language** `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.

> [accordion] Expand to view language options
>
> The available language options are as follows:
>
> * `babel` - Babel (All Languages) - Experimental<sup>1</sup>
> * `fluent` - Fluent (Multilingual)<sup>2</sup>
> * `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)
>
> <sup>1</sup> 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.**
>
> <sup>2</sup> 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.**

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

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

> [accordion] 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`.

**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: 500)

Legacy. Sets a fixed wait, in milliseconds, after the caller stops speaking before the AI responds. We recommend leaving this unset: response timing adapts to each caller automatically (see [Agent Speech](https://docs.bland.ai/tutorials/agent-speech.md)).

To control how readily the AI stops when the caller talks over it, use `interruptibility`.

**interruptibility** `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.
* `4`: Always interrupt. Any caller speech stops the AI, including brief acknowledgments like "uh-huh".

See [Agent Speech](https://docs.bland.ai/tutorials/agent-speech.md) for how each level behaves.

### Dispatch Parameters

**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](https://app.bland.ai/dashboard/add-ons).

Example:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

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

> [accordion] 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.

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

```json theme={null}
{
  "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

### Knowledge Parameters

**tools** `array`

Add custom tools and knowledge base items to your call for your agent to call upon.

Example:

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

Read more about custom tools [here](https://docs.bland.ai/tutorials/custom-tools#custom-tools)

### Audio Parameters

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

**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 Parameters

**ivr\_mode** `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`](https://docs.bland.ai/api-v1/post/calls#param-precall-dtmf-sequence) to play a fixed sequence of digits before the call starts, or leave the agent to navigate the menu from the `task`.

> [!NOTE]
>
> `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.

**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.
  * `"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`.

> [!NOTE]
>
> 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`](https://docs.bland.ai/api-v1/post/calls#param-ivr-mode) forces `ignore` regardless of `action`, since a phone menu has no voicemail. See [Voicemail](https://docs.bland.ai/platform/agent-call-recipes.md#voicemail) for the full precedence.

Example:

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

### Analysis Parameters

**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](https://app.bland.ai/dashboard/analytics?tab=citations).

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:

```json theme={null}
{
  "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.

**disposition\_ids** `string[]`

Outcome IDs to run after the call ends. Create outcomes with [Create Outcome](https://docs.bland.ai/api-v1/post/dispositions.md). Results appear in the `dispositions` field of [Call Details](https://docs.bland.ai/api-v1/get/calls-id.md). See [Outcomes](https://docs.bland.ai/tutorials/outcomes.md) for details.

**stream\_post\_transfer\_transcript** `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](https://docs.bland.ai/api-v1/post/calls-id-transcript-stream.md) 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.

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

**post\_call\_evals** `object`

Attach an [evals workbench](https://docs.bland.ai/agents/evaluations.md#score-calls-after-they-end) 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:

```json theme={null}
{
  "post_call_evals": {
    "workbench_setup_id": "b7c2e1d4-8f3a-4c9e-9a2b-1e5f6d7c8a9b"
  }
}
```

### Post Call Parameters

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

```json theme={null}
{
  "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`, `leave_message_and_sms`, `ignore`.
* `voicemail_message` (string): The message to leave when the call goes to voicemail.

Example:

```json theme={null}
{
    "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.

> [accordion] 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:

```json theme={null}
  {
    "dispositions": ["got_full_name_and_number", "no_information_provided", "transferred_to_agent"]
  }
```

### Advanced Parameters

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

```json theme={null}
  {
    "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:

```json theme={null}
{
  "metadata": {
    "campaign_id": "1234",
    "source": "web"
  }
}
```

**external\_id** `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](https://docs.bland.ai/api-v1/get/calls-id.md), [List calls](https://docs.bland.ai/api-v1/get/calls.md), and the post-call webhook with this `external_id`.

```json theme={null}
{
  "external_id": "crm-interaction-48213"
}
```

**webhook** `string`

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

**webhook\_events** `array`

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

> [!NOTE]
>
> **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](https://docs.bland.ai/enterprise-features/citations.md#webhook-integration-options) 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](https://docs.bland.ai/agents/evaluations.md#score-calls-after-they-end), 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](https://docs.bland.ai/tutorials/post-call-webhooks.md#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:

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

```json call theme={null}
// 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"
}
```

```json latency theme={null}
// 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"
}
```

```json webhook theme={null}
{
  "message": "Storing dynamic data messages: \n\n answer : \"true\"",
  "call_id": "87654321-4321-4321-4321-cba987654321",
  "category": "call",
  "log_level": "info"
}
```

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

```json dynamic_data theme={null}
{
  "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"
}
```

```json citations theme={null}
{
  "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"
    }
  ]
}
```

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

```json theme={null}
  "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:

```json theme={null}
  {
    "keywords": ["Blandy"]
  }
```

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

```json theme={null}
  {
    "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:

```json theme={null}
  {
    "precall_dtmf_sequence": "1234567890*#w"
  }
```

**guard\_rails** `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](https://docs.bland.ai/tutorials/guard-rails.md).

Each item in the array can be one of three types:

> [accordion] 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.
>
> ```json theme={null}
> {
>   "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) |

> [accordion] Custom Guard Rails (Enterprise)
>
> Custom guard rails with your own prompt. Enterprise customers can create up to 5 custom guard rails.
>
> ```json theme={null}
> {
>   "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 |

> [accordion] 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:**

```json theme={null}
{
  "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

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

```json theme={null}
{
    "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."
    ]
}
```

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

## Error Codes Reference

> [accordion] 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
>
> **401 - AUTH\_FAILURE** `object`
>
> Authentication failed due to missing or invalid API key.
>
> ```json theme={null}
> {
>   "data": null,
>   "errors": [
>     {
>       "error": "AUTH_FAILURE", 
>       "message": "Unauthorized"
>     }
>   ]
> }
> ```
>
> **Common causes:**
>
> * Missing Authorization header
> * Invalid API key
> * Expired API key
>
> **403 - Account Flagged** `object`
>
> Account has been flagged or banned for security purposes.
>
> ```json theme={null}
> {
>   "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 support@bland.ai with your account phone number."
> }
> ```
>
> ### Rate Limiting Errors (HTTP 429)
>
> **429 - Call Frequency Limit** `object`
>
> Calls sent too frequently to the same number.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Calls can only be sent every 10 seconds to the same number. Please try again in a few seconds."
> }
> ```
>
> **429 - General Rate Limit** `object`
>
> Rate limit exceeded for your account.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Rate limit exceeded"
> }
> ```
>
> **429 - Blacklisted Number** `object`
>
> Attempting to call a blacklisted number.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "This number is blacklisted."
> }
> ```
>
> **429 - New Customer Rate Limit** `object`
>
> Rate limits for newly created accounts.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Rate limit exceeded for newly created accounts. Please try again soon."
> }
> ```
>
> **429 - International Rate Limit** `object`
>
> International calling rate limit exceeded.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "International rate limit exceeded for your account type."
> }
> ```
>
> ### Parameter Validation Errors (HTTP 400)
>
> **400 - Missing Required Parameter** `object`
>
> Required parameters are missing from the request.
>
> ```json theme={null}
> {
>   "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)
>
> **400 - Invalid Field Types** `object`
>
> Field values are the wrong data type according to TypeBox validation.
>
> ```json theme={null}
> {
>   "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"`
>
> **400 - Invalid Voicemail Action** `object`
>
> Voicemail action must be one of the allowed values.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid voicemail action. Must be one of: hangup, leave_message, leave_message_and_sms, ignore"
> }
> ```
>
> **400 - Number Range Validation** `object`
>
> Numeric values are outside their allowed ranges.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Max duration must be at least 1"
> }
> ```
>
> **400 - Invalid DTMF Sequence** `object`
>
> Precall DTMF sequence contains invalid characters.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Precall DTMF sequence must be a valid DTMF sequence"
> }
> ```
>
> **Valid DTMF characters:** 0-9, \*, #, w (wait)
>
> **400 - Invalid Date Format** `object`
>
> Start time must be a valid ISO date-time string.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Start time must be a valid date-time format"
> }
> ```
>
> **400 - Invalid Webhook URL** `object`
>
> Webhook URL format is invalid.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Webhook must be a valid URI"
> }
> ```
>
> **400 - Invalid From Number Format** `object`
>
> From number doesn't match phone number pattern.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid from number format"
> }
> ```
>
> **400 - Invalid Transfer Phone Format** `object`
>
> Transfer phone number format validation error.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid transfer phone number format"
> }
> ```
>
> **400 - Invalid Transfer List Format** `object`
>
> Transfer list contains phone numbers with invalid format.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid phone number format in transfer list"
> }
> ```
>
> **400 - Additional Properties Not Allowed** `object`
>
> Request contains fields that are not allowed in the schema.
>
> ```json theme={null}
> {
>   "status": "error", 
>   "message": "Additional properties are not allowed"
> }
> ```
>
> **400 - Invalid Phone Number** `object`
>
> Phone number format is invalid, missing country code, or invalid length.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid phone number. Please include a country code if outside the US."
> }
> ```
>
> **Other variations:**
>
> ```json theme={null}
> {
>   "status": "error", 
>   "message": "Invalid phone number. `+1234567890123456789` has these validation errors: [specific errors]"
> }
> ```
>
> ```json theme={null}
> {
>   "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
>
> **400 - Invalid Transfer Number** `object`
>
> Transfer phone number is invalid.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid transfer_phone_number."
> }
> ```
>
> **400 - Invalid Language Code** `object`
>
> Language code is not supported.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid language code"
> }
> ```
>
> **400 - Invalid Pronunciation Guide** `object`
>
> Pronunciation guide format is incorrect.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid pronunciation guide type."
> }
> ```
>
> **400 - Platform Not Supported** `object`
>
> Feature not supported on the specified platform.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Precall DTMF sequence is not supported for this platform."
> }
> ```
>
> **400 - Invalid From Number** `object`
>
> The 'from' number is invalid or not owned by your account.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid 'from' - must be a phone number string with 10 or 12 digits."
> }
> ```
>
> **400 - DNC List Violation** `object`
>
> Attempting to call a number on the Do Not Call list.
>
> ```json theme={null}
> {
>   "status": "DNC Error",
>   "message": "Number found in DNC list. You cannot dial sensitive numbers. More attempts will result in being blocked."
> }
> ```
>
> **400 - Transfer List Validation** `object`
>
> Transfer list configuration errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Transfer list must be an object."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid transfer phone number."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error", 
>   "message": "Transfer phone number cannot be the same as the phone number."
> }
> ```
>
> **400 - Retry Parameter Validation** `object`
>
> Retry configuration must be an object.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Retry must be an object."
> }
> ```
>
> **400 - Version Number Validation** `object`
>
> Version number must be a valid number.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "version_number must be a number."
> }
> ```
>
> **400 - Pathway Version Validation** `object`
>
> Pathway version must be a number or specific string value.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "pathway_version needs to either be a number, or a string of 'production' or 'staging'."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "version_number must be a number or string."
> }
> ```
>
> **400 - From Phone Number Validation** `object`
>
> The 'from' number format is invalid.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid from phone number."
> }
> ```
>
> **400 - Boolean Parameter Validation** `object`
>
> Boolean parameters must be true/false or string equivalents.
>
> ```json theme={null}
> {
>   "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`
>
> **400 - First Sentence Validation** `object`
>
> First sentence must be a string.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "First sentence must be a string. type: [actual_type]"
> }
> ```
>
> **400 - Voicemail Message Validation** `object`
>
> Voicemail message must be a string.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Voicemail message must be a string. type: [actual_type]"
> }
> ```
>
> **400 - Voicemail SMS Validation** `object`
>
> Voicemail SMS configuration errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "voicemail_sms must be an object. type: [actual_type]"
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "voicemail_sms.message must be a string. type: [actual_type]"
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "voicemail_sms.from must be a string. type: [actual_type]"
> }
> ```
>
> **400 - Interruption Threshold Validation** `object`
>
> Interruption threshold must be a number.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "interruption_threshold must be a number."
> }
> ```
>
> **400 - Webhook URL Validation** `object`
>
> Webhook URL must be a valid HTTPS URL.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "webhook must be a string that starts with https://."
> }
> ```
>
> **400 - Request Data Validation** `object`
>
> Request data must be an object.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "request_data must be an object."
> }
> ```
>
> **400 - Metadata Validation** `object`
>
> Metadata must be an object.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "metadata must be an object."
> }
> ```
>
> **400 - Voice Parameter Validation** `object`
>
> Voice parameter must be a string.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Voice must be a string."
> }
> ```
>
> **400 - Voicemail Action Validation** `object`
>
> Voicemail action must be one of the allowed values.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid voicemail_action. Options are: [list_of_options]."
> }
> ```
>
> **400 - Keywords Validation** `object`
>
> Keywords configuration errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Keywords must be an array of strings."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Keywords must be strings."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Keywords each must be less than 100 characters: [keyword]"
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Keywords must be in the format 'string' or 'string:number'."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Keyword boosts with a colon must have a valid integer for the boost rate."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "At most 20 keywords can be added."
> }
> ```
>
> **400 - Timezone Validation** `object`
>
> Timezone validation errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Timezone must be a string."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid timezone: [error_message]"
> }
> ```
>
> **400 - Summary Prompt Validation** `object`
>
> Summary prompt validation errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Summary prompt must be a string."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Summary prompt must be less than 2000 characters."
> }
> ```
>
> **400 - Start Time Validation** `object`
>
> Start time scheduling validation errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "start_time must be a string."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid start_time."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Calls must be scheduled at least 5 minutes in advance, or more"
> }
> ```
>
> **400 - Background Track Validation** `object`
>
> Background track validation errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "background_track must be a string."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid background_track option. Options are: [list_of_options]."
> }
> ```
>
> **400 - Max Duration Validation** `object`
>
> Max duration validation errors.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "max_duration must be a number."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "max_duration must be a positive number."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "max_duration must be at most 12 hours."
> }
> ```
>
> **400 - Invalid Dynamic Data** `object`
>
> Dynamic data or tools configuration is invalid.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Unable to parse dynamic data/tools."
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid tools: [error_message]"
> }
> ```
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid dynamic data: [error_message]"
> }
> ```
>
> **400 - Invalid Pathway Data** `object`
>
> Pathway configuration is invalid or missing required components.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid pathway data - no blocks or links found for pathway {pathway_id}"
> }
> ```
>
> **Other variations:**
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid pathway data"
> }
> ```
>
> **400 - Invalid Start Node ID** `object`
>
> The specified start node ID does not exist in the pathway.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid start node ID: {start_node_id}"
> }
> ```
>
> **400 - Content Flagged** `object`
>
> Content failed moderation and was flagged as inappropriate.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Flagged Node: [flagged content]"
> }
> ```
>
> **400 - Sensitive Number Protection** `object`
>
> Attempting to call emergency or sensitive numbers.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Cannot dial sensitive numbers. More attempts will result in being blocked."
> }
> ```
>
> **400 - Unable to Save Request** `object`
>
> Server unable to save the request body or call data.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Unable to save request body."
> }
> ```
>
> **400 - Unable to Queue Call** `object`
>
> Call could not be queued for processing.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Unable to queue call."
> }
> ```
>
> **400 - Warm Transfer Parent Call Completed** `object`
>
> Parent call for warm transfer has already completed or doesn't exist.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Parent call has completed or does not exist. Warm Transfer Request Cancelled"
> }
> ```
>
> **500 - Internal Server Errors** `object`
>
> General server errors and catch-all error handlers.
>
> ```json theme={null}
> {
>   "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
>
> **400 - Call Parameters Validation** `object`
>
> Basic call parameters validation from the main validation function.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Call parameters must be an object."
> }
> ```
>
> ### Business Logic Errors
>
> **402 - No Billing Record** `object`
>
> No billing record found for your account.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "No billing record found."
> }
> ```
>
> **402 - Insufficient Balance** `object`
>
> Account balance is insufficient for the call.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Insufficient balance."
> }
> ```
>
> **404 - Pathway Not Found** `object`
>
> The specified pathway ID does not exist or is not accessible.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Pathway with ID \"{pathway_id}\" not found"
> }
> ```
>
> **404 - Pathway Version Not Found** `object`
>
> The specified pathway version does not exist.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Pathway version with ID \"{version_number}\" not found"
> }
> ```
>
> **418 - Invalid Objective** `object`
>
> The objective parameter failed validation (returns validation details).
>
> ```json theme={null}
> {
>   "error": "OBJECTIVE_VALIDATION_ERROR",
>   "details": "Custom validation response"
> }
> ```
>
> ### Service Errors (HTTP 500)
>
> **500 - Twilio Connection Error** `object`
>
> Failed to establish connection with Twilio services.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error in creating Twilio connection."
> }
> ```
>
> **500 - Invalid Encrypted Key** `object`
>
> The encrypted key provided is invalid or corrupted.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Invalid `encrypted_key`. Please use the correct key for your account."
> }
> ```
>
> **500 - Internal Server Error** `object`
>
> General internal server error during call processing.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error triggering call. Please check your twilio account for errors"
> }
> ```
>
> **500 - Content Moderation Error** `object`
>
> Error occurred during the content flagging process.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Internal server error during flagging process"
> }
> ```
>
> **500 - BYOT Number Error** `object`
>
> Error retrieving Bring Your Own Twilio (BYOT) phone number.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error in getting BYOT Number"
> }
> ```
>
> **500 - Dialer Data Error** `object`
>
> Error retrieving dialer data from encrypted key.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error in getting dialer data from encrypted key"
> }
> ```
>
> **500 - User Data Fetch Error** `object`
>
> Error fetching user data for account verification.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error in fetching user data"
> }
> ```
>
> **Other variations:**
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Error in fetching parent user data"
> }
> ```
>
> **500 - Retry Call Error** `object`
>
> Missing retry attempt information for retry calls.
>
> ```json theme={null}
> {
>   "status": "error",
>   "message": "Retry attempt not provided for retry call: {call_id}"
> }
> ```

***

Docs for agents: [llms.txt](https://docs.bland.ai/llms.txt)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.