Skip to main content
POST
cURL
This is the API route. To run batches from the platform, upload your CSV under Deploy → Batches in the dashboard — see Batch Calling from the dashboard.
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 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
Python (stdlib)
201 Response

Split a batch across agent versions

Pass version_split to split the batch’s contacts across 2 to 4 versions of the agent, by percentage:
curl
  • Each arm needs a different agent_version_id of this agent, and a whole-number weight from 1 to 99. The weights must add up to 100.
  • Every contact is assigned a version when the batch is created. The split is exact: 70/30 of 10 contacts calls 7 on the first version and 3 on the second, in random order. Retries keep the contact’s version.
  • Calls outside the batch keep using the live version.
  • Every version must use the live version’s telephony provider.
  • Batches with a workflow can’t be A/B tested.
An invalid version_split returns 400 with a message saying what’s wrong. List all batches and Get batch return the split as version_split, with each version’s version_name. To see which version handled each call, read agent_version_id on the batch’s executions. For every way to A/B test versions, see A/B test agent versions.

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)
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
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:
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],"prioritize_retries":true}

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"

version_split
string

JSON string that splits the batch's contacts across 2 to 4 versions of the agent for an A/B test. Each arm needs a different agent_version_id that belongs to this agent and isn't deleted, and a whole-number weight from 1 to 99. The weights must add up to 100. Each contact is assigned a version when the batch is created, and its retries keep that version. Calls outside the batch keep using the live version. Every version must use the live version's telephony provider. Not supported on batches with a workflow. Example - {"arms":[{"agent_version_id":"0c6a5e0e-7b8f-4d1a-9f2e-3a4b5c6d7e8f","weight":50},{"agent_version_id":"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b","weight":50}]}

Example:

"{\"arms\":[{\"agent_version_id\":\"0c6a5e0e-7b8f-4d1a-9f2e-3a4b5c6d7e8f\",\"weight\":50},{\"agent_version_id\":\"9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b\",\"weight\":50}]}"

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