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

Speechify-VersionstringOptional

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

X-Request-IDstring

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an X-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.

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends an `X-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.

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 nullformat: "^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.

errorstring

Populated when the batch itself fails.

started_atdatetime or null

When the dispatcher started dialing.

ended_atdatetime or null

When the last recipient was resolved.

scheduled_atdatetime or null

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

ringing_timeout_msinteger or null

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