API Guides

Batch Calls

View as Markdown

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

Upload a batch

1POST /v1/batch-call
$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.

1customer_phone,customer_name,loan_id,due_amount
2+919876543210,Rahul,LN-12345,29000
3+919812345678,Anita,LN-67890,15000

Response

1{
2  "data": {
3    "id": 456,
4    "name": "March Follow Ups",
5    "agent_id": 123,
6    "status": "pending",
7    "total_recipients": 500,
8    "created_at": "2026-03-16T10:30:00Z"
9  }
10}

List batches

1GET /v1/batch-calls
$curl "https://api.voice.formantai.com/v1/batch-calls?agent_id=123&limit=20&offset=0" \
>  -H "Authorization: Bearer $FORMANT_API_KEY"
Query parameterTypeDescription
agent_idintegerOptional filter by agent.
limitintegerDefault 20, maximum 100.
offsetintegerPagination offset.

Get one batch

1GET /v1/batch-calls/{batch_id}
$curl "https://api.voice.formantai.com/v1/batch-calls/456" \
>  -H "Authorization: Bearer $FORMANT_API_KEY"

Get batch metrics

1GET /v1/batch-calls/{batch_id}/metrics
$curl "https://api.voice.formantai.com/v1/batch-calls/456/metrics" \
>  -H "Authorization: Bearer $FORMANT_API_KEY"
1{
2  "data": {
3    "avg_duration_seconds": 125.5,
4    "busy_count": 15,
5    "completed_count": 420,
6    "failed_count": 30,
7    "in_progress_count": 5,
8    "no_answer_count": 20,
9    "pending_retry_count": 10,
10    "socket_failure_count": 0,
11    "success_count": 420,
12    "success_rate": 84.0,
13    "total_processed": 485,
14    "unreachable_count": 0
15  }
16}

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.