> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Batch Call
> Upload contacts and start a batch of outbound calls.
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](/docs/api-reference/v1/migrating-to-v1) 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](/docs/api-reference/v1/workflow-leads/add) instead. For a single immediate call, use [Create Call](/docs/api-reference/v1/calls/create).
## 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](/docs/api-reference/v1/batches/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](/docs/batch-calls/retries-and-statuses#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](/docs/api-reference/v1/batches/list) 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.
## OpenAPI
````yaml POST /v1/batch-calls
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/batch-calls:
post:
tags:
- Batch Calls
- Batch Calls V1
- V1
summary: Create Batch Call
description: >-
Uploads a CSV or Excel leads file, creates a batch call, and enqueues
outbound calls for all leads.
operationId: BatchCallsV1Controller_create
parameters: []
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- title
- agent_id
- agent_version_number
properties:
file:
type: string
format: binary
description: CSV or Excel file containing leads (max 10 MB)
title:
type: string
example: Q3 Follow-up Batch
agent_id:
type: string
example: agent_abc123
agent_version_number:
type: number
example: 1
starts_at:
type: string
example: '2024-01-15T09:00:00Z'
description: ISO 8601 datetime - leave empty to start immediately
ends_at:
type: string
example: '2024-01-15T18:00:00Z'
calling_hours_start:
type: string
example: '09:00'
calling_hours_end:
type: string
example: '18:00'
examples:
request:
summary: Request example
value:
file: leads.csv
title: Q3 Follow-up Batch
agent_id: agent_abc123
agent_version_number: 1
responses:
'201':
description: Batch call created and calls enqueued.
content:
application/json:
schema:
type: object
properties:
id:
type: string
example: batch_abc123
title:
type: string
total_records:
type: number
example: 250
status:
type: string
example: initiated
from_number:
type: string
nullable: true
examples:
success:
summary: Successful response
value:
id: batch_abc123
title: Q3 Follow-up Batch
total_records: 250
status: initiated
from_number: '+14155552671'
'400':
description: Invalid file or missing required fields.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: The uploaded file must include a phone_number column
error: Bad Request
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: >-
Destination country or network prefix is not enabled for
this workspace
error: Forbidden
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````