Create Batch API

POST

batches

cURL

curl --request POST \
  --url https://api.bolna.ai/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form agent_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form file='@example-file' \
  --form 'from_phone_numbers[0]=+919876543210' \
  --form 'from_phone_numbers[1]=+919876543211' \
  --form 'retry_config=<string>' \
  --form webhook_url=https://your-server.com/batch-webhook

import requests

url = "https://api.bolna.ai/batches"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from_phone_numbers[0]": "+919876543210",
    "from_phone_numbers[1]": "+919876543211",
    "retry_config": "<string>",
    "webhook_url": "https://your-server.com/batch-webhook"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('agent_id', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('file', '<string>');
form.append('from_phone_numbers[0]', '+919876543210');
form.append('from_phone_numbers[1]', '+919876543211');
form.append('retry_config', '<string>');
form.append('webhook_url', 'https://your-server.com/batch-webhook');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.bolna.ai/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/batches"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/batches")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "batch_id": "3c90c3cc0d444b5088888dd25736052a",
  "state": "created"
}

{
  "error": 123,
  "message": "<string>"
}

Creates a new batch campaign by uploading a CSV of recipients. Returns HTTP 201 with a batch_id. The batch does not start calling until you call POST /batches/{batch_id}/schedule.

CSV format

contact_number,customer_name,appointment_day
+919876543210,Asha,Friday
+919812345678,Ravi,Monday

contact_number is required — E.164 format
Any other column becomes a {variable} available in your agent’s prompt and welcome message
The per-call execution stores these columns in context_details.recipient_data

Example request

Use multipart/form-data — not JSON.

curl

curl https://api.bolna.ai/batches \
  -H "Authorization: Bearer $BOLNA_API_KEY" \
  -F "agent_id=123e4567-e89b-12d3-a456-426655440000" \
  -F "file=@recipients.csv"

Python (stdlib)

import os, urllib.request
from io import BytesIO

# See public/examples/bolna_batch_test.py for a complete implementation

201 Response

{
  "batch_id": "3c90c3cc0d444b5088888dd25736052a",
  "state": "created"
}

Next step: schedule the batch

A created batch is idle until scheduled. Call POST /batches/{batch_id}/schedule with a scheduled_at timestamp:

Schedule request (form-data)

scheduled_at=2026-06-23T18:30:00+00:00

Use a numeric UTC offset like +00:00 — the Z suffix is rejected with a 500. The time must be at least 2 minutes in the future, and Bolna rounds the start up to the next 10-minute mark.

See the Batch Quickstart for a complete walk-through including scheduling and result retrieval.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

multipart/form-data

agent_id

string<uuid>

required

The ID of the agent

file

required

CSV file to upload

from_phone_numbers

string[]

List of phone numbers from which the batch calls will be made. Each number must include the country code in E.164 format. Pass multiple values to use multiple originating numbers.

Example:

["+919876543210", "+919876543211"]

retry_config

string

JSON string containing retry configuration for failed calls. See auto-retry documentation for details. Example - {"enabled":true,"max_retries":2,"retry_intervals_minutes":[15,30]}

webhook_url

string<uri>

URL that Bolna POSTs the batch payload to when the batch finishes processing, and again when all of its executions reach a terminal state. Use it to receive the batch's executions without polling. Must be a valid URL; an invalid value is ignored and no webhook is sent.

Example:

"https://your-server.com/batch-webhook"

Response

batch created response

batch_id

string<^[0-9a-fA-F]{32}$>

required

The ID of the batch

Example:

"3c90c3cc0d444b5088888dd25736052a"

state

enum<string>

required

Status of the request

Available options:

created

⌘I

cURL

curl --request POST \
  --url https://api.bolna.ai/batches \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form agent_id=3c90c3cc-0d44-4b50-8888-8dd25736052a \
  --form file='@example-file' \
  --form 'from_phone_numbers[0]=+919876543210' \
  --form 'from_phone_numbers[1]=+919876543211' \
  --form 'retry_config=<string>' \
  --form webhook_url=https://your-server.com/batch-webhook

import requests

url = "https://api.bolna.ai/batches"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "agent_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from_phone_numbers[0]": "+919876543210",
    "from_phone_numbers[1]": "+919876543211",
    "retry_config": "<string>",
    "webhook_url": "https://your-server.com/batch-webhook"
}
headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('agent_id', '3c90c3cc-0d44-4b50-8888-8dd25736052a');
form.append('file', '<string>');
form.append('from_phone_numbers[0]', '+919876543210');
form.append('from_phone_numbers[1]', '+919876543211');
form.append('retry_config', '<string>');
form.append('webhook_url', 'https://your-server.com/batch-webhook');

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

options.body = form;

fetch('https://api.bolna.ai/batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.bolna.ai/batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bolna.ai/batches"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.bolna.ai/batches")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.bolna.ai/batches")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\n3c90c3cc-0d44-4b50-8888-8dd25736052a\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B0%5D\"\r\n\r\n+919876543210\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"from_phone_numbers%5B1%5D\"\r\n\r\n+919876543211\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"retry_config\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"webhook_url\"\r\n\r\nhttps://your-server.com/batch-webhook\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "batch_id": "3c90c3cc0d444b5088888dd25736052a",
  "state": "created"
}

{
  "error": 123,
  "message": "<string>"
}

Overview

Agents

Calls

Executions

Batches

Inbound

Phone Numbers

Knowledgebases

Dispositions

Providers

Sub-Accounts

Voice

User

SIP Trunks (BYOT)

Violations

Legacy APIs

CSV format

Example request

Next step: schedule the batch

Authorizations

Body

Response

​CSV format

​Example request

​Next step: schedule the batch

Authorizations

Body

Response

CSV format

Example request

Next step: schedule the batch