Schedule a call
Books an outbound call from a published agent for run_at, which must carry a timezone offset and be between 30 seconds and a year away. Send an Idempotency-Key. Your do-not-call list, minutes and limits are checked again when it dials, and an unanswered call is retried.
Scopes: call:create
Authorizations
An API key from Settings → API keys, sent as Authorization: Bearer kb_live_…. A workspace key starts kb_; a personal key starts kbp_ and acts as its owner.
Headers
A unique key (a UUID works) for this request. Retrying with the same key returns the first answer instead of running twice.
255The API version to answer as, a date (YYYY-MM-DD). Leave it out for the current version (2026-11-07). An unknown version is refused with 400 unsupported_api_version.
2026-11-07 "2026-11-07"
Body
The agent that makes the call. It must be published and allowed to dial out.
The number to call, in E.164 (e.g. +971501234567).
8 - 20When to dial (ISO 8601 with a time zone). Must be in the future.
The caller ID, in E.164: one of your numbers. Omit to use the agent's caller number.
8 - 20The callee's IANA time zone (e.g. Asia/Dubai), kept with the booking for showing its time.
1 - 64Why the call is booked; the agent is told.
280Values for the agent's {{variables}} (e.g. first_name). At most 50 keys.
Response
Successful Response
The scheduled call's id.
The agent that makes the call.
The callee's IANA time zone.
manual (booked through the API or dashboard), callback (a caller asked) or retry.
manual, callback, retry proposed (a callback waiting for confirmation; never dials on its own), scheduled, dialing, done, canceled or failed.
proposed, scheduled, dialing, done, canceled, failed Dial attempts made.
The number to call, masked.
When it dials (ISO 8601).
Why it was booked.
Values for the agent's {{variables}}.
The call that asked for it, for a callback.
The call it placed, once dialled.
The number it calls from.
Why the last attempt failed.
Who booked it.
When it was booked (ISO 8601).
When it last changed (ISO 8601).
The number to call, unmasked (single reads and writes only).