Skip to main content
POST
/
batch-calls
Create a batch call
curl --request POST \
  --url https://api.dialnexa.com/v1/batch-calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form agent_id=agt_abc123 \
  --form file='@example-file' \
  --form 'from_phone_number=+912234567890' \
  --form 'name=May Follow-Up Campaign' \
  --form scheduled_at=2023-11-07T05:31:56Z \
  --form max_concurrent_calls=10 \
  --form 'retry_config={
  "max_retries": 2,
  "retry_interval_minutes": 60
}'
{
  "id": "batch_abc123",
  "name": "May Follow-Up Campaign",
  "status": "initiated",
  "total_leads": 250,
  "completed": 235,
  "failed": 15,
  "agent_id": "agt_abc123",
  "created_at": "2024-03-01T10:00:00.000Z"
}
A batch call lets you upload a CSV or XLSX file of contacts and trigger a single outbound call to each one. Every row in the file becomes one call. The batch starts processing immediately (or at a scheduled time) and calls are made concurrently up to your configured limit.

​
File format

Your file must include a phone_number column. All other column headers become dynamic variables that are injected into the agent’s prompt for each individual call:
phone_numbercustomer_nameloan_amountproduct
9876543210Priya Sharma500000home_loan
9123456789Rahul Mehra250000car_loan
In your agent prompt, reference these as {{customer_name}}, {{loan_amount}}, etc.

​
Batch vs. Campaign

Use a batch call for a one-shot outreach where you upload the full list upfront and don’t need to add leads later. If you need ongoing lifecycle control (pause, resume, add leads incrementally), use Campaigns instead.

​
File requirements

  • Formats: CSV, XLSX, XLS
  • Max size: 10 MB
  • Required column: phone_number
  • Phone numbers should be valid international numbers. Include the country code for non-local destinations.

​
Destination validation

Before launch, each row is checked against the outbound route selected for the batch. For non-SIP routes, the destination country and prefix must be enabled in Workspace Settings > Telephony Config. If one or more rows fail validation, the API returns 400 Bad Request with grouped error details, including the affected row numbers. Common reasons include invalid phone number format, unsupported destination country, unsupported prefix, or no enabled countries configured.

​
Request example

This is a multipart/form-data request. Use the interactive tester above or the following curl example: 
curl -X POST https://api.dialnexa.com/v1/batch-calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "agent_id=agt_abc123" \
  -F "from_phone_number=+912234567890" \
  -F "name=May Follow-Up Run" \
  -F "max_concurrent_calls=10" \
  -F "file=@contacts.csv"

Authorizations

​
Authorization
string
header
required

Pass your API key as a Bearer token in the Authorization header.

Body

multipart/form-data
​
agent_id
string
required
Example:

"agt_abc123"

​
file
file
required

CSV, XLSX, or XLS file. Max 10 MB. Required column: phone_number. All other columns become dynamic variables. Destination numbers must pass workspace route validation.

​
from_phone_number
string
Example:

"+912234567890"

​
name
string
Example:

"May Follow-Up Campaign"

​
scheduled_at
string<date-time>
​
max_concurrent_calls
integer
Example:

10

​
retry_config
object

Response

Batch created.

​
id
string
Example:

"batch_abc123"

​
name
string
Example:

"May Follow-Up Campaign"

​
status
enum<string>

Create acknowledgement status or batch campaign lifecycle status. Legacy create responses can return initiated before later reads show draft, active, running, paused, completed, or cancelled.

Available options:
initiated,
draft,
active,
running,
paused,
completed,
cancelled
Example:

"initiated"

​
total_leads
integer
Example:

250

​
completed
integer
Example:

235

​
failed
integer
Example:

15

​
agent_id
string
Example:

"agt_abc123"

​
created_at
string<date-time>
Example:

"2024-03-01T10:00:00.000Z"