> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vogent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Dial Jobs

> Automate large-scale outbound calling campaigns with scheduled batch dial jobs

Batch dial jobs enable you to execute large-scale outbound calling campaigns by creating and managing multiple dials in batches. This feature is perfect for sales campaigns, customer surveys, appointment reminders, and other scenarios where you need to make hundreds or thousands of calls efficiently.

## Overview

A batch dial job consists of:

* **Target phone numbers**: A list of phone numbers to call
* **Agent configuration**: The AI agent that will handle the conversations
* **Scheduling**: When the calls should be made
* **Concurrency limits**: How many calls to make simultaneously (this may not exceed your workspace's concurrent dial limit)
* **Phone number pool**: Which of your phone numbers to use for outbound calls

## Creating a Batch Dial Job

### 1. Prepare Your Data

First, prepare a list of phone numbers and any associated data (like names, account numbers, etc.) that your agent will need during the calls.

```json theme={null}
[
  {
    "toNumber": "+1234567890",
    "inputs": {
      "customer_name": "John Doe",
      "account_id": "ACC123"
    }
  },
  {
    "toNumber": "+1987654321",
    "inputs": {
      "customer_name": "Jane Smith",
      "account_id": "ACC456"
    }
  }
]
```

### 2. Create the Batch Job

Use the API to create your batch dial job:

```bash theme={null}
curl -X POST "https://api.vogent.ai/api/batch_dial_jobs" \
  -H "Content-Type: application/json" \
  -H "api_key: YOUR_API_KEY" \
  -d '{
    "name": "Customer Survey Campaign",
    "callAgentId": "your-agent-id",
    "maxConcurrentDials": 5,
    "fromPhoneNumberIds": ["your-phone-number-id"],
    "schedule": {
      "days": [
        {
          "dayOfWeek": 1,
          "timeSlots": [
            {
              "startTime": "09:00",
              "endTime": "17:00"
            }
          ]
        }
      ],
      "timezone": "America/New_York"
    },
    "rows": [
      {
        "toNumber": "+1234567890",
        "inputs": {
          "customer_name": "John Doe",
          "account_id": "ACC123"
        }
      }
    ]
  }'
```

You may view your job in the Vogent UI by going to the *Batch Dials* page.

### 3. Start the Job

Batch jobs are created in the `INIT` state. You must start them explicitly:

```bash theme={null}
curl -X POST "https://api.vogent.ai/api/batch_dial_jobs/{job-id}/paused" \
  -H "Content-Type: application/json" \
  -H "api_key: YOUR_API_KEY" \
  -d '{"paused": false}'
```

## Managing Batch Jobs

### Check Job Status

Monitor your batch job's progress:

```bash theme={null}
curl -X GET "https://api.vogent.ai/api/batch_dial_jobs/{job-id}" \
  -H "api_key: YOUR_API_KEY"
```

Response includes:

* Current status (`INIT`, `ACTIVE`, `PAUSED`, `COMPLETE`, `CANCELLED`)
* Creation timestamp
* Configuration details

### Update Job Configuration

You may update an existing job's settings, after it's been created. The changes won't apply until the workflow is paused.

```bash theme={null}
curl -X PUT "https://api.vogent.ai/api/batch_dial_jobs/{job-id}" \
  -H "Content-Type: application/json" \
  -H "api_key: YOUR_API_KEY" \
  -d '{
    "maxConcurrentDials": 10,
    "schedule": {
      "days": [
        {
          "dayOfWeek": 1,
          "timeSlots": [
            {
              "startTime": "09:00",
              "endTime": "18:00"
            }
          ]
        }
      ],
      "timezone": "America/New_York"
    }
  }'
```

### View Queued Dials

See all the rows that are queued to run on your batch job. This won't show dials that have already completed or are in progress.

```bash theme={null}
curl -X GET "https://api.vogent.ai/api/batch_dial_jobs/{job-id}/queue" \
  -H "api_key: YOUR_API_KEY"
```

## Scheduling

Batch dial jobs support sophisticated scheduling to ensure calls are made at appropriate times:

### Weekly Schedule Format

```json theme={null}
{
  "schedule": {
    "days": [
      {
        "dayOfWeek": 1,  // Monday (0=Sunday, 1=Monday, etc.)
        "timeSlots": [
          {
            "startTime": "09:00",
            "endTime": "12:00"
          },
          {
            "startTime": "13:00",
            "endTime": "17:00"
          }
        ]
      }
    ],
    "timezone": "America/New_York"
  }
}
```

### Time Zone Support

All schedules use the specified timezone. Common timezone values:

* `America/New_York` - Eastern Time
* `America/Chicago` - Central Time
* `America/Denver` - Mountain Time
* `America/Los_Angeles` - Pacific Time
* `UTC` - Coordinated Universal Time

## Best Practices

### Phone Number Pool

Use multiple phone numbers to increase call success rates and distribute call volume over multiple numbers.

### Data Management

Structure your `inputs` data consistently:

* Use the same field names across all rows
* Include all data your agent prompt references
* All your values must be strings

### Job Statuses

Your job will go through the following statuses:

* **INIT**: Job is just created and hasn't been started yet
* **ACTIVE**: Job is running normally
* **PAUSED**: Job is temporarily stopped
* **COMPLETE**: All dials have been attempted
* **CANCELLED**: Job was manually stopped