Skip to main content

API Endpoint

Request Headers

required
Bearer your-api-key
required
application/json

Request Body

string
required
The ID of the outbound agent to use for all calls in the batch.
array
required
List of calls to queue. Minimum 1, maximum 100 per request. Each item must include phoneNumber and optionally promptVariables and metadata.
string
required
The phone number to call (e.g., "966501234567"). Must match your SIP trunk’s outbound format.
object
Dynamic variables injected into the agent’s prompt for this specific call. Key-value pairs of strings.
object
Arbitrary metadata attached to this call. Not passed to the agent prompt.

Response

boolean
required
true if at least one call was queued successfully.
object
required
The duplicate handling policy applied to this batch.
string
required
DEDUPE — duplicate phone numbers within the same request are dropped. SPACED — duplicates are allowed but spaced 10 minutes apart.
number
required
Minutes between duplicate calls when mode is SPACED. Always 10.
object
required
Counts for the outcome of each call in the batch.
number
required
Total number of calls received in the request.
number
required
Calls queued for immediate dialing.
number
required
Calls queued with a future scheduled time (only applies in SPACED mode for duplicates).
number
required
Calls dropped because the same phone number already appeared earlier in the request (only in DEDUPE mode).
number
required
Calls that failed validation or hit a rate limit.
array
required
Per-call outcome list. One entry per call in the original request.
string
required
The phone number from the original request.
string
required
One of: queued_now, queued_later, failed, deduped.
string
ISO timestamp of when the call will be dialed. Only present when action is queued_later.
string
Failure or dedup reason. Only present when action is failed or deduped.
string
required
Webhook ID for tracking this batch’s call events.
string
required
The agent ID used for the batch.
number
required
Total calls received (same as summary.received).
number
required
Total calls successfully queued (queuedNow + queuedLater).
number
required
Total calls that failed.
number
required
Number of duplicate phone numbers removed in DEDUPE mode.

Duplicate Handling

The duplicate policy is configured per company in the dashboard. The default is DEDUPE. DEDUPE (default): If the same phone number appears more than once in a single request, only the first occurrence is queued. The rest are dropped with action: "deduped". SPACED: All occurrences are queued but spaced 10 minutes apart. Later duplicates will have action: "queued_later" with a scheduledFor timestamp.

Error Handling

string
Top-level error message when the entire request fails (e.g., agent not found, missing SIP trunk).
Per-call failures are returned in data.items with action: "failed" and a reason field — they do not cause the whole request to fail.

Common Errors

  • "phoneNumber" or "calls" must be provided, not both — do not mix single-call and batch fields in the same request
  • promptVariables/metadata must be per-call for batch requests — top-level promptVariables is not allowed for batch; put them inside each call item
  • Agent not found / not configured — agent must be an outbound agent with a SIP trunk
  • Contact rate limit — a phone number was called too recently; data.items[].reason will include the reset time

Webhooks

Real-time Call Events

Subscribe to webhooks to receive real-time notifications for each call in the batch. All calls in a batch share the same webhookId.