Create Batch Call | SpeechifyAI API

curl -X POST https://api.speechify.ai/v1/agents/batch-calls \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Appointment reminders",
  "agent_id": "agent_01HS...",
  "recipients": [
    {
      "phone": "+14155551234",
      "dynamic_variables": {
        "appointment_date": "May 5th at 2pm",
        "first_name": "Alice"
      }
    },
    {
      "phone": "+14155555678",
      "dynamic_variables": {
        "appointment_date": "May 6th at 10am",
        "first_name": "Bob"
      }
    }
  ]
}'

{
  "id": "batch_01kj8fy7kphhchfcfc230hgv12",
  "agent_id": "agent_01HS...",
  "name": "Appointment reminders",
  "status": "pending",
  "total": 2,
  "completed": 0,
  "failed": 0,
  "created_at": "2024-01-15T09:30:00Z",
  "updated_at": "2024-01-15T09:30:00Z"
}

Dial a list of phone numbers through one of your voice agents in a single request. Each recipient can receive personalised dynamic variables that your agent prompt references via {{key}} placeholders. Batches can run immediately or be scheduled up to 30 days in advance.

Accepts application/json or multipart/form-data (with a CSV file). Max 1000 recipients per batch.

Dial a list of phone numbers through one of your voice agents in a single request. Each recipient can receive personalised dynamic variables that your agent prompt references via `{{key}}` placeholders. Batches can run immediately or be scheduled up to 30 days in advance. Accepts `application/json` or `multipart/form-data` (with a CSV file). Max 1000 recipients per batch.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

namestringRequired

Human-readable batch name.

agent_idstringRequired

Agent that handles each call.

recipientslist of objectsRequired

phone_number_idstringOptional

Caller-ID override. Falls back to the agent’s bound number.

scheduled_atdatetimeOptional

Schedule the batch for a future time (RFC 3339). Omit to start immediately.

ringing_timeout_msintegerOptional1000-80000

Ringing timeout in milliseconds applied to every call in the batch (how long each recipient rings before the dial gives up). Range 1000-80000 (1-80s). Omit to use the 30s default. Express this in milliseconds even if a UI collects seconds.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

Batch accepted for processing.

idstringformat: "^batch_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (batch_<26 char Crockford base32>). URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404.

agent_idstringformat: "^agent_[0-9a-hjkmnp-tv-z]{26}$"

Prefixed wire identifier (agent_<26 char Crockford base32>) of the agent that will run the batch.

namestring

Human-readable batch name.

statusenum

Lifecycle status. A batch deferred to a future time is pending with a non-null scheduled_at; it moves to running once the scheduled time arrives and the dispatcher starts dialing.

totalinteger

Total number of recipients (the progress denominator).

completedinteger

Recipients successfully dialed.

failedinteger

Recipients that failed.

created_atdatetime

updated_atdatetime

phone_number_idstring or nullOptionalformat: "^phone_[0-9a-hjkmnp-tv-z]{26}$"

Caller-ID override. When set, prefixed wire identifier (phone_<26 char Crockford base32>) of the phone number to use; falls back to the agent’s bound number when null.

errorstringOptional

Populated when the batch itself fails.

started_atdatetime or nullOptional

When the dispatcher started dialing.

ended_atdatetime or nullOptional

When the last recipient was resolved.

scheduled_atdatetime or nullOptional

If set, the batch waits until this time before dialing.

ringing_timeout_msinteger or nullOptional

Per-call ringing timeout in milliseconds applied to every recipient in the batch. Null when the batch uses the 30s default.

Errors

400

Bad Request Error

401

Unauthorized Error

409

Conflict Error