Batch Calls

Manage high-volume outbound calling campaigns. The full lifecycle is:

Create a batch call (status: draft)
Add contacts via folder, contact_ids, inline contacts, or upload after creation
Schedule the batch (status: scheduled) — contacts are distributed across days using your timezone, working days, and daily call limits
Pause / Resume as needed
Monitor via analytics and the contacts list endpoint
Delete when done (draft/failed/cancelled only)

Scheduling is database-driven: contacts receive individual scheduled_at timestamps spread across your calling window. A background job fires them at the right time. This matches the dashboard/internal scheduling model exactly.

List Batch Calls

Query parameters:

Parameter	Type	Default	Description
`agent_id`	UUID	—	Filter by agent
`status`	string	—	Filter by status: `draft`, `scheduled`, `active`, `paused`, `completed`, `failed`, `cancelled`
`limit`	int	50	1-100
`offset`	int	0	Pagination offset

Response: data (array), pagination (total, limit, offset, has_more), meta.

Create Batch Call

Creates a new batch call in draft status. Contacts can be attached at creation time via three methods (or combined):

Field	Type	Required	Description
`name`	string	Yes	1-255 characters
`agent_id`	UUID	Yes	Agent that makes the calls (must be synced)
`phone_number_ids`	UUID[]	No	Outbound number IDs. Auto-fills from agent if empty
`phone_rotation_strategy`	string	No	`random` (default), `sequential`, or `round_robin`
`contact_source`	string	No	`csv` (default), `folder`, or `manual`
`contact_folder_id`	UUID	When source=folder	Contacts from this folder are copied into the batch
`contact_ids`	UUID[]	No	Existing contact IDs from your contacts table
`contacts`	object[]	No	Inline contacts: `{ phone_number, first_name?, last_name?, email?, custom_fields? }`
`schedule_type`	string	No	`immediate` (default) or `scheduled`
`scheduled_at`	ISO datetime	When scheduled	Required when `schedule_type` is `scheduled`
`timezone`	string	No	IANA timezone. Default `UTC`
`start_time`	HH:MM	No	Daily window start (e.g. `09:00`)
`end_time`	HH:MM	No	Daily window end (e.g. `18:00`)
`working_days`	int[]	No	1=Mon … 7=Sun. Default `[1,2,3,4,5]`
`max_concurrent_calls`	int	No	1-100. Default 10
`max_calls_per_day`	int	No	Capped by your billing tier. Default 500
`retry_failed`	bool	No	Default true
`max_retry_attempts`	int	No	0-3. Default 2

Headers: Send X-Idempotency-Key for safe retries. Example — inline contacts:

{
  "name": "Q1 Outreach",
  "agent_id": "AGENT_UUID",
  "phone_number_ids": ["PHONE_UUID"],
  "contacts": [
    { "phone_number": "+15551234567", "first_name": "Alice" },
    { "phone_number": "+15559876543", "first_name": "Bob", "last_name": "Smith" }
  ],
  "max_calls_per_day": 100,
  "start_time": "09:00",
  "end_time": "17:00"
}

Example — folder source:

{
  "name": "Folder Campaign",
  "agent_id": "AGENT_UUID",
  "contact_source": "folder",
  "contact_folder_id": "FOLDER_UUID",
  "schedule_type": "scheduled",
  "scheduled_at": "2025-02-01T09:00:00Z",
  "timezone": "America/New_York"
}

Example — existing contact IDs:

{
  "name": "Re-engage",
  "agent_id": "AGENT_UUID",
  "contact_ids": ["CONTACT_UUID_1", "CONTACT_UUID_2"]
}

Response: 200 with data (batch call object including id, status, total_contacts) and meta.

Get Batch Call

Query	Type	Default	Description
`refresh`	bool	false	Sync `completed_contacts` from the telephony provider

Response: data (full batch call object), meta.

Update Batch Call

Allowed when status is draft, scheduled, or paused. Body (all optional): name, phone_number_ids, phone_rotation_strategy, scheduled_at, start_time, end_time, working_days, max_concurrent_calls, max_calls_per_day (capped by billing tier), retry_failed, max_retry_attempts. If scheduling parameters (scheduled_at, start_time, end_time, max_calls_per_day, working_days) are changed on a scheduled or paused batch, contacts are automatically redistributed across the new schedule.

Delete Batch Call

Deletes the batch and all its campaign contacts. Only allowed when status is draft, failed, or cancelled. Response: 200 with data: { "id", "deleted": true }.

List Batch Call Contacts

Lists all contacts attached to a batch call with their scheduling and execution status.

Query	Type	Default	Description
`status`	string	—	Filter: `pending`, `scheduled`, `completed`, `failed`
`limit`	int	50	1-200
`offset`	int	0	Pagination offset

Response: data (array of campaign contact objects with phone_number, first_name, status, scheduled_at, etc.), pagination, meta.

Upload Contacts to Batch Call

Add contacts to a draft batch call. Two input methods:

Field	Type	Description
`contacts`	object[]	Array of `{ phone_number, first_name?, last_name?, email?, custom_fields? }`
`csv_base64`	string	Base64-encoded CSV (columns: `phone_number`, `first_name`, `last_name`, `email`)
`add_to_folder`	bool	Also save contacts to a contact folder (default `true`)
`folder_id`	UUID	Target folder. Auto-creates one if omitted

Response: data: { "batch_call_id", "contacts_added", "folder_id" }, meta.

Schedule Batch Call

Transitions a draft batch to scheduled. The scheduling engine:

Validates the batch has an agent, phone numbers, and at least one pending contact
Prepares call payloads with phone number rotation
Distributes contacts across days using timezone, working_days, start_time/end_time, and max_calls_per_day
Assigns each contact an individual scheduled_at timestamp
A background job fires calls at their scheduled times

Returns 422 if prerequisites are not met (no contacts, agent not synced, etc.). Response: data: { "batch_call_id", "status": "scheduled", "contacts_scheduled", "message" }, meta.

Pause Batch Call

Pauses an active or scheduled batch. Pending calls are held until resumed. Returns 422 if the batch is not in active or scheduled status.

Resume Batch Call

Resumes a paused batch. If the original scheduled_at is in the future, status returns to scheduled; otherwise, it becomes active. Returns 422 if the batch is not in paused status.

Get Batch Call Analytics

Returns detailed stats: total_contacts, completed_contacts, successful_contacts, failed_contacts, voicemail_contacts, no_answer_contacts, total_cost_usd, average_duration_seconds, and more.

Bulk Delete Batch Calls

Body: { "ids": ["uuid1", "uuid2", ...] } Deletes only batches in draft, failed, or cancelled status. Others are skipped. Response: data: { "deleted_count", "failed_count" }, meta.

Batch Call Lifecycle

draft --> scheduled --> active --> completed
  |          |           |
  |          +-- paused --+
  |                       |
  +-- failed / cancelled <+

Status	Description
`draft`	Created, accepts contact uploads and updates
`scheduled`	Contacts distributed with timestamps, waiting for execution
`active`	Calls are being fired by the background job
`paused`	Execution halted; can be resumed
`completed`	All contacts processed
`failed`	Scheduling or execution error
`cancelled`	Manually cancelled

Endpoints

​Batch Calls

​List Batch Calls

​Create Batch Call

​Get Batch Call

​Update Batch Call

​Delete Batch Call

​List Batch Call Contacts

​Upload Contacts to Batch Call

​Schedule Batch Call

​Pause Batch Call

​Resume Batch Call

​Get Batch Call Analytics

​Bulk Delete Batch Calls

​Batch Call Lifecycle