Create Batch Call

POST

batch-calls

Create campaign, upload leads file, and enqueue calls

curl --request POST \
  --url https://api.dialnexa.com/batch-calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-organization-id: <x-organization-id>' \
  --form file='@example-file' \
  --form 'title=Enter campaign title here' \
  --form agent_id=agent_123 \
  --form agent_version_number=1 \
  --form starts_at= \
  --form ends_at= \
  --form calling_hours_start= \
  --form calling_hours_end=

import requests

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

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Enter campaign title here",
    "agent_id": "agent_123",
    "agent_version_number": "1",
    "starts_at": "",
    "ends_at": "",
    "calling_hours_start": "",
    "calling_hours_end": ""
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('title', 'Enter campaign title here');
form.append('agent_id', 'agent_123');
form.append('agent_version_number', '1');
form.append('starts_at', '');
form.append('ends_at', '');
form.append('calling_hours_start', '');
form.append('calling_hours_end', '');

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

options.body = form;

fetch('https://api.dialnexa.com/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/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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	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/batch-calls")
  .header("x-organization-id", "<x-organization-id>")
  .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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--"

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

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. Use the /v1 version for new integrations. This endpoint remains available for existing integrations until then.

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_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 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.

Authorizations

Authorization

string

header

required

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

Headers

x-organization-id

string

required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

Body

multipart/form-data

file

required

CSV or Excel leads file

title

string

required

Example:

"Enter campaign title here"

agent_id

string

required

Example:

"agent_123"

agent_version_number

number

required

Example:

1

starts_at

string

Example:

""

ends_at

string

Example:

""

calling_hours_start

string

Example:

""

calling_hours_end

string

Example:

""

Response

201

Batch call created and queued

List Batch CallsRetrieve every batch call job in your workspace, with status and progress counters, ordered newest first.

Create campaign, upload leads file, and enqueue calls

curl --request POST \
  --url https://api.dialnexa.com/batch-calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-organization-id: <x-organization-id>' \
  --form file='@example-file' \
  --form 'title=Enter campaign title here' \
  --form agent_id=agent_123 \
  --form agent_version_number=1 \
  --form starts_at= \
  --form ends_at= \
  --form calling_hours_start= \
  --form calling_hours_end=

import requests

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

files = { "file": ("example-file", open("example-file", "rb")) }
payload = {
    "title": "Enter campaign title here",
    "agent_id": "agent_123",
    "agent_version_number": "1",
    "starts_at": "",
    "ends_at": "",
    "calling_hours_start": "",
    "calling_hours_end": ""
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>"
}

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

print(response.text)

const form = new FormData();
form.append('file', '<string>');
form.append('title', 'Enter campaign title here');
form.append('agent_id', 'agent_123');
form.append('agent_version_number', '1');
form.append('starts_at', '');
form.append('ends_at', '');
form.append('calling_hours_start', '');
form.append('calling_hours_end', '');

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

options.body = form;

fetch('https://api.dialnexa.com/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/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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "x-organization-id: <x-organization-id>"
  ],
]);

$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/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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--")

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

	req.Header.Add("x-organization-id", "<x-organization-id>")
	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/batch-calls")
  .header("x-organization-id", "<x-organization-id>")
  .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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
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\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"title\"\r\n\r\nEnter campaign title here\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_id\"\r\n\r\nagent_123\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"agent_version_number\"\r\n\r\n1\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"starts_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"ends_at\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_start\"\r\n\r\n\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"calling_hours_end\"\r\n\r\n\r\n-----011000010111000001101001--"

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

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

File format

Batch vs. Campaign

File requirements

Destination validation

Authorizations

Headers

Body

Response

​File format

​Batch vs. Campaign

​File requirements

​Destination validation

Authorizations

Headers

Body

Response

File format

Batch vs. Campaign

File requirements

Destination validation