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

# Batch Calls

# Batch Calls

Manage high-volume outbound calling batches.

## List Batch Calls

<Endpoint method="GET" path="/api/public/v1/batch-calls" />

**Query:** `agent_id` (optional), `status` (optional), `limit` (default 50, max 100), `offset` (default 0). Response includes `data` (array of batch call objects) and pagination.

## Get Batch Call

<Endpoint method="GET" path="/api/public/v1/batch-calls/{batch_call_id}" />

## Create Batch Call

<Endpoint method="POST" path="/api/public/v1/batch-calls" />

**Request body**

| Field                     | Type                  | Required           | Description                                                                       |
| ------------------------- | --------------------- | ------------------ | --------------------------------------------------------------------------------- |
| `name`                    | string                | Yes                | Campaign name (1–255 chars).                                                      |
| `agent_id`                | string (UUID)         | Yes                | Agent that will make the calls.                                                   |
| `phone_number_ids`        | array of UUIDs        | No                 | Outbound number IDs. If empty, numbers assigned to the agent are used.            |
| `phone_rotation_strategy` | string                | No                 | `random`, `sequential`, or `round_robin`. Default `random`.                       |
| `contact_source`          | string                | No                 | `csv`, `folder`, or `manual`. Default `csv`.                                      |
| `contact_folder_id`       | string (UUID)         | When source=folder | Required when `contact_source` is `folder`; contacts are loaded from this folder. |
| `schedule_type`           | string                | No                 | `immediate` or `scheduled`. Default `immediate`.                                  |
| `scheduled_at`            | string (ISO datetime) | When scheduled     | Required when `schedule_type` is `scheduled`.                                     |
| `timezone`                | string                | No                 | Default `UTC`.                                                                    |
| `start_time`, `end_time`  | string (HH:MM)        | No                 | Daily calling window.                                                             |
| `working_days`            | array of int          | No                 | 1=Mon … 7=Sun. Default `[1,2,3,4,5]`.                                             |
| `max_concurrent_calls`    | int                   | No                 | 1–100. Default 10.                                                                |
| `max_calls_per_day`       | int                   | No                 | Optional cap per day.                                                             |
| `retry_failed`            | boolean               | No                 | Default false.                                                                    |
| `max_retry_attempts`      | int                   | No                 | 0–3. Default 0.                                                                   |

Send `X-Idempotency-Key` for safe retries. The agent must exist and be active and ready for calls; at least one valid outbound phone number is required (assigned to the agent or in `phone_number_ids`).

**Example**

```json theme={null}
{
  "name": "Q1 Outreach",
  "agent_id": "AGENT_UUID",
  "contact_source": "folder",
  "contact_folder_id": "FOLDER_UUID",
  "schedule_type": "immediate",
  "max_concurrent_calls": 5
}
```

**Response:** 201 Created with `data` (batch call object: `id`, `name`, `agent_id`, `status` (e.g. `draft`), `contact_source`, and other configured fields) and `meta`.

## Update Batch Call

<Endpoint method="PATCH" path="/api/public/v1/batch-calls/{batch_call_id}" />

**Body:** Any of `name`, `phone_number_ids`, `phone_rotation_strategy`, `scheduled_at`, `start_time`, `end_time`, `working_days`, `max_concurrent_calls`, `max_calls_per_day`, `retry_failed`, `max_retry_attempts`. Only allowed when the batch is in **draft** status.

## Delete Batch Call

<Endpoint method="DELETE" path="/api/public/v1/batch-calls/{batch_call_id}" />

## Schedule Batch Call

<Endpoint method="POST" path="/api/public/v1/batch-calls/{batch_call_id}/schedule" />

Starts the batch (draft with contacts). Returns **422** if the batch is not in draft, has no contacts, or scheduling fails (e.g. provider error).

## Pause Batch Call

<Endpoint method="POST" path="/api/public/v1/batch-calls/{batch_call_id}/pause" />

Pauses an active or scheduled batch. Returns **422** with a message if the batch is not in `active` or `scheduled` status (e.g. already paused or still draft).

## Resume Batch Call

<Endpoint method="POST" path="/api/public/v1/batch-calls/{batch_call_id}/resume" />

Resumes a paused batch. Returns **422** if the batch is not in `paused` status.