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

***

## Headers

<ParamField header="authorization" type="string" required>
  Your API key for authentication.
</ParamField>

<ParamField header="encrypted_key" type="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](/tutorials/custom-twilio).
</ParamField>

***

## Body Parameters

### Basic Parameters

<ParamField body="phone_number" type="string" required>
  The phone number to call. Must be a valid phone number in [E.164](https://en.wikipedia.org/wiki/E.164) format.
</ParamField>

<ParamField body="voice" type="string">
  The voice of the AI agent to use. Accepts any form of voice ID, including custom voice clones and voice presets.

  Default voices can be referenced directly by their name instead of an id.

  Usage example: voice: "maya"

  Bland Curated voices:

  * Josh
  * Florian
  * Derek
  * June
  * Nat
  * Paige
</ParamField>

<ParamField body="pathway_id" type="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"
  }
  ```
</ParamField>

<ParamField body="pathway_version" type="integer">
  The version number of the pathway to use for the call. Defaults to the production version.
</ParamField>

<ParamField body="task" type="string" required>
  Note: Do not specify if using a pathway.

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

  This is your prompt where you are telling the agent what to do.

  Recommendations:

  * Include context and a background/persona for the agent like `"You are {name}, a customer service agent at {company} calling {name} about {reason}`.
  * Phrase instructions like you are speaking to the agent before the call.
  * Any time you tell the agent not to do something, provide an example of what they should do instead.
  * Keep the prompt under 2,000 characters where possible.
</ParamField>

<ParamField body="first_sentence" type="string">
  Makes your agent say a specific phrase or sentence for it's first response.
</ParamField>

<ParamField body="persona_id" type="string">
  The ID of the persona to use for the call.

  Personas act as pre-configured templates that automatically apply a configuration when you pass a persona\_id to an outbound call. Think of them as "call presets" that you can reuse across multiple calls.

  When using a persona\_id, any parameters specified in your request body will override the corresponding parameters from the persona's configuration.

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

### Model Parameters

<ParamField body="model" default="base" type="string">
  Select a model to use for your call.

  Options: `base` or `turbo`.

  In nearly all cases, `base` is the best choice.

  <Accordion title="Model Differences">
    There are two different ways to use Bland:

    * `model: base`
      * The original, follows scripts/procedures most effectively.
      * Supports all features and capabilities.
      * Best for Custom Tools
    * `model: turbo`
      * The absolute fastest latency possible, can be verbose at times
      * Limited capabilities currently (excludes Transferring, IVR navigation, Custom Tools)
      * Extremely realistic conversation capabilities
  </Accordion>
</ParamField>

<ParamField body="language" default="babel-en" type="string">
  Select a supported language of your choice. Optimizes every part of our API for that language - transcription, speech, and other inner workings.

  <Accordion title="Expand to view language options">
    The available language options are as follows:

    * `babel` - Babel (All Languages) - Experimental<sup>1</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.**
  </Accordion>
</ParamField>

<ParamField body="wait_for_greeting" default="false" type="boolean">
  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.
</ParamField>

<ParamField body="pronunciation_guide" type="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 title="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`.
  </Accordion>
</ParamField>

<ParamField body="temperature" default={0.7} type="float">
  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"
</ParamField>

<ParamField body="interruption_threshold" default="500" type="number">
  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.
</ParamField>

### Dispatch Parameters

<ParamField body="from" type="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.
</ParamField>

<ParamField body="dialing_strategy" type="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.
</ParamField>

<ParamField body="timezone" default="America/Los_Angeles" type="string">
  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.
</ParamField>

<ParamField body="start_time" type="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.
</ParamField>

<ParamField body="transfer_phone_number" type="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 title="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.
  </Accordion>
</ParamField>

<ParamField body="transfer_list" type="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"
    }
  }
  ```
</ParamField>

<ParamField body="max_duration" default="30" type="integer">
  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
</ParamField>

### Knowledge Parameters

<ParamField body="tools" type="array">
  Add custom tools and knowledge bases 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)
</ParamField>

### Audio Parameters

<ParamField body="background_track" type="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
</ParamField>

<ParamField body="noise_cancellation" default="false" type="boolean">
  Toggles noise filtering or suppression in the audio stream to filter out background noise.
</ParamField>

<ParamField body="block_interruptions" default="false" type="boolean">
  When set to `true`, the AI will not respond or process interruptions from the user.
