Create Batch Call

POST

batch-calls

Create Batch Call

curl --request POST \
  --url https://api.dialnexa.com/v1/batch-calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'title=Q3 Follow-up Batch' \
  --form agent_id=agent_abc123 \
  --form agent_version_number=1

import requests

url = "https://api.dialnexa.com/v1/batch-calls"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Q3 Follow-up Batch",
    "agent_id": "agent_abc123",
    "agent_version_number": "1"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('file', 'leads.csv');
form.append('title', 'Q3 Follow-up Batch');
form.append('agent_id', 'agent_abc123');
form.append('agent_version_number', '1');

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

options.body = form;

fetch('https://api.dialnexa.com/v1/batch-calls', 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.dialnexa.com/v1/batch-calls",
  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=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\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.dialnexa.com/v1/batch-calls"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\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.dialnexa.com/v1/batch-calls")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/batch-calls")

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=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001--"

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

{
  "id": "batch_abc123",
  "total_records": 250,
  "dnc_skipped_count": 0,
  "status": "initiated",
  "from_number": "+14155552671",
  "title": "Q3 Follow-up Batch"
}

Billable - retry unsafe A batch call lets you upload a CSV or XLSX file of contacts and trigger a single outbound call to each one. Every row with a phone number becomes one call. A new batch is stored as waiting until the scheduler prepares it, or as scheduled when starts_at is in the future. ends_at, calling_hours_start and calling_hours_end (HH:MM) are stored with the batch but are not enforced by the scheduler today: calls are not held to those hours or stopped at ends_at.

When to use this

One-shot outreach: call a fixed list of contacts you already have in a file, such as appointment reminders or a payment-due campaign.
Scheduled campaigns: upload now and let the batch start at a scheduled time.
Personalized calls at scale: every extra column in your file, apart from the reserved columns below, becomes a dynamic variable in the agent’s prompt, so each contact hears their own details.

If leads arrive continuously or the sequence has multiple steps, use workflows with Upload Workflow Leads instead. For a single immediate call, use Create Call.

File format

Your file must include a phone number column. The header can be phone_number, phone, mobile, mobile_number, cell, telephone or tel; case, spaces, underscores and hyphens in the header are ignored. Every number must start with its country code. Other column headers, apart from the reserved columns below, become dynamic variables that are injected into the agent’s prompt for each individual call:

phone_number	customer_name	loan_amount	product
+919876543210	Priya Sharma	500000	home_loan
+919123456789	Rahul Mehra	250000	car_loan

In your agent prompt, reference these as {{customer_name}}, {{loan_amount}}, etc. An empty cell sets no variable for that row.

Reserved columns

These headers are matched the same way as the phone header and are not passed to the prompt as ordinary variables:

Column	Behaviour
`notes`	Stored on the lead and copied to each call’s `notes`. A JSON object with at most 15 top-level keys, or plain text, which is stored as `{"text": "..."}`. A JSON array, or invalid JSON that starts with `{` or `[`, returns `400`.
`agent_transfer_destinations`	Transfer numbers for that lead, separated by the pipe character. Validated, then passed to the call as the `agent_transfer_destinations` variable. An invalid value returns `400`.
`tags`	Validated, then not saved: batch leads do not keep tags. An invalid value returns `400`.

Row rules

CSV: blank rows and rows with an empty phone number are skipped. A row with more values than the header has columns returns 400; wrap values that contain commas in double quotes. Extra empty values at the end of a row are ignored.
XLSX and XLS: only the first sheet is read, and a row with an empty phone number returns 400. Values in a column with no header are skipped.
A file with no usable phone number returns 400.

Batch vs. Campaign

Use a batch call for a one-shot outreach where you upload the full list upfront and do not need to add leads later. If you need to stop and restart execution, use Update Batch Call Status. If you need incremental lead enrollment, use workflows.

Queue Behavior

