> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.formantai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.formantai.com/_mcp/server.

# Batch Calls

> Upload CSV campaigns and inspect batch call performance.

Batch calls let you start many outbound calls from a CSV file.

## Upload a batch

```http
POST /v1/batch-call
```

```bash
curl -X POST "https://api.voice.formantai.com/v1/batch-call" \
  -H "Authorization: Bearer $FORMANT_API_KEY" \
  -F "agent_id=123" \
  -F "name=March Follow Ups" \
  -F "file=@contacts.csv"
```

### CSV format

The CSV must include `customer_phone`. Other columns become call parameters.

```csv
customer_phone,customer_name,loan_id,due_amount
+919876543210,Rahul,LN-12345,29000
+919812345678,Anita,LN-67890,15000
```

### Response

```json
{
  "data": {
    "id": 456,
    "name": "March Follow Ups",
    "agent_id": 123,
    "status": "pending",
    "total_recipients": 500,
    "created_at": "2026-03-16T10:30:00Z"
  }
}
```

## List batches

```http
GET /v1/batch-calls
```

```bash
curl "https://api.voice.formantai.com/v1/batch-calls?agent_id=123&limit=20&offset=0" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

| Query parameter | Type    | Description                  |
| --------------- | ------- | ---------------------------- |
| `agent_id`      | integer | Optional filter by agent.    |
| `limit`         | integer | Default `20`, maximum `100`. |
| `offset`        | integer | Pagination offset.           |

## Get one batch

```http
GET /v1/batch-calls/{batch_id}
```

```bash
curl "https://api.voice.formantai.com/v1/batch-calls/456" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

## Get batch metrics

```http
GET /v1/batch-calls/{batch_id}/metrics
```

```bash
curl "https://api.voice.formantai.com/v1/batch-calls/456/metrics" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
```

```json
{
  "data": {
    "avg_duration_seconds": 125.5,
    "busy_count": 15,
    "completed_count": 420,
    "failed_count": 30,
    "in_progress_count": 5,
    "no_answer_count": 20,
    "pending_retry_count": 10,
    "socket_failure_count": 0,
    "success_count": 420,
    "success_rate": 84.0,
    "total_processed": 485,
    "unreachable_count": 0
  }
}
```

## Best practices

* Upload a small test batch before a production campaign.
* Keep variable column names stable across prompts, webhooks, and CRM mappings.
* Use webhooks to process completed outcomes instead of repeatedly polling.
* Use batch metrics for campaign-level reporting and Conversations for per-call details.