</ParamField>

<ParamField body="record" default="false" type="boolean">
  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.
</ParamField>

### Voicemail Parameters

<ParamField body="voicemail" type="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`.

  <br />

  * `action` (enum): What the AI should do when it detects a voicemail. The default is `"hangup"`. Available options:
    * `"hangup"`: Immediately end the call without leaving a message.
    * `"leave_message"`: Play the `message` and then end the call.
    * `"ignore"`: Continue the call as if no voicemail was detected (used for IVRs or special routing).

  <br />

  * `sms` (object): Optional. Configuration for sending an SMS notification when a voicemail is left. Contains:
    * `to` (string): The phone number to send the SMS to (usually the same as the original callee).
    * `from` (string): The phone number to send the SMS from (must be a number you own and have SMS permissions for).
    * `message` (string): The body of the SMS message. Keep concise and clear.

  <br />

  * `sensitive` (boolean): When `true`, uses LLM-based analysis to detect frequent voicemails. The default is `false`.

  Example:

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

### Analysis Parameters

<ParamField body="citation_schema_ids" type="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.
</ParamField>

### Post Call Parameters

<ParamField body="summary_prompt" type="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."
  }
  ```
</ParamField>

<ParamField body="retry" type="object">
  If the call goes to voicemail, you can set up the call to retry, after a configurable delay. You can also update the voicemail\_action, and voicemail\_message in the retry object, for the re-tried call.

  Takes in the following parameters:

  * `wait` (integer): The delay in seconds before the call is retried.
  * `voicemail_action` (enum): The action to take when the call goes to voicemail. Options: `hangup`, `leave_message`, `ignore`.
  * `voicemail_message` (string): The message to leave when the call goes to voicemail.

  Example:

  ```json theme={null}
  {
      "retry": {
          "wait": 10,
          "voicemail_action": "leave_message",
          "voicemail_message": "Hello, this is a test message."
      }
  }
  ```
</ParamField>

<ParamField body="dispositions" type="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 title="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)
  </Accordion>

  Example:

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

### Advanced Parameters

<ParamField body="request_data" type="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".
</ParamField>

<ParamField body="metadata" type="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"
    }
  }
  ```
</ParamField>

<ParamField body="webhook" type="string">
  When the call ends, call information is sent to this webhook URL.
</ParamField>

<ParamField body="webhook_events" type="array">
  Specify which events you want to stream to the webhook, during the call.

  <Info>
    **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](/enterprise-features/citations#webhook-integration-options) for complete setup instructions.
  </Info>

  Options:

  * `queue`
  * `call`
  * `latency`
  * `webhook`
  * `tool`
  * `dynamic_data`
  * `citations` (Required for any citation webhooks)

  Example payloads:

  <CodeGroup>
    ```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"
        }
      ]
    }
    ```
  </CodeGroup>
</ParamField>

<ParamField body="dynamic_data" type="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": ""
          }
        ]
      }
    ],
  ```
</ParamField>

<ParamField body="keywords" default="[]" type="string[]">
  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"]
    }
  ```
</ParamField>

<ParamField body="ignore_button_press" default="false" type="boolean">
  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.
</ParamField>

<ParamField body="precall_dtmf_sequence" type="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"
    }
  ```
</ParamField>

<ParamField body="guard_rails" type="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](/tutorials/guard-rails).

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

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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" }`         |
  </Accordion>

  **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" } }
        ]
      }
    ]
  }
  ```
</ParamField>

## Response

<ResponseField name="status" type="string">
  Can be `success` or `error`.
</ResponseField>

<ResponseField name="message" type="string">
  A message explaining the status of the call.
</ResponseField>

<ResponseField name="call_id" type="string">
  A unique identifier for the call (present only if status is `success`).
</ResponseField>

<ResponseField name="batch_id" type="string">
  The batch ID of the call (present only if status is `success`).
</ResponseField>

<ResponseField name="errors" type="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."
      ]
  }
  ```
</ResponseField>

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

## Error Codes Reference