Multiple batches can run concurrently in one workspace and share its available calling capacity. A waiting batch is awaiting scheduler preparation; it does not need another batch to finish first. Future-start batches remain scheduled until eligible for preparation. See the batch lifecycle state machine before automating status changes. Treat create requests as billable and retry unsafe. If the client times out, call List Batch Calls before repeating the upload so you do not create a duplicate batch. The create response no longer includes a scheduling-conflict warning for other batches. Available concurrency and call-start capacity still determine how quickly calls are placed. The create response always reports status: "initiated" and does not include created_at. The stored batch is already waiting or scheduled; read its real status from List Batch Calls.

File requirements

Formats: CSV, XLSX, XLS
Max size: 10 MB. A larger file returns 413.
Required column: a phone number column, as described in File format
Batch title: 35 characters or fewer
Every phone number must start with its country code, for example +919876543210. A leading + or 00 is optional, so 919876543210 is read the same way, but 9876543210 is read as country code 98 and fails validation.
The workspace needs a billing plan and a spendable wallet balance, and must be under its monthly spend cap; otherwise the API returns 402 Payment Required.
Rows whose number is on the workspace’s DNC list are left out: no lead is created for them, and dnc_skipped_count in the response counts them. If every row’s number is on the DNC list, the API returns 400 and no lead is created. A queued call whose number is added to the DNC list before it dials fails with end_reason dnc_blocked.

agent_version_number is optional. If you omit it, DialNexa uses the agent’s latest published version. If you provide it, that version must exist and be published. The batch stays on this version even if the agent is published again.

Choose The From Number

The batch dials from one of the agent’s outbound numbers. Pass phone_number_id (a phn_ ID from List Agent Phone Numbers) to choose it. When the agent has exactly one outbound number you can omit it. When it has several, omitting it returns 400 Bad Request with code PHONE_NUMBER_REQUIRED and the agent’s numbers in data.phone_number_ids. A phone_number_id that is not one of the agent’s outbound numbers returns 400 with code PHONE_NUMBER_NOT_LINKED. An agent with no outbound number returns 400; attach one first. Error bodies on this route have the shape { "message": "...", "data": { "code": "..." } }. If title is longer than 35 characters, the API returns 400 Bad Request with a clear validation message instead of creating the batch. Binding checks happen before the campaign is written. The API returns 404 Not Found for an agent outside the workspace or a requested version that does not exist. It returns 400 Bad Request when the agent has no published version, the requested version is still a draft, or the From number cannot be resolved as described above. A successful response reports the number the batch dials from in from_number.

Create Batch Calls With Retry Settings

Send number_of_retries and interval_between_retries as multipart fields when configuring retries. Retry count is an integer from 0 to 4; the interval is an integer from 0 to 1440 minutes. Set both to zero, or omit both, to disable retries, or use a positive count and interval. When both fields are supplied, mixing zero and a positive value returns 400. Send the two fields together: a positive count without an interval is accepted and its retries are scheduled with no wait. A retry is scheduled the interval after the attempt ends, then, when the From number’s country has a known time zone, moved into 10:00 to 21:00 local time (to 10:00 the same or next day). This window applies to retries only; it is not the batch’s calling_hours_start and calling_hours_end. Files must be CSV, XLSX, or XLS and no larger than 10 MB. The documented batch endpoints do not return a batch’s retry settings after creation, so record the values you sent. Before attempting another create request, check the batch’s status with List Batch Calls.

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. 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. While the workspace’s KYC is still pending, every row must be the owner’s registered phone number; any other number returns 403 Forbidden. The dashboard preview path can show invalid rows before launch so operators can edit or remove them. Direct API create requests still reject the whole file when row validation fails, so repair the file before retrying. A create request that fails, for example on row validation, the KYC check or an unsupported file type, leaves no batch behind.

Authorizations

Authorization

string

header

required

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

Body

multipart/form-data

file

required

CSV, XLSX or XLS file containing leads (max 10 MB). Needs a phone number column; every number must include its country code.

title

string

required

Example:

