Batch Calls

Manage high-volume outbound calling batches.

List Batch Calls

Query: agent_id (optional), status (optional), limit (default 50, max 100), offset (default 0). Response includes data (array of batch call objects) and pagination.

Get Batch Call

Create Batch Call

Request body

Field	Type	Required	Description
`name`	string	Yes	Campaign name (1–255 chars).
`agent_id`	string (UUID)	Yes	Agent that will make the calls.
`phone_number_ids`	array of UUIDs	No	Outbound number IDs. If empty, numbers assigned to the agent are used.
`phone_rotation_strategy`	string	No	`random`, `sequential`, or `round_robin`. Default `random`.
`contact_source`	string	No	`csv`, `folder`, or `manual`. Default `csv`.
`contact_folder_id`	string (UUID)	When source=folder	Required when `contact_source` is `folder`; contacts are loaded from this folder.
`schedule_type`	string	No	`immediate` or `scheduled`. Default `immediate`.
`scheduled_at`	string (ISO datetime)	When scheduled	Required when `schedule_type` is `scheduled`.
`timezone`	string	No	Default `UTC`.
`start_time`, `end_time`	string (HH:MM)	No	Daily calling window.
`working_days`	array of 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	Optional cap per day.
`retry_failed`	boolean	No	Default false.
`max_retry_attempts`	int	No	0–3. Default 0.

Send X-Idempotency-Key for safe retries. The agent must exist and be active and ready for calls; at least one valid outbound phone number is required (assigned to the agent or in phone_number_ids). Example

{
  "name": "Q1 Outreach",
  "agent_id": "AGENT_UUID",
  "contact_source": "folder",
  "contact_folder_id": "FOLDER_UUID",
  "schedule_type": "immediate",
  "max_concurrent_calls": 5
}

Response: 201 Created with data (batch call object: id, name, agent_id, status (e.g. draft), contact_source, and other configured fields) and meta.

Update Batch Call

Body: Any of name, phone_number_ids, phone_rotation_strategy, scheduled_at, start_time, end_time, working_days, max_concurrent_calls, max_calls_per_day, retry_failed, max_retry_attempts. Only allowed when the batch is in draft status.

Delete Batch Call

Schedule Batch Call

Starts the batch (draft with contacts). Returns 422 if the batch is not in draft, has no contacts, or scheduling fails (e.g. provider error).

Pause Batch Call

Pauses an active or scheduled batch. Returns 422 with a message if the batch is not in active or scheduled status (e.g. already paused or still draft).

Resume Batch Call

Resumes a paused batch. Returns 422 if the batch is not in paused status.

​Batch Calls

​List Batch Calls

​Get Batch Call

​Create Batch Call

​Update Batch Call

​Delete Batch Call

​Schedule Batch Call

​Pause Batch Call

​Resume Batch Call