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

<span data-api-safety-label="billable"><Badge color="yellow" size="sm" shape="pill">Billable - retry unsafe</Badge></span>
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.

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.


## OpenAPI

````yaml POST /v1/batch-calls
openapi: 3.0.0
info:
  title: DialNexa API
  description: Public `/v1` REST API for the DialNexa voice AI platform.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: Agents
  - name: Batch Calls
  - name: Calls
  - name: Knowledge Base
  - name: Languages
  - name: LLMs
  - name: Phone Numbers
  - name: Transcribers
  - name: Webhooks
  - name: Voices
  - name: Workflows
  - name: Workflow Leads
paths:
  /v1/batch-calls:
    post:
      tags:
        - Batch Calls
      summary: Create Batch Call
      description: >-
        Uploads a CSV or Excel leads file, creates a batch call, and enqueues
        outbound calls for all leads.
      operationId: createBatchCall
      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
                  maxLength: 35
                  description: >-
                    Batch title shown in the dashboard. Must be 35 characters or
                    fewer.
                agent_id:
                  type: string
                  example: agent_abc123
                agent_version_number:
                  example: 1
                  type: number
                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
                  warning:
                    type: object
                    description: >-
                      Non-blocking scheduling warning returned when another
                      running, waiting, or nearby scheduled batch may delay this
                      batch.
                    properties:
                      message:
                        type: string
                      conflicts:
                        type: array
                        items:
                          type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - running
                                - waiting
                                - scheduled
                            batch_name:
                              type: string
                            processed_leads:
                              type: number
                            total_leads:
                              type: number
                            starts_at:
                              type: string
                              format: date-time
              examples:
                success:
                  summary: Successful response
                  value:
                    id: batch_abc123
                    title: Q3 Follow-up Batch
                    total_records: 250
                    status: initiated
                    from_number: '+14155552671'
                    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
        '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
                titleTooLong:
                  summary: Title too long
                  value:
                    statusCode: 400
                    message: title must be 35 characters or fewer (received 42).
                    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
      type: http

````