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,
  "status": "initiated",
  "from_number": "+14155552671",
  "title": "Q3 Follow-up Batch",
  "warning": {
    "message": "This batch was created, but your organization already has 1 running batch ahead of it. Batches run one at a time per organization, so this batch may be delayed.",
    "conflicts": [
      {
        "kind": "running",
        "batch_name": "July renewals",
        "processed_leads": 42,
        "total_leads": 250
      }
    ]
  }
}

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 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. When a create request succeeds but DialNexa detects another running, waiting, or nearby scheduled batch, the response can include a non-blocking warning. The batch was still created. Use the warning to tell operators that the new batch may be delayed behind existing work.

File requirements

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

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 selected version must also have an outbound phone number attached before the request can create any campaign data. 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 no outbound number is attached to the resolved version. A successful response reports the number bound to that exact agent version 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 to disable retries, or use a positive count and interval. When both fields are supplied, mixing zero and a positive value returns 400. Files must be CSV, XLSX, or XLS and no larger than 10 MB. After creation, inspect the batch’s saved retry configuration and status before attempting another create request.

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

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

Batch title shown in the dashboard. Must be 35 characters or fewer.

Maximum string length: 35

Example:

"Q3 Follow-up Batch"

agent_id

string

required

Example:

"agent_abc123"

agent_version_number

number

Published agent version to use. Omit to use the agent's latest published version.

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"

number_of_retries

integer

How many times to retry a lead that did not connect, from 0 to 4. Must be 0 when interval_between_retries is 0, and greater than 0 when it is not.

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.

Required range: 0 <= x <= 1440

Example:

30

Response

Batch call created and calls enqueued.

string

Example:

"batch_abc123"

total_records

number

Example:

250

status

string

Example:

"initiated"

from_number

string | null

title

string

warning

object

Non-blocking scheduling warning returned when another running, waiting, or nearby scheduled batch may delay this batch.

Show child attributes

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,
  "status": "initiated",
  "from_number": "+14155552671",
  "title": "Q3 Follow-up Batch",
  "warning": {
    "message": "This batch was created, but your organization already has 1 running batch ahead of it. Batches run one at a time per organization, so this batch may be delayed.",
    "conflicts": [
      {
        "kind": "running",
        "batch_name": "July renewals",
        "processed_leads": 42,
        "total_leads": 250
      }
    ]
  }
}

Overview

Endpoints

When to use this

File format

Batch vs. Campaign

Queue Behavior

File requirements

Create Batch Calls With Retry Settings

Destination validation

Authorizations

Body

Response

​When to use this

​File format

​Batch vs. Campaign

​Queue Behavior

​File requirements

​Create Batch Calls With Retry Settings

​Destination validation

Authorizations

Body

Response

When to use this

File format

Batch vs. Campaign

Queue Behavior

File requirements

Create Batch Calls With Retry Settings

Destination validation