Create Batch Job

Overview

Creates a batch calling job that will automatically dial contacts from your uploaded list. The job can start immediately or be scheduled for a future time. Key Features:

CSV file upload (up to 10,000 contacts)
Automatic phone number validation (E.164 format)
Scheduled start with timezone support
Configurable retry policy
Two-level concurrency control

Prerequisites

Before creating a batch job:

Register a phone number in Studio → Phone Numbers
Assign an outbound agent to that phone number
Ensure sufficient credits in your organization account
Prepare CSV file with at least a phone column

The agent assigned to the phone number must use Pipeline or Realtime architecture. Text-only agents cannot make voice calls.

Request

CSV Upload (Recommended)

POST /batch/create
Content-Type: multipart/form-data

file: [CSV file]
fromPhoneNumberId: phone_abc123
name: January Renewal Campaign
description: Follow up on expiring subscriptions
concurrentCallLimit: 5
maxAttempts: 3
scheduledStartTime: 2025-02-28T09:00:00 (optional)
timezone: America/New_York (optional, default: UTC)

JSON Request (Programmatic)

POST /batch/create
Content-Type: application/json

{
  "fromPhoneNumberId": "phone_abc123",
  "name": "January Renewal Campaign",
  "description": "Follow up on expiring subscriptions",
  "contacts": [
    {
      "phone": "+12025550101",
      "name": "John Smith",
      "customerName": "John Smith",
      "renewalDate": "Feb 1"
    },
    {
      "phone": "+12025550102",
      "name": "Jane Doe",
      "customerName": "Jane Doe",
      "renewalDate": "Feb 5"
    }
  ],
  "concurrentCallLimit": 5,
  "maxAttempts": 3,
  "scheduledStartTime": "2025-02-28T09:00:00",
  "timezone": "America/New_York"
}

Request Parameters

Form/Body Fields

Field	Type	Required	Default	Description
`file`	File	✅ (CSV mode)	—	CSV file with contacts
`fromPhoneNumberId`	string	✅	—	Phone number ID to call from
`name`	string	✅	—	Batch job name (max 200 chars)
`description`	string	❌	`null`	Optional description (max 1000 chars)
`contacts`	array	✅ (JSON mode)	—	List of contact objects
`concurrentCallLimit`	integer	❌	`5`	Max concurrent calls (1-50)
`maxAttempts`	integer	❌	`3`	Max retry attempts (1-10)
`scheduledStartTime`	string	❌	`null`	Schedule start (ISO 8601 format)
`timezone`	string	❌	`"UTC"`	IANA timezone for scheduled time

Contact Object

Field	Type	Required	Description
`phone`	string	✅	Phone number in E.164 format
`name`	string	❌	Contact name
`*`	any	❌	Additional custom fields (stored as-is)

CSV Format

Your CSV file must have a phone column. Additional columns are stored as custom fields.

phone,name,customerName,renewalDate
+12025550101,John Smith,John Smith,Feb 1
+12025550102,Jane Doe,Jane Doe,Feb 5
+12025550103,Bob Johnson,Bob Johnson,Feb 10

Column	Required	Description
`phone`	✅	Phone number in E.164 format (+12025550101)
`name`	❌	Contact name
any other	❌	Additional columns stored as custom fields

Phone Number Format: All phone numbers must be in E.164 format (e.g., +12025550101, +442071838750). Numbers without + or with formatting characters will be rejected.

Response

{
  "success": true,
  "batchJobId": "batch_xyz789",
  "totalContacts": 2,
  "estimatedDuration": "2 minutes",
  "estimatedCost": "$0.50",
  "status": "scheduled",
  "scheduledStartTime": "2025-02-28T14:00:00Z",
  "message": "Batch job created with 2 contacts"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the job was created successfully
`batchJobId`	string	Unique batch job identifier
`totalContacts`	integer	Number of valid contacts
`estimatedDuration`	string	Human-readable duration estimate
`estimatedCost`	string	Estimated cost in USD
`status`	string	Initial status (`scheduled` or `pending`)
`scheduledStartTime`	string	Scheduled start time (ISO 8601, UTC)
`message`	string	Success message

Status Values

Status	Description
`pending`	Job created, will start immediately
`scheduled`	Job created, waiting for scheduled start time
`running`	Job is actively processing contacts
`completed`	All contacts processed
`failed`	Job failed due to errors
`cancelled`	Job was cancelled manually

Examples

Example 1: Immediate Start (CSV)

curl -X POST "https://api.talkifai.com/batch/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  -F "fromPhoneNumberId=phone_abc123" \
  -F "name=Payment Reminders" \
  -F "concurrentCallLimit=5" \
  -F "maxAttempts=3"

Example 2: Scheduled Start with Timezone

curl -X POST "https://api.talkifai.com/batch/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPhoneNumberId": "phone_abc123",
    "name": "Morning Follow-ups",
    "contacts": [
      {"phone": "+12025550101", "name": "John Smith"},
      {"phone": "+12025550102", "name": "Jane Doe"}
    ],
    "scheduledStartTime": "2025-03-01T09:00:00",
    "timezone": "America/New_York",
    "concurrentCallLimit": 3,
    "maxAttempts": 2
  }'

Example 3: Custom Fields for Personalization

