---
title: "Create an outbound calling task in draft status; nothing is dialed until it is started"
method: POST
path: "/v1/tasks"
---

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

`POST /v1/tasks`

## Request

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

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.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `name` string, required: Name shown in task lists and history.
  - `agentId` string, 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.
  - `externalRefs` object: Links to provider records used to verify the business outcome. Supply ids from your owned connections, not copied invoice or event status.
    - `invoice` object: Invoice whose fresh provider evidence is checked for this task.
      - `connectionId` string, required: Owned Fakturoid or ABRA Flexi connection id from GET /v1/integrations.
      - `externalId` string, required: Opaque invoice id from the connection's invoice list, passed unchanged.
      - `provider` 'fakturoid' | 'abra-flexi': Invoice provider matching the referenced connection.
    - `calendar` object: Calendar event whose fresh provider evidence is checked for this task.
      - `connectionId` string, required: Owned Google or Apple Calendar connection id.
      - `calendarId` string, required: Calendar id returned by the connection's calendar list.
      - `eventId` string, required: Opaque externalId from the event list. Pass unchanged; an Apple resource id is not its iCalendar UID.
      - `provider` 'google-calendar' | 'apple-calendar': Calendar provider matching the referenced connection.
  - `recipients` object[], required: Recipients to call. On PATCH this replaces the entire list, rather than merging. Cannot change after dialing has started.
    - `phone` string, required: Recipient phone number, normalized to E.164. Only supported Czech and Slovak destinations can be called.
    - `variables` object: Recipient-specific values available to the agent, for example customer_name or order_id. Do not include secrets.
    - `externalRefs` object: Links to provider records used to verify the business outcome. Supply ids from your owned connections, not copied invoice or event status.
      - `invoice` object: Invoice whose fresh provider evidence is checked for this task.
        - `connectionId` string, required: Owned Fakturoid or ABRA Flexi connection id from GET /v1/integrations.
        - `externalId` string, required: Opaque invoice id from the connection's invoice list, passed unchanged.
        - `provider` 'fakturoid' | 'abra-flexi': Invoice provider matching the referenced connection.
      - `calendar` object: Calendar event whose fresh provider evidence is checked for this task.
        - `connectionId` string, required: Owned Google or Apple Calendar connection id.
        - `calendarId` string, required: Calendar id returned by the connection's calendar list.
        - `eventId` string, required: Opaque externalId from the event list. Pass unchanged; an Apple resource id is not its iCalendar UID.
        - `provider` 'google-calendar' | 'apple-calendar': Calendar provider matching the referenced connection.
  - `callingWindow` object: Local times and weekdays in which new calls may begin. Does not interrupt a call already in progress.
    - `timezone` 'Europe/Prague': Timezone used to interpret the window. Currently only Europe/Prague is supported, including its daylight-saving changes.
    - `start` string: Beginning of the daily calling window, HH:mm in the selected timezone.
    - `end` string: End of the daily calling window, HH:mm in the selected timezone, inclusive of that whole minute (18:00 still allows a call at 18:00:59); must be later than start.
    - `days` integer[]: Weekdays on which dialing is allowed: 0 is Sunday, 1 Monday, through 6 Saturday.
  - `maxAttempts` integer: 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.
  - `expiresAt` integer: 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.
  - `maxDurationSecs` integer: Maximum duration of each call in seconds.
  - `budgetHal` integer, required: Maximum task spend in integer halere, excluding VAT. The task stops dispatching when the remaining budget cannot cover another call.

## Response `200`

Created task

