Create Batch Call

Upload contacts and start a batch of outbound calls.

POST /v1/batch-calls

Create Batch Call

cURL

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

201

success

{
  "id": "batch_abc123",
  "title": "Q3 Follow-up Batch",
  "total_records": 250,
  "status": "initiated",
  "from_number": "[phone]",
  "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.

If title is longer than 35 characters, the API returns 400 Bad Request with a clear validation message instead of creating the batch.

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

201

application/json

Batch call created and calls enqueued.

id · string

Example:

"batch_abc123"

title · string

total_records · number

Example:

250

status · string

Example:

"initiated"

from_number · string | null

warning · object

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

Show child attributes