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",
  "title": "Q3 Follow-up Batch",
  "total_records": 250,
  "status": "initiated",
  "from_number": "+14155552671"
}

{
  "statusCode": 400,
  "message": "The uploaded file must include a phone_number column",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "Destination country or network prefix is not enabled for this workspace",
  "error": "Forbidden"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Billable - retry unsafe

Recommended. This endpoint is part of the public /v1 API reference and is the supported path for new integrations. See the migration guide for versioning guidance.

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 can start processing immediately, enter waiting until the organization queue is clear, or move to scheduled when you provide a future start time.

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 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. All other column headers become dynamic variables that are injected into the agent’s prompt for each individual call:

phone_number	customer_name	loan_amount	product
9876543210	Priya Sharma	500000	home_loan
9123456789	Rahul Mehra	250000	car_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 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

DialNexa runs one batch campaign per organization at a time. If another batch is already running or waiting, a newly accepted batch can wait behind it instead of placing calls immediately. Future-start batches can remain scheduled until their start window, then move into waiting or running based on queue availability. 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.

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.

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 or Excel file containing leads (max 10 MB)

title

string

required

Example:

"Q3 Follow-up Batch"

agent_id

string

required

Example:

"agent_abc123"

agent_version_number

number

required

Example:

1

starts_at

string

ISO 8601 datetime - leave empty to start immediately

Example:

"2024-01-15T09:00:00Z"

ends_at

string

Example:

"2024-01-15T18:00:00Z"

calling_hours_start

string

Example:

"09:00"

calling_hours_end

string

Example:

"18:00"

Response

Batch call created and calls enqueued.

string

Example:

"batch_abc123"

title

string

total_records

number

Example:

250

status

string

Example:

"initiated"

from_number

string | null

List Batch CallsList batch call jobs for your workspace and filter by draft, waiting, scheduled, running, paused, completed, cancelled, deleted, or legacy active status.

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",
  "title": "Q3 Follow-up Batch",
  "total_records": 250,
  "status": "initiated",
  "from_number": "+14155552671"
}

{
  "statusCode": 400,
  "message": "The uploaded file must include a phone_number column",
  "error": "Bad Request"
}

{
  "statusCode": 401,
  "message": "API key is missing or invalid",
  "error": "Unauthorized"
}

{
  "statusCode": 403,
  "message": "Destination country or network prefix is not enabled for this workspace",
  "error": "Forbidden"
}

{
  "statusCode": 500,
  "message": "Internal server error",
  "error": "Internal Server Error"
}

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

When to use this

File format

Batch vs. Campaign

Queue Behavior

File requirements

Destination validation

Authorizations

Body

Response

​When to use this

​File format

​Batch vs. Campaign

​Queue Behavior

​File requirements

​Destination validation

Authorizations

Body

Response

When to use this

File format

Batch vs. Campaign

Queue Behavior

File requirements

Destination validation