- object
  - `task` object, required
    - `purpose` 'standard' | 'coupon_reminder', required: Immutable task purpose. Coupon reminders require manual/custom, maxAttempts 1, expiresAt and a trusted server preflight.
    - `id` string, required
    - `name` string, required
    - `agentId` string, required
    - `taskType` 'invoice' | 'appointment' | 'custom', required
    - `source` 'manual' | 'integration', required
    - `externalRefs` object
      - `invoice` object
        - `connectionId` string, required
        - `externalId` string, required
        - `provider` 'fakturoid' | 'abra-flexi'
      - `calendar` object
        - `connectionId` string, required
        - `calendarId` string, required
        - `eventId` string, required
        - `provider` 'google-calendar' | 'apple-calendar'
    - `callingWindow` object, required
      - `timezone` 'Europe/Prague', required
      - `start` string, required
      - `end` string, required
      - `days` number[], required
    - `maxAttempts` union, required: Maximum automatic attempts including the first. Values 1-3 without a retry policy; 1-4 with lorela_enterprise.
      - 1
      - 2
      - 3
      - 4
    - `retryPolicy` 'lorela_enterprise': Opt-in retry schedule. Absent on tasks using the existing retry behavior.
    - `dispatchOrder` 'first_attempts_first': Prioritize due recipients without a counted attempt before due retries. Pre-dispatch rejections do not count. Omitted preserves item order.
    - `expiresAt` integer: Unix milliseconds after which no new call may begin, including the first attempt. Does not interrupt an active call.
    - `maxDurationSecs` number, required
    - `budgetHal` number, required
    - `reservedBudgetHal` number, required
    - `spentHal` number, required
    - `status` 'draft' | 'ready' | 'running' | 'paused' | 'completed' | 'needs_attention', required
    - `revision` number, required
    - `createdAt` number, required
    - `updatedAt` number, required
    - `lastError` string
    - `reviewReason` string
    - `activeItemId` string
    - `items` object[], required
      - `id` string, required
      - `phone` string, required
      - `variables` object, required
      - `externalRefs` object
        - `invoice` object
          - `connectionId` string, required
          - `externalId` string, required
          - `provider` 'fakturoid' | 'abra-flexi'
        - `calendar` object
          - `connectionId` string, required
          - `calendarId` string, required
          - `eventId` string, required
          - `provider` 'google-calendar' | 'apple-calendar'
      - `paymentStatus` 'not_applicable' | 'unknown' | 'unpaid' | 'paid' | 'disputed', required
      - `status` 'pending' | 'in_progress' | 'completed' | 'skipped' | 'failed' | 'review', required
      - `attempts` object[], required
        - `id` string, required
        - `startedAt` number, required
        - `finishedAt` number
        - `providerCallId` string
        - `outcome` 'placed' | 'completed' | 'no_answer' | 'busy' | 'failed' | 'unknown'
        - `countsAsAttempt` boolean
        - `errorCode` string
        - `costHal` number
        - `variables` object
        - `goalResult` 'success' | 'failure' | 'unknown'
        - `statement` 'promised' | 'disputed' | 'none' | 'unknown'
        - `nextStep` string
      - `nextAttemptAt` number
      - `resolution` object
        - `action` 'skip', required
        - `reason` 'customer_purchased', required
        - `operationId` string, required
        - `evidenceRef` string, required
        - `fingerprint` string, required
        - `resolvedAt` number, required
      - `lastError` string
      - `reviewReason` string
      - `providerCallId` string
      - `estimatedCostHal` number
      - `reservedCostHal` number
      - `actualCostHal` number
  - `warnings` object[]: Present only when the saved text (agent configuration, draft or tool description), the call variables, the task name or variables, or the trial call prompt contains wording that may come across as impersonating an authority or another institution, or as a request for sensitive information - code agent_misuse_suspected. It never blocks the request; the field is absent when there is nothing to flag.
    - `code` 'agent_misuse_suspected', required
    - `message` object, required
      - `cs` string, required
      - `en` string, required

## Other responses

- `400`: Error codes: validation (request), budget_too_low (request).
- `401`: Error codes: unauthorized (request).
- `403`: Error codes: account_suspended (account).
- `404`: Error codes: agent_not_found (account).
- `409`: Error codes: idempotency_in_progress (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service).

---

[API](https://skmtc.dev/volai/apis/volai-rest-api.md) · [All operations](https://skmtc.dev/volai/apis/volai-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/volai/apis/volai-rest-api/revisions/12029b05e2fa?raw)