openapi: 3.2.0
info:
  title: DialNexa Batch Calls 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: Batch Calls
paths:
  /v1/batch-calls:
    post:
      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
              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:
                  type: number
                  example: 1
                  description: Published agent version to use. Omit to use the agent's latest published version.
                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
                    - 'null'
                  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, the resolved agent version is unpublished, or no outbound phone number is attached to that version.
          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
                unpublishedVersion:
                  summary: Agent version is still a draft
                  value:
                    statusCode: 400
                    message: Version 2 of agent agent_abc123 is a draft. Publish it before starting a batch call.
                    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
        '404':
          description: Agent not found in the workspace, or the requested agent version does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                versionNotFound:
                  summary: Agent version not found
                  value:
                    statusCode: 404
                    message: 'Agent agent_abc123 has no version 9. Published versions: 1, 3.'
                    error: Not Found
        '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: []
      summary: Create Batch Call
      tags:
      - Batch Calls
    get:
      operationId: listBatchCalls
      parameters:
      - name: limit
        required: false
        in: query
        schema:
          example: 20
          type: number
      - name: page
        required: false
        in: query
        schema:
          example: 1
          type: number
      - name: status
        required: false
        in: query
        description: Filter by batch status - can be a single status or comma-separated list. Supported values include draft, waiting, scheduled, running, paused, completed, cancelled, deleted, and legacy active.
        schema:
          type: string
      responses:
        '200':
          description: Batch calls returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: batch_abc123
                        title:
                          type: string
                        status:
                          type: string
                        total_records:
                          type: number
                        createdAt:
                          type: string
                          format: date-time
                        total_lead_count:
                          type: number
                          description: Total recipients loaded into the batch.
                        sent_lead_count:
                          type: number
                          description: Initial recipient calls that have been sent.
                        picked_up_lead_count:
                          type: number
                          description: Legacy connected-recipient counter retained for compatibility. Prefer picked_up_calls for the current Picked Up rollup.
                        picked_up_calls:
                          type: number
                          description: Completed call attempts across initial calls and retry children. In-progress and unanswered outcomes are excluded.
                        last_call_sent_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                          description: Latest dispatch time across initial calls and retry children.
                        number_of_retries:
                          type:
                          - number
                          - 'null'
                          description: Configured retry count.
                        first_retry_count:
                          type:
                          - number
                          - 'null'
                          description: Retry call logs scheduled for the first retry depth.
                        second_retry_count:
                          type:
                          - number
                          - 'null'
                          description: Retry call logs scheduled for the second retry depth.
                        third_retry_count:
                          type:
                          - number
                          - 'null'
                          description: Retry call logs scheduled for the third retry depth.
                        fourth_retry_count:
                          type:
                          - number
                          - 'null'
                          description: Retry call logs scheduled for the fourth retry depth.
                        attempt_stages:
                          type: array
                          description: Per-stage attempt progress. Depth 0 is the initial call, and depths 1 through 4 are retry stages. Present when retry enrichment is available.
                          items:
                            type: object
                            properties:
                              depth:
                                type: number
                                example: 0
                              attempted:
                                type: number
                                example: 240
                              total:
                                type: number
                                example: 250
                  total:
                    type: number
                  page:
                    type: number
                  limit:
                    type: number
              examples:
                success:
                  summary: Successful response
                  value:
                    items:
                    - id: batch_abc123
                      title: Q3 Follow-up Batch
                      status: waiting
                      total_records: 250
                      createdAt: '2026-07-03T10:30:00.000Z'
                      total_lead_count: 250
                      sent_lead_count: 240
                      picked_up_lead_count: 120
                      picked_up_calls: 116
                      last_call_sent_at: '2026-07-03T11:42:18.000Z'
                      number_of_retries: 2
                      first_retry_count: 80
                      second_retry_count: 25
                      third_retry_count: 0
                      fourth_retry_count: 0
                      attempt_stages:
                      - depth: 0
                        attempted: 240
                        total: 250
                      - depth: 1
                        attempted: 60
                        total: 80
                      - depth: 2
                        attempted: 10
                        total: 25
                    total: 1
                    page: 1
                    limit: 20
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid query parameters
                    error: Bad Request
        '401':
          description: Unauthorized.
          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: []
      summary: List Batch Calls
      tags:
      - Batch Calls
      description: Returns batch call jobs for the authenticated workspace, including status and progress fields.
  /v1/batch-calls/{id}:
    get:
      operationId: getBatchCall
      parameters:
      - name: id
        required: true
        in: path
        description: Batch call ID
        schema:
          example: batch_abc123
          type: string
      - name: agent_id
        required: false
        in: query
        description: Filter by agent ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)
        schema:
          type: string
      - name: call_id
        required: false
        in: query
        description: Filter by call ID - can be a single ID or comma-separated list (e.g., call_abc,call_def)
        schema:
          type: string
      - name: batch_call_id
        required: false
        in: query
        description: Filter by batch call ID - can be a single ID or comma-separated list (e.g., batch_abc,batch_def)
        schema:
          type: string
      - name: from
        required: false
        in: query
        description: Filter by sender phone number
        schema:
          type: string
      - name: to
        required: false
        in: query
        description: Filter by recipient phone number
        schema:
          type: string
      - name: type
        required: false
        in: query
        description: Filter by call type(s) - can be a single value or comma-separated list
        schema:
          type: string
          enum:
          - phone
          - web
      - name: call_direction
        required: false
        in: query
        description: Filter by call direction(s) - can be a single value or comma-separated list
        schema:
          type: string
          enum:
          - inbound
          - outbound
      - name: latency_min
        required: false
        in: query
        description: Filter by minimum latency (in milliseconds)
        schema:
          type: number
      - name: latency_max
        required: false
        in: query
        description: Filter by maximum latency (in milliseconds)
        schema:
          type: number
      - name: agent_version_id
        required: false
        in: query
        description: Filter by agent version ID(s) - can be a single ID or comma-separated list (e.g., 1,2,3)
        schema:
          type: string
      - name: agent_version_name
        required: false
        in: query
        description: Search by agent version name (partial match, case-insensitive)
        schema:
          type: string
      - name: sentiment
        required: false
        in: query
        description: Filter by sentiment(s) - can be a single value or comma-separated list
        schema:
          type: string
          enum:
          - positive
          - neutral
          - negative
          - unknown
      - name: start_date
        required: false
        in: query
        description: Filter by start date (ISO format)
        schema:
          type: string
      - name: end_date
        required: false
        in: query
        description: Filter by end date (ISO format)
        schema:
          type: string
      - name: duration_greater_than
        required: false
        in: query
        description: Filter by minimum call duration (in milliseconds)
        schema:
          type: number
      - name: duration_less_than
        required: false
        in: query
        description: Filter by maximum call duration (in milliseconds)
        schema:
          type: number
      - name: duration_min
        required: false
        in: query
        description: Filter by minimum duration range (in milliseconds)
        schema:
          type: number
      - name: duration_max
        required: false
        in: query
        description: Filter by maximum duration range (in milliseconds)
        schema:
          type: number
      - name: page
        required: false
        in: query
        description: Page number (starts from 1)
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: 'Number of records per page (min: 1, default: 20, max: 200)'
        schema:
          example: 20
          type: number
      - name: created_at
        required: false
        in: query
        description: Sort by created_at (asc or desc)
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: duration
        required: false
        in: query
        description: Sort by duration (asc or desc)
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: status
        required: false
        in: query
        description: Filter by call status(es) - can be a single status or comma-separated list
        schema:
          type: string
      - name: export
        required: false
        in: query
        description: Set to true to export all data without pagination
        schema:
          type: boolean
      - name: end_reason
        required: false
        in: query
        description: Filter by end/hangup reason - exact match; comma-separate multiple values for OR filtering
        schema:
          type: string
      - name: columns
        required: false
        in: query
        description: 'Export only: comma-separated column keys. Omitting both transcript and summary raises the single-export limit from 5000 to 10000 rows. Omit this parameter to include all columns.'
        schema:
          type: string
          example: duration,status,agent_name
      responses:
        '200':
          description: Calls in the batch returned successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    callLogs:
                    - id: call_abc123
                      agent_id: agent_2g7Xy3tY53gRlp
                      to_number: '+919876543210'
                      from_number: '+14155552671'
                      status: initiated
                      call_direction: outbound
                      createdAt: '2026-07-03T10:30:00.000Z'
                      batch_id: batch_abc123
                    total: 1
                    page: 1
                    limit: 20
                    totalPages: 1
              schema:
                type: object
                properties:
                  callLogs:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          example: call_abc123
                        status:
                          type: string
                          example: completed
                        from_number:
                          type: string
                          example: '+14155552671'
                        to_number:
                          type: string
                          example: '+919876543210'
                        duration:
                          type: number
                          example: 42
                        createdAt:
                          type: string
                          format: date-time
                  total:
                    type: number
                  page:
                    type: number
                  limit:
                    type: number
                  totalPages:
                    type: number
        '401':
          description: Unauthorized.
          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
        '404':
          description: Batch call not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: Batch call not found
                    error: Not Found
        '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
        '400':
          description: Invalid batch call ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid batch call ID format
                    error: Bad Request
      security:
      - bearer: []
      summary: Get Batch Call Details
      tags:
      - Batch Calls
      description: Returns one batch call job and its current processing details.
  /v1/batch-calls/{id}/status:
    patch:
      operationId: updateBatchCallStatus
      summary: Update Batch Call Status
      description: Changes the execution status of a batch call. Use `pause` to halt new outbound calls, `resume` to continue a paused batch, or `cancel` to permanently stop the batch and remove queued calls.
      parameters:
      - name: id
        required: true
        in: path
        description: Batch call ID
        schema:
          example: batch_abc123
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - action
              properties:
                action:
                  type: string
                  enum:
                  - pause
                  - resume
                  - cancel
                  example: pause
                  description: The status transition to apply.
            examples:
              pause:
                summary: Pause a batch call
                value:
                  action: pause
              resume:
                summary: Resume a batch call
                value:
                  action: resume
              cancel:
                summary: Cancel a batch call
                value:
                  action: cancel
      responses:
        '200':
          description: Batch call status updated successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    message: Campaign paused successfully
                    campaign:
                      id: batch_abc123
                      status: paused
                      title: Q3 Follow-up Batch
                    affectedCalls:
                      initiated: 0
                      queued: 0
                      removedFromQueue: 12
                      cancelledCallLogs: 0
                      resumedCallLogs: 0
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Campaign paused successfully
                  campaign:
                    type: object
                    properties:
                      id:
                        type: string
                        example: batch_abc123
                      status:
                        type: string
                        enum:
                        - initiated
                        - draft
                        - waiting
                        - scheduled
                        - running
                        - paused
                        - completed
                        - cancelled
                        - deleted
                        example: paused
                      title:
                        type: string
                        example: Q3 Follow-up Batch
                  affectedCalls:
                    type: object
                    properties:
                      initiated:
                        type: number
                        example: 0
                      queued:
                        type: number
                        example: 0
                      removedFromQueue:
                        type: number
                        example: 12
                      cancelledCallLogs:
                        type: number
                        example: 0
                      resumedCallLogs:
                        type: number
                        example: 0
        '400':
          description: Invalid action, or action not allowed for the current batch call status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: 'Invalid action. Must be one of: pause, resume, cancel'
                    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 - batch call does not belong to your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
        '404':
          description: Batch call not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: Batch call not found
                    error: Not Found
        '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: []
      tags:
      - Batch Calls
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