---
title: "Place a call - through an agent, as a bridge, or a trial call"
method: POST
path: "/v1/calls"
---

# Place a call - through an agent, as a bridge, or a trial call

`POST /v1/calls`

## Request

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

Place one billed call. Send exactly one of agentId (your agent with an attached number), from (bridge: rings from first, then to), or systemPrompt (trial from a shared demo number). Only the agent variant accepts variables. Ringing timeout is 5-60 seconds for an agent and 5-30 for a trial, default 25. A successful response means placement started; read GET /v1/calls/{id} or wait for a webhook to learn the actual outcome. Trial calls require a verified account and have separate usage limits.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - object
    - `to` string, required: Destination with Czech +420 or Slovak +421 country code, normalized to E.164.
    - `agentId` string, required: Owned agent with an attached phone number. Send exactly one of agentId, from or systemPrompt.
    - `variables` object: Dynamic variables for the agent: at most 20 entries, keys up to 64 characters and values up to 512. attempt_id, caller_number, called_number, trial_prompt and trial_first_message are overwritten by the system; system__ and volai_ keys are reserved and rejected.
    - `ringingTimeoutSecs` integer: Seconds to wait for the destination to answer; defaults to 25.
  - object
    - `to` string, required: Destination with Czech +420 or Slovak +421 country code, normalized to E.164.
    - `from` string, required: Number that rings first for a bridge call; after pickup, volai dials to. It need not belong to your account. Send exactly one of from, agentId or systemPrompt.
  - object
    - `to` string, required: Destination with Czech +420 or Slovak +421 country code, normalized to E.164.
    - `systemPrompt` string, required: Instructions for a trial call from a shared demo number. Send exactly one of systemPrompt, agentId or from.
    - `firstMessage` string: Optional opening line for a trial call.
    - `ringingTimeoutSecs` integer: Seconds to wait for the destination to answer; defaults to 25.

## Response `200`

Created call

- object
  - `id` string, required
  - `status` 'initiated' | 'ringing' | 'in_progress' | 'completed' | 'failed' | 'missed' | 'no_answer', required
  - `trial` boolean
  - `from` string
  - `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: invalid_number (request), validation (request), on_dnc (account), destination_auto_blocked (account), cannot_call_own_number (request), cannot_call_volai_number (request).
- `401`: Error codes: unauthorized (request).
- `402`: Error codes: insufficient_credit (account), subscription_cap_reached (account).
- `403`: Error codes: account_suspended (account), agent_suspended (account), trial_email_unverified (account).
- `404`: Error codes: bridge_needs_number (account), agent_not_found (account), agent_no_number (account).
- `409`: Error codes: idempotency_in_progress (busy), destination_busy (busy).
- `429`: Error codes: rate_limited (busy).
- `500`: Error codes: internal_error (service), trial_not_configured (service).
- `502`: Error codes: call_rejected (service), callback_failed (service), engine_unavailable (service).
- `503`: Error codes: capacity_busy (busy), trial_calls_disabled (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)