---
title: "Create a batch call"
method: POST
path: "/calls/batch"
tags: ["batchCalls"]
---

# Create a batch call

`POST /calls/batch`

Creates a batch of outbound calls that are dialed over time as your account's concurrency allows. Provide `batch_call_id` to append more recipients to an existing batch instead of creating a new one. A batch holds up to 1000000 recipients in total, and is canceled along with its queued recipients if it has not finished within seven days.

## Headers

- `Authorization` string, required

## Request body

- object
  - `name` string — A display name for the batch.
  - `model_id` string — The agent that places the calls. Required when creating a new batch, ignored when appending to an existing one.
  - `from_phone_number` string — The caller ID used for every call in the batch. Required when creating a new batch, ignored when appending.
  - `batch_call_id` string, uuid — An existing batch to append the recipients to. When set, `model_id`, `from_phone_number`, `trigger_timestamp`, `reserved_concurrency` and `call_time_window` are ignored.
  - `trigger_timestamp` integer — Unix timestamp in milliseconds at which dialing starts. Omit to start dialing immediately.
  - `reserved_concurrency` integer — Number of concurrent call slots held back for calls outside this batch. Must be lower than the account's maximum concurrent calls.
  - `call_time_window` CallTimeWindow — Calling window evaluated in the agent's timezone. Recipients that come up while the window is shut wait for it to open. This does not replace the agent's working hours, which are checked separately when the call is placed, so a window that falls outside them fails every call. When neither is configured, recipients are dialed at any time.
    - `enable` boolean — Whether the window is enforced. Defaults to true when `weekly_hours` is provided.
    - `weekly_hours` object — Keys are lowercase weekday names (`monday` to `sunday`). Each day holds a list of windows in `HH:MM` 24-hour format with `start` earlier than `end`. A missing or empty day means no calls on that day.
  - `tasks` CallsBatchPostRequestBodyContentApplicationJsonSchemaTasksItems[], required — The recipients to call. Between 1 and 10000 per request. Append to the batch to go beyond that, up to 1000000 recipients in total.
    - `id` string — Optional caller-supplied recipient id, unique within the batch. Recipients re-sent with an id that already exists in the batch are skipped, which makes retries safe.
    - `to_phone_number` string, required — The recipient's phone number.
    - `lead_name` string — The recipient's name.
    - `lead_email` string — The recipient's email address.
    - `custom_variables` object — Prompt variables forwarded to the call, as key-value pairs.
    - `override_model_id` string — Agent to use for this recipient instead of the batch's `model_id`.

## Response `200`

200

- BatchCallsCreateABatchCallResponse200
  - `status` string
  - `response` CallsBatchPostResponsesContentApplicationJsonSchemaResponse
    - `batch_call_id` string
    - `name` string
    - `from_phone_number` string
    - `scheduled_timestamp` integer — Unix timestamp in milliseconds at which dialing starts. Null when dialing starts immediately.
    - `total_task_count` integer — Recipients stored in the batch after this request, excluding duplicates that were skipped.
    - `call_time_window` CallTimeWindow — Calling window evaluated in the agent's timezone. Recipients that come up while the window is shut wait for it to open. This does not replace the agent's working hours, which are checked separately when the call is placed, so a window that falls outside them fails every call. When neither is configured, recipients are dialed at any time.
      - `enable` boolean — Whether the window is enforced. Defaults to true when `weekly_hours` is provided.
      - `weekly_hours` object — Keys are lowercase weekday names (`monday` to `sunday`). Each day holds a list of windows in `HH:MM` 24-hour format with `start` earlier than `end`. A missing or empty day means no calls on that day.
    - `status` string

## Other responses

- `400` — Invalid payload, or the batch is completed or canceled and cannot take new recipients.
- `401` — Missing or invalid API key.
- `404` — `batch_call_id` was provided but no batch with that id exists in the workspace.

---

[API](https://skmtc.dev/synthflow/apis/platform-api.md) · [All operations](https://skmtc.dev/synthflow/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/synthflow/platform-api/revisions/6976456ad422/schema)