curl -X POST "https://api.talkifai.com/batch/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromPhoneNumberId": "phone_abc123",
    "name": "Renewal Campaign",
    "contacts": [
      {
        "phone": "+12025550101",
        "name": "John Smith",
        "customerName": "John Smith",
        "renewalDate": "Feb 1",
        "planType": "Premium"
      }
    ],
    "concurrentCallLimit": 5
  }'

Then in your Agent System Prompt, use the custom fields:

You are calling {{customerName}} about their {{planType}} plan renewal on {{renewalDate}}.
Greet them by name and confirm the renewal date.

Cost Estimation

The system estimates cost based on:

Number of contacts
Agent architecture (pipeline vs realtime)
Average call duration (assumed 2 minutes)

Example calculation for 100 contacts:

Pipeline agent: ~ $3.50 ($ 0.035/call)
Realtime agent: ~ $7.00 ($ 0.07/call)

Actual costs may vary based on call duration. The estimate assumes 2-minute average calls.

Error Handling

400 Bad Request

{
  "detail": "CSV must have 'phone' column. Found columns: ['name', 'email']"
}

Error Code	Cause
`invalid_csv`	CSV file missing or invalid format
`missing_phone_column`	CSV missing required `phone` column
`no_valid_contacts`	CSV contains no valid phone numbers
`too_many_contacts`	Exceeds 10,000 contact limit
`invalid_timezone`	Invalid IANA timezone
`past_scheduled_time`	Scheduled time is in the past
`invalid_phone_format`	Phone number not in E.164 format
`insufficient_credits`	Organization has insufficient credits
`no_outbound_agent`	Phone number has no outbound agent assigned

404 Not Found

{
  "detail": "Phone number phone_abc123 not found"
}

500 Internal Server Error

{
  "detail": "Failed to process CSV file: Database connection error"
}

How It Works

1. Upload CSV / Send JSON
         │
         ▼
2. Validate phone numbers (E.164 format)
         │
         ▼
3. Look up fromPhoneNumberId
         ├── Not found → 404 Error
         └── Found → Get org + agent
                   │
                   ▼
4. Check agent architecture
         ├── Text agent → 400 Error
         └── Voice agent → Continue
                   │
                   ▼
5. Validate contacts (remove duplicates)
         │
         ▼
6. Check organization credits
         ├── Insufficient → 400 Error
         └── Sufficient → Continue
                   │
                   ▼
7. Create batch job record
         │
         ├── Scheduled? → Store in Redis defer queue
         └── Immediate? → Enqueue contacts to worker queue
                   │
                   ▼
8. Return batch job ID

Batch Jobs List — List all batch jobs
Batch Job Detail — Get detailed job status
Cancel Batch Job — Cancel a running job
Batch Calling Guide — Complete guide to batch campaigns
Telephony — Configure phone numbers

Authorizations

Authorization

string

header

required

Your TalkifAI API key. Get it from Studio â†’ Settings â†’ API Keys.

Body

file

required

CSV file with contacts (must have 'phone' column)

fromPhoneNumberId

string

required

Phone number ID to call from

name

string

required

Batch job name

description

string

Optional description

concurrentCallLimit

integer

default:5

Required range: 1 <= x <= 50

maxAttempts

integer

default:3

Required range: 1 <= x <= 10

scheduledStartTime

string<date-time>

Schedule start time (ISO 8601)

timezone

string

default:UTC

IANA timezone for scheduled time

Response

Batch job created

success

boolean

Example:

true

batchJobId

string

Example:

"batch_xyz789"

totalContacts

integer

Example:

100

estimatedDuration

string

Example:

"15 minutes"

estimatedCost

string

Example:

"$3.50"

status

string

Example:

"scheduled"

scheduledStartTime

string<date-time> | null

message

string

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

Overview

Prerequisites

Request

CSV Upload (Recommended)

JSON Request (Programmatic)

Request Parameters

Form/Body Fields

Contact Object

CSV Format

Response

Response Fields

Status Values

Examples

Example 1: Immediate Start (CSV)

Example 2: Scheduled Start with Timezone

Example 3: Custom Fields for Personalization

Cost Estimation

Error Handling

400 Bad Request

404 Not Found

500 Internal Server Error

How It Works

Authorizations

Body

Response

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

​Overview

​Prerequisites

​Request

​CSV Upload (Recommended)

​JSON Request (Programmatic)

​Request Parameters

​Form/Body Fields

​Contact Object

​CSV Format

​Response

​Response Fields

​Status Values

​Examples

​Example 1: Immediate Start (CSV)

​Example 2: Scheduled Start with Timezone

​Example 3: Custom Fields for Personalization

​Cost Estimation

​Error Handling

​400 Bad Request

​404 Not Found

​500 Internal Server Error

​How It Works

​Related

Authorizations

Body

Response

Overview

Prerequisites

Request

CSV Upload (Recommended)

JSON Request (Programmatic)

Request Parameters

Form/Body Fields

Contact Object

CSV Format

Response

Response Fields

Status Values

Examples

Example 1: Immediate Start (CSV)

Example 2: Scheduled Start with Timezone

Example 3: Custom Fields for Personalization

Cost Estimation

Error Handling

400 Bad Request

404 Not Found

500 Internal Server Error

How It Works

Related