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

# Batch Calls

> Send out a batch of calls to a csv of recipients.

## Introduction

Batch calls let you run high-volume call campaigns by uploading a list of recipients as a CSV. One agent staffs every call in the batch, and you monitor progress and results from the dashboard.

Common use cases include:

> [card] Outbound Campaigns
>
> Reach customers with limited-time offers or updates.

> [card] Customer Reminders
>
> Follow up with clients for appointments, payments, or check-ins.

> [card] Lead Qualification
>
> Qualify or re-engage leads from your CRM or sign-up funnel.

> [card] Data Collection
>
> Prompt users for updated contact info, preferences, or survey responses.

***

## Creating a Batch Call

Batches live under Dispatch in the dashboard sidebar. At **All agents** you choose the agent. Inside an agent, that agent is filled in and locked.

To start a batch call:

1. Open **Batches** under Dispatch and press **Create Batch** in the top bar.
2. **Recipients**: upload your CSV.
3. **Script**: pick the agent that staffs the batch and write the instructions for this run.
4. **Review & send**: check the first recipient as the agent will get them, name the batch, and press **Start calling**.

See [Run a batch](https://docs.bland.ai/agents/dispatch.md#run-a-batch) for the full wizard.

Batch calls are built around a CSV file containing all information on your recipients, with each row representing a single recipient.

### Required Fields

Your uploaded CSV must include a column named `phone_number`, in exactly that spelling. Every number needs a country code: `+14155550100` works, `4155550100` does not.

Additional columns can be included to define dynamic variables referenced during the call.

> **Important**: Column names cannot contain spaces since they are used as variables. Use underscores or camelCase instead (for example, `customer_name` or `customerName`, not `customer name`).

Example format:

| phone\_number | business\_name | previous\_customer | champion\_name | webhook |
| - | - | - | - | - |
| +12345678909 | South Bay Coffee | Yes | Sarah H | [https://example.com/webhook1](https://example.com/webhook1) |
| +10987654321 | John's Laundry | No | John W | [https://example.com/webhook2](https://example.com/webhook2) |

With this CSV, we are aiming to send 2 calls out in our batch, to +12345678909 and +10987654321.

In each of those calls, the agent can use the information in the other columns (business\_name, previous\_customer, champion\_name), similar to request data in a normal call. The `webhook` column matches a call setting name, so check how it is mapped (see **Watch the defaults** below).

On the Script step, under **How your columns are used**, each column gets a dropdown. **Use as `{{column}}`** makes the value available in the prompt as `{{column_name}}`.

> **Watch the defaults**: a column named after a call setting, like `from` or `voice`, defaults to setting that field per call rather than becoming a variable. Rename the column if you meant it as a variable.

When you create a batch through the API, each entry in `call_objects` follows the same schema as `/v1/calls`, so pass per-recipient values in that entry's `request_data`.

***

## Monitoring Batch Progress

You can monitor batch progress in two ways: **polling** the batch and logs endpoints, or **receiving status webhooks** when using the API.

### Status webhook (API)

When creating a batch via the API, you can pass an optional **`status_webhook`** URL. We will send HTTP POST requests to that URL at each major lifecycle step and when the batch finishes, so you get push updates without polling.

**When we call it:** We POST once per phase: `validating` → `dispatching` → `in_progress` (or `in_progress_chunked` for large batches) → optionally `waiting_for_scheduled_calls` → then one final event: `completed`, `failed`, or `completed_partial`. Each request is JSON with `batch_id`, `status`, and `timestamp`; final events include call counts or error `code` and `reason` when applicable.

**Best practice:** Your endpoint should respond with **200 within a few seconds**. Do any heavy processing asynchronously so the batch workflow is not delayed (we wait up to 10 seconds per webhook call).

See the [Create Batch API reference](https://docs.bland.ai/api-v2/post/batches.md#status-webhook) for the full payload shape and example bodies.

### Dashboard and polling

After launching a batch, return to **Batches** under Dispatch. Each batch is listed with its **Status**, **Name**, **Batch ID**, and **Created** time, newest first with active batches on top.

Each row has two icon buttons. The first opens [Conversations](https://docs.bland.ai/agents/conversations.md) filtered to that batch. The second stops the calls that have not been placed yet, and asks first. Select a row for a detail panel with the event log and its own **Stop Batch** button, which stops the batch without asking.

### Understanding Batch Statuses

Your batch will progress through various statuses as it processes. Here's what each status means:

> [accordion] Active Statuses (In Progress)
>
> * **Initializing** - The batch is being set up and prepared for processing. This happens immediately after creation.
> * **Validating** - The system is verifying your CSV format, phone numbers, and call parameters before dispatching.
> * **Dispatching** - Calls are being actively sent out to recipients from your CSV.
> * **In Progress** - Calls are actively being processed and conversations are ongoing.
> * **In Progress (Chunked)** - Large batches are being processed in smaller chunks for better performance.
> * **Waiting for Scheduled Calls** - The batch is waiting for calls with specific start times to be executed.
> * **Unknown** - In the dashboard list, a batch past its first thousand calls that is still running. Use **Stop Batch** in the detail panel to stop it.

> [accordion] Final Statuses (Completed)
>
> * **Completed** - All calls in the batch were successfully processed and finished.
> * **Completed Partial** - The batch ended early, usually because you stopped it. Check the logs for details.
> * **Failed** - The batch ended on an error. Review the error logs for troubleshooting.

***

## Example Use Case

Let's say you're running a follow-up campaign for returning customers.

Upload a CSV like:

| phone\_number | customer\_name | service | date |
| - | - | - | - |
| +12345678909 | Emily | Home Cleaning | July 10 |

Then write the instructions on the Script step:

```text theme={null}
Hi {{customer_name}}, just checking in to see if you'd like to 
schedule your next {{service}}. We're available as early as {{date}}. 
Would you like me to get that on the books?
```

The agent personalizes each call using the values from that row in your CSV.

***

## Frequently Asked Questions

> [accordion] What happens if a number is invalid?
>
> A CSV with one bad row is rejected whole. The upload checks every number before the batch exists, names up to three of the bad rows, and counts the rest. Duplicates and numbers on your do-not-call list are different: those are dropped at dial time and the rest of the batch runs.

> [accordion] Can I use tools with batch calls?
>
> Yes. The agent that staffs the batch brings its own configuration, including its tools.

> [accordion] How do I access individual results?
>
> Use the first icon button on the batch's row to open [Conversations](https://docs.bland.ai/agents/conversations.md) filtered to that batch, then open each call's transcript and details.

> [accordion] How do I send a batch via API?
>
> You can use our API to send a batch call. See our [API Reference](https://docs.bland.ai/api-v2/post/batches.md) for more details.

***

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.