"Q3 Follow-up Batch"

agent_id

string

required

Example:

"agent_abc123"

agent_version_number

number

Must be a published version. Omit to use the agent's latest published version. The batch stays on this version even if the agent is published again.

Example:

1

phone_number_id

string

One of the agent's outbound numbers to dial from. Required when the agent has more than one outbound number.

Example:

"phn_abc123"

starts_at

string

ISO 8601 datetime: leave empty to start immediately

Example:

"2026-10-15T09:00:00Z"

ends_at

string

ISO 8601 datetime stored with the batch. The scheduler does not enforce it today: calls are not stopped at this time.

Example:

"2026-10-20T18:00:00Z"

calling_hours_start

string

Time of day (for example 09:00) stored with the batch. The scheduler does not enforce it today. The API does not validate it; a value that is not a valid time returns 500.

Example:

"09:00"

calling_hours_end

string

Time of day (for example 18:00) stored with the batch. The scheduler does not enforce it today. The API does not validate it; a value that is not a valid time returns 500.

Example:

"18:00"

number_of_retries

integer

How many times to retry a lead that did not connect, from 0 to 4. Omit both retry fields for no retries. Must be 0 when interval_between_retries is 0, and greater than 0 when it is not; send both fields together.

Required range: 0 <= x <= 4

Example:

2

interval_between_retries

integer

Minutes to wait between retries, from 0 to 1440. Must be 0 when number_of_retries is 0, and greater than 0 when it is not. Send it whenever number_of_retries is above 0: without it the retry is scheduled with no wait.

Required range: 0 <= x <= 1440

Example:

30

Response

Batch accepted. status is initiated; from_number identifies the selected outbound number. No scheduling-conflict warning is returned.

string

Example:

"batch_abc123"

total_records

number

Example:

250

dnc_skipped_count

number

Leads left out because their number is on the workspace's DNC list

Example:

0

status

string

Example:

"initiated"

from_number

string | null

title

string

Create Batch Call

curl --request POST \
  --url https://api.dialnexa.com/v1/batch-calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@example-file \
  --form 'title=Q3 Follow-up Batch' \
  --form agent_id=agent_abc123 \
  --form agent_version_number=1

import requests

url = "https://api.dialnexa.com/v1/batch-calls"

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Q3 Follow-up Batch",
    "agent_id": "agent_abc123",
    "agent_version_number": "1"
}
headers = {"Authorization": "Bearer <token>"}

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

print(response.text)

const form = new FormData();
form.append('file', 'leads.csv');
form.append('title', 'Q3 Follow-up Batch');
form.append('agent_id', 'agent_abc123');
form.append('agent_version_number', '1');

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

options.body = form;

fetch('https://api.dialnexa.com/v1/batch-calls', 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.dialnexa.com/v1/batch-calls",
  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=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\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.dialnexa.com/v1/batch-calls"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\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.dialnexa.com/v1/batch-calls")
  .header("Authorization", "Bearer <token>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/v1/batch-calls")

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=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\nleads.csv\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nQ3 Follow-up Batch\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_abc123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001--"

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

{
  "id": "batch_abc123",
  "total_records": 250,
  "dnc_skipped_count": 0,
  "status": "initiated",
  "from_number": "+14155552671",
  "title": "Q3 Follow-up Batch"
}

Overview

Endpoints

When to use this

File format

Reserved columns

Row rules

Batch vs. Campaign

Queue Behavior

File requirements

Choose The From Number

Create Batch Calls With Retry Settings

Destination validation

Authorizations

Body

Response

​When to use this

​File format

​Reserved columns

​Row rules

​Batch vs. Campaign

​Queue Behavior

​File requirements

​Choose The From Number

​Create Batch Calls With Retry Settings

​Destination validation

Authorizations

Body

Response

When to use this

File format

Reserved columns

Row rules

Batch vs. Campaign

Queue Behavior

File requirements

Choose The From Number

Create Batch Calls With Retry Settings

Destination validation