Skip to main content
POST
Create Batch

Headers

string
required
Your API key for authentication.
string
Optional encrypted key used for securing batch payloads.Learn more about BYOT here.

Body

array
A list of individual call objects to include in the batch. Each object follows the same schema as /v1/calls.
Example
object
required
Global call properties to apply to all call_objects, unless overridden per entry.

Required keys:
  • Must include at least one of: "task" or "pathway_id".

    Forbidden keys:
  • "phone_number" is not allowed in the global object.
Example:
Example
string
A short label for the batch shown in the dashboard. Maximum 60 characters. Defaults to "Untitled Batch" if not provided.
string
Optional URL to receive batch status updates. We send a single POST per lifecycle phase and one final POST when the batch completes or fails. Payload is JSON with batch_id, status, and timestamp; final events include calls_total / calls_successful / calls_failed or code and reason on failure. Your endpoint should respond with 200 within a few seconds; we wait up to 10 seconds per call. See Status webhook below for payload details.

Response

object
The response includes the batch_id of the newly created batch.
string
The unique identifier for the batch.
null
Always null on success.

Status webhook

If you provide status_webhook, we POST to that URL at each lifecycle phase and once when the batch finishes. All requests use Content-Type: application/json. Status values: validating | dispatching | in_progress | in_progress_chunked | waiting_for_scheduled_calls | completed | failed | completed_partial Common fields on every request: batch_id (string), status (string), timestamp (ISO 8601). Progress events may include message (string). Final events include call counts or error details as below. Progress examples:
Validating
In progress (with message)
Final events:
Completed
Failed
Completed partial (e.g. timeout)
We send one attempt per event with a 10-second timeout. If the request fails or times out, we log and continue; the workflow is not retried or failed. Respond with 2xx quickly and perform any heavy work asynchronously.
Docs for agents: llms.txt