Skip to navigation
API Guides

Batch Calls

View as Markdown

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

Upload a batch

POST /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.

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

Response

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

List batches

GET /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

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

Get batch metrics

GET /v1/batch-calls/{batch_id}/metrics
curl "https://api.voice.formantai.com/v1/batch-calls/456/metrics" \
  -H "Authorization: Bearer $FORMANT_API_KEY"
{
  "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.