---
title: "Initiate bulk outbound calls with AI agent"
method: POST
path: "/api/v1/phones/calls/initiate-bulk"
tags: ["Phones - Calls"]
---

# Initiate bulk outbound calls with AI agent

`POST /api/v1/phones/calls/initiate-bulk`

## Request

- Base URL: `https://api.voicelogica.ai`
- URL: `https://api.voicelogica.ai/api/v1/phones/calls/initiate-bulk`
- Auth: API key in header `x-api-key`

Initiate multiple outbound AI phone calls in a single request. Each call is scheduled and processed independently, allowing partial success — some calls may succeed while others fail.

**Use Case:**
Use this endpoint instead of calling initiate-call repeatedly when you need to reach multiple phone numbers. Ideal for campaigns, batch follow-ups, appointment reminders, or any scenario requiring parallel outreach.

**Request:**
- `calls`: Array of 1–50 call requests, each with a phone number and optional per-call settings
- Each call entry accepts the same fields as the single initiate-call endpoint
- If `agentId` or `voipPhoneId` are omitted, the company's MCP default settings are used

**Per-Call Fields:**
- `phoneNumber` (required): Destination number in E.164 format (e.g., +306912345678)
- `agentId` (optional): AI agent to handle this specific call
- `voipPhoneId` (optional): VoIP phone to use for this specific call
- `callerId` (optional): Override caller ID shown to the recipient
- `contextForAi` (optional): Additional context appended to the agent's system prompt
- `dynamicVariables` (optional): Key-value pairs accessible to the agent (e.g., customer name, order ID)
- `scheduledAt` (optional): ISO 8601 date-time to schedule the call for a future time
- `maxRetries` (optional): Retry attempts if call fails (0–3, default 2). Retries occur after 10 minutes
- `overrideTimeRestriction` (optional): Bypass 9 AM – 9 PM local time restrictions

**Scheduling Behavior:**
- All bulk calls are created as **scheduled** calls (status: "scheduled")
- If `scheduledAt` is provided and is in the future, the call is scheduled for that time
- If `scheduledAt` is omitted or in the past, the call is scheduled 1 minute from now
- The system processes scheduled calls automatically at their scheduled time

**Anti-Harassment Protection:**
- All bulk calls have anti-harassment protection enabled by default
- Limits: max 3 outbound calls/day, 1-hour cooldown between outbound calls to the same number
- Calls that violate these limits will fail with a descriptive error

**Response:**
Returns an array of results in the same order as the input calls array. Each result contains:
- `phoneNumber`: The destination number
- `success`: Whether the call was scheduled successfully
- `id`: Call ID for tracking (on success) — use with GET /{id} or cancel-scheduled-calls
- `status`: Always "scheduled" on success
- `message`: Human-readable status with scheduling details
- `error`: Error description (on failure)

**Limits:**
- Maximum 50 calls per request
- Subject to your plan's concurrent call limits and available channels
- Each call counts toward anti-harassment quotas independently

**HTTP Status Codes:**
- `200 OK`: Request processed (check individual results for per-call success/failure)
- `400 Bad Request`: Invalid request body (empty array, exceeds 50 calls, or schema validation error)
- `500 Internal Server Error`: Server-side error (retry later)

**Example Workflow:**
1. Call this endpoint with an array of phone numbers and per-call context
2. Check the response for per-call success/failure
3. Use GET /calls/{id} to check individual call results after they complete
4. Use GET /calls/statistics to see aggregate campaign performance

## Headers

- `x-api-key` string, required
- `x-company-id` string

## Request body

- object: Request schema for initiating bulk outbound AI phone calls
  - `calls` object[], required: Array of call requests to process (1–50 calls per request). Each entry follows the same schema as the single initiate-call endpoint.
    - `phoneNumber` string, required: Destination phone number to call (E.164 format preferred, e.g., +306912345678)
    - `agentId` string: Agent ID to handle the call. Falls back to company's default agent from MCP settings if not provided
    - `voipPhoneId` string: VoIP phone ID for the call. Falls back to company's default VoIP phone from MCP settings if not provided
    - `callerId` string: The phone number or SIP URI shown to the recipient as the caller. Overrides the default caller ID of the VoIP phone. Use a full E.164 phone number (e.g. "+302101234567") or a SIP identity (e.g. "sip:user@domain.com"). If omitted, the VoIP phone's own caller ID is used.
    - `contextForAi` string: Additional context appended to the agent's system prompt for this specific call. Typically contains customer details, call purpose, or situation-specific information. Example: "Customer has open support ticket #1234, prefers communication in Greek."
    - `dynamicVariables` object: Key-value pairs accessible to the AI agent during the call as named template variables. Example: { "customer_name": "John Doe", "order_id": "ORD-123" }
    - `scheduledAt` string: Schedule the call for a future date/time (ISO 8601 format, e.g. "2026-03-22T14:00:00Z"). If not provided or in the past, the call is scheduled 1 minute from now.
    - `maxRetries` number: Total calls to this number, the first one included (0–3, default 2): 2 = the first call plus 1 retry; 0 or 1 = no retry. A retry is placed 10 minutes after a busy line, no answer, voicemail or a failed call.
    - `overrideTimeRestriction` boolean: Bypass 9 AM – 9 PM local time restrictions for the destination country. Set to true to call at any time.

## Response `200`

Bulk calls processed — per-call results returned

- object[]: Array of per-call results — one entry per call in the request, in the same order
  - `phoneNumber` string, required: The destination phone number for this call
  - `success` boolean, required: Whether the call was successfully scheduled
  - `id` string: Call ID if successful — use this to track the call via get-call-by-id or cancel via cancel-scheduled-calls
  - `status` string: Call status if successful (always "scheduled" for bulk calls)
  - `callerId` string: Caller ID if successful
  - `message` string: Human-readable status message with scheduling details and guidance
  - `error` string: Error description if the call could not be scheduled

## Other responses

- `400`: Bad Request — invalid request body or empty calls array
- `401`: Unauthorized
- `403`: Invalid CSRF
- `429`: Rate limit exceeded
- `500`: Internal Server Error

---

[API](https://skmtc.dev/voicelogica/apis/voice-logica-api.md) · [All operations](https://skmtc.dev/voicelogica/apis/voice-logica-api/llms.txt) · [OpenAPI document](https://skmtc.dev/voicelogica/apis/voice-logica-api/revisions/30f76840084e?raw)