Create an outbound calling task in draft status; nothing is dialed until it is started

Creates a task in draft status - nothing gets dialed. agentId can be any active agent, including one on ElevenLabs - the engine requirement (provider: "engine", chosen at creation via useForOutboundTasks: true) is only checked at POST .../start, which then fails with engine_required. At most 1000 recipients. Without retryPolicy, maxAttempts is 1-3 and defaults to 1; with optional retryPolicy: "lorela_enterprise" it is 1-4 and defaults to 4. Optional expiresAt (positive safe-integer Unix milliseconds) prevents new calls at or after the campaign deadline, including the first. Both policy and deadline are returned in the task detail. Supports Idempotency-Key. Optional immutable purpose defaults to standard. coupon_reminder requires source: manual, taskType: custom, explicit maxAttempts: 1 and expiresAt. Before dialing, a trusted server gate verifies the exact reminder; user variables cannot override its greeting or coupon. Without gate configuration, the reminder is not dialed.

post/v1/tasks

Request

  • Base URL: https://volai.cz
  • URL: https://volai.cz/v1/tasks
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional key for one logical request. Its scope is global to this API key, independent of the HTTP method, path, or body: use a new value for every distinct logical action across all endpoints and request bodies, and reuse it only to retry the exact same logical request. Reusing a non-blank key within 24 hours returns the stored response; a concurrent request with the same key returns 409 idempotency_in_progress. A missing or whitespace-only value disables idempotency.

Request body

namestring required

Name shown in task lists and history.

agentIdstring required

Owned agent to call recipients. Engine provider and an attached number are required before starting the task, but creation can prepare it earlier. Cannot be changed after creation.

taskType'invoice' | 'appointment' | 'custom' required

Business purpose of the task, used to select its outcome checks. Cannot be changed after creation.

source'manual' | 'integration' required

Where this task originated. Cannot be changed after creation.

purpose'standard' | 'coupon_reminder'

Immutable task purpose, standard by default. coupon_reminder requires manual source, custom taskType, explicit maxAttempts 1 and expiresAt. A trusted server preflight must authorize each reminder before dialing.

maxAttemptsinteger

Maximum automatic call attempts per recipient, including the first. Without retryPolicy: 1-3, creation default 1. With lorela_enterprise: 1-4, creation default 4 when omitted. On PATCH, a value of 4 requires the policy in the request or already stored on the task.

retryPolicy'lorela_enterprise'

Opt-in lorela_enterprise schedule: second attempt no earlier than 8 minutes after the first real attempt started, inside 08:00-22:00 Europe/Prague; third in the next other 08:00-09:00 or 17:00-19:00 window; fourth on the following calendar day in the opposite window. All attempts also respect callingWindow, expiry, budget, DNC and rate limits. Retries stop after 5 days from the first real attempt. Manual resolve retry is rejected with validation; only scheduled automatic attempts are allowed, so it cannot bypass the four-attempt cap, the age limit or a non-retryable result. Only no_answer, missed, busy or completed voicemail without human contact are retried; human contact, refusal and engine failure stop automatic retries, and ambiguous results need review. May be enabled only before any dispatch attempt; resending the same policy is allowed later. Omission preserves existing behavior at creation and the current policy on PATCH. PATCH does not reset maxAttempts when it is omitted.

dispatchOrder'first_attempts_first'

Optional first_attempts_first prioritizes due recipients with zero counted attempts before due retries in both cron and explicit processing. Pre-dispatch rejections marked countsAsAttempt:false retain first-attempt priority; future backoff remains enforced. Default preserves item order. Set before the first dispatch attempt.

expiresAtinteger

Optional campaign deadline as positive safe-integer Unix milliseconds. Checked at start and before every dial, including the first; at or after the deadline nothing new is dialed and no attempt is consumed. Calls already in progress finish normally. Omission preserves the current deadline on PATCH.

maxDurationSecsinteger

Maximum duration of each call in seconds.

budgetHalinteger required

Maximum task spend in integer halere, excluding VAT. The task stops dispatching when the remaining budget cannot cover another call.

Response

Created task

Changes

No recorded changes to this operation across all 1 revision of this API.