<Accordion title="View All Error Codes" icon="warning">
  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

  <ResponseField name="401 - AUTH_FAILURE" type="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
  </ResponseField>

  <ResponseField name="403 - Account Flagged" type="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 hello@bland.ai with your account phone number."
    }
    ```
  </ResponseField>

  ### Rate Limiting Errors (HTTP 429)

  <ResponseField name="429 - Call Frequency Limit" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="429 - General Rate Limit" type="object">
    Rate limit exceeded for your account.

    ```json theme={null}
    {
      "status": "error",
      "message": "Rate limit exceeded"
    }
    ```
  </ResponseField>

  <ResponseField name="429 - Blacklisted Number" type="object">
    Attempting to call a blacklisted number.

    ```json theme={null}
    {
      "status": "error",
      "message": "This number is blacklisted."
    }
    ```
  </ResponseField>

  <ResponseField name="429 - New Customer Rate Limit" type="object">
    Rate limits for newly created accounts.

    ```json theme={null}
    {
      "status": "error",
      "message": "Rate limit exceeded for newly created accounts. Please try again soon."
    }
    ```
  </ResponseField>

  <ResponseField name="429 - International Rate Limit" type="object">
    International calling rate limit exceeded.

    ```json theme={null}
    {
      "status": "error",
      "message": "International rate limit exceeded for your account type."
    }
    ```
  </ResponseField>

  ### Parameter Validation Errors (HTTP 400)

  <ResponseField name="400 - Missing Required Parameter" type="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)
  </ResponseField>

  <ResponseField name="400 - Invalid Field Types" type="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"`
  </ResponseField>

  <ResponseField name="400 - Invalid Voicemail Action" type="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, ignore"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Number Range Validation" type="object">
    Numeric values are outside their allowed ranges.

    ```json theme={null}
    {
      "status": "error",
      "message": "Max duration must be at least 1"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid DTMF Sequence" type="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)
  </ResponseField>

  <ResponseField name="400 - Invalid Date Format" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Webhook URL" type="object">
    Webhook URL format is invalid.

    ```json theme={null}
    {
      "status": "error",
      "message": "Webhook must be a valid URI"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid From Number Format" type="object">
    From number doesn't match phone number pattern.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid from number format"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Transfer Phone Format" type="object">
    Transfer phone number format validation error.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid transfer phone number format"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Transfer List Format" type="object">
    Transfer list contains phone numbers with invalid format.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid phone number format in transfer list"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Additional Properties Not Allowed" type="object">
    Request contains fields that are not allowed in the schema.

    ```json theme={null}
    {
      "status": "error", 
      "message": "Additional properties are not allowed"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Phone Number" type="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
  </ResponseField>

  <ResponseField name="400 - Invalid Transfer Number" type="object">
    Transfer phone number is invalid.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid transfer_phone_number."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Language Code" type="object">
    Language code is not supported.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid language code"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Pronunciation Guide" type="object">
    Pronunciation guide format is incorrect.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid pronunciation guide type."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Platform Not Supported" type="object">
    Feature not supported on the specified platform.

    ```json theme={null}
    {
      "status": "error",
      "message": "Precall DTMF sequence is not supported for this platform."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid From Number" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - DNC List Violation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Transfer List Validation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Retry Parameter Validation" type="object">
    Retry configuration must be an object.

    ```json theme={null}
    {
      "status": "error",
      "message": "Retry must be an object."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Version Number Validation" type="object">
    Version number must be a valid number.

    ```json theme={null}
    {
      "status": "error",
      "message": "version_number must be a number."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Pathway Version Validation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - From Phone Number Validation" type="object">
    The 'from' number format is invalid.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid from phone number."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Boolean Parameter Validation" type="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`
  </ResponseField>

  <ResponseField name="400 - First Sentence Validation" type="object">
    First sentence must be a string.

    ```json theme={null}
    {
      "status": "error",
      "message": "First sentence must be a string. type: [actual_type]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Voicemail Message Validation" type="object">
    Voicemail message must be a string.

    ```json theme={null}
    {
      "status": "error",
      "message": "Voicemail message must be a string. type: [actual_type]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Voicemail SMS Validation" type="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]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Interruption Threshold Validation" type="object">
    Interruption threshold must be a number.

    ```json theme={null}
    {
      "status": "error",
      "message": "interruption_threshold must be a number."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Webhook URL Validation" type="object">
    Webhook URL must be a valid HTTPS URL.

    ```json theme={null}
    {
      "status": "error",
      "message": "webhook must be a string that starts with https://."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Request Data Validation" type="object">
    Request data must be an object.

    ```json theme={null}
    {
      "status": "error",
      "message": "request_data must be an object."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Metadata Validation" type="object">
    Metadata must be an object.

    ```json theme={null}
    {
      "status": "error",
      "message": "metadata must be an object."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Analysis Schema Validation" type="object">
    Analysis schema must be an object.

    ```json theme={null}
    {
      "status": "error",
      "message": "analysis_schema must be an object."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Voice Parameter Validation" type="object">
    Voice parameter must be a string.

    ```json theme={null}
    {
      "status": "error",
      "message": "Voice must be a string."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Voicemail Action Validation" type="object">
    Voicemail action must be one of the allowed values.

    ```json theme={null}
    {
      "status": "error",
      "message": "Invalid voicemail_action. Options are: [list_of_options]."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Keywords Validation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Timezone Validation" type="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]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Summary Prompt Validation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Start Time Validation" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Background Track Validation" type="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]."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Max Duration Validation" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Dynamic Data" type="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]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Pathway Data" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Invalid Start Node ID" type="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}"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Content Flagged" type="object">
    Content failed moderation and was flagged as inappropriate.

    ```json theme={null}
    {
      "status": "error",
      "message": "Flagged Node: [flagged content]"
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Sensitive Number Protection" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Unable to Save Request" type="object">
    Server unable to save the request body or call data.

    ```json theme={null}
    {
      "status": "error",
      "message": "Unable to save request body."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Unable to Queue Call" type="object">
    Call could not be queued for processing.

    ```json theme={null}
    {
      "status": "error",
      "message": "Unable to queue call."
    }
    ```
  </ResponseField>

  <ResponseField name="400 - Warm Transfer Parent Call Completed" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Internal Server Errors" type="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
  </ResponseField>

  <ResponseField name="400 - Call Parameters Validation" type="object">
    Basic call parameters validation from the main validation function.

    ```json theme={null}
    {
      "status": "error",
      "message": "Call parameters must be an object."
    }
    ```
  </ResponseField>

  ### Business Logic Errors

  <ResponseField name="402 - No Billing Record" type="object">
    No billing record found for your account.

    ```json theme={null}
    {
      "status": "error",
      "message": "No billing record found."
    }
    ```
  </ResponseField>

  <ResponseField name="402 - Insufficient Balance" type="object">
    Account balance is insufficient for the call.

    ```json theme={null}
    {
      "status": "error",
      "message": "Insufficient balance."
    }
    ```
  </ResponseField>

  <ResponseField name="404 - Pathway Not Found" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="404 - Pathway Version Not Found" type="object">
    The specified pathway version does not exist.

    ```json theme={null}
    {
      "status": "error",
      "message": "Pathway version with ID \"{version_number}\" not found"
    }
    ```
  </ResponseField>

  <ResponseField name="418 - Invalid Objective" type="object">
    The objective parameter failed validation (returns validation details).

    ```json theme={null}
    {
      "error": "OBJECTIVE_VALIDATION_ERROR",
      "details": "Custom validation response"
    }
    ```
  </ResponseField>

  ### Service Errors (HTTP 500)

  <ResponseField name="500 - Twilio Connection Error" type="object">
    Failed to establish connection with Twilio services.

    ```json theme={null}
    {
      "status": "error",
      "message": "Error in creating Twilio connection."
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Invalid Encrypted Key" type="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."
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Internal Server Error" type="object">
    General internal server error during call processing.

    ```json theme={null}
    {
      "status": "error",
      "message": "Error triggering call. Please check your twilio account for errors"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Content Moderation Error" type="object">
    Error occurred during the content flagging process.

    ```json theme={null}
    {
      "status": "error",
      "message": "Internal server error during flagging process"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - BYOT Number Error" type="object">
    Error retrieving Bring Your Own Twilio (BYOT) phone number.

    ```json theme={null}
    {
      "status": "error",
      "message": "Error in getting BYOT Number"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Dialer Data Error" type="object">
    Error retrieving dialer data from encrypted key.

    ```json theme={null}
    {
      "status": "error",
      "message": "Error in getting dialer data from encrypted key"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - User Data Fetch Error" type="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"
    }
    ```
  </ResponseField>

  <ResponseField name="500 - Retry Call Error" type="object">
    Missing retry attempt information for retry calls.

    ```json theme={null}
    {
      "status": "error",
      "message": "Retry attempt not provided for retry call: {call_id}"
    }
    ```
  </ResponseField>
</Accordion>

***

Docs for agents: [llms.txt](/llms.txt)