Start a web Call or an outbound phone Call

POST /v1/calls

Admission runs before any room or dial exists, in the order of control-plane.md section 7.1. From 1.19.0 it refuses with 402 spend_cap_reached when the Organization's spend in the current UTC calendar month is at or above its spend_cap_micros (FR-dispatch-6); from 1.23.0 that spend is the Organization's spend counter, which GET /v1/usage/spend reads. From 1.21.0 it refuses a test Call on real Providers with 429 test_daily_cap_reached once the Organization's test Calls on real Providers have used the daily allowance: 60 minutes of Calls per UTC day (target), configured in the api's environment (FR-platform-8). A test Call counts when any stage of its resolved chains names a Provider that is not a mock Provider; a Call on mock Providers only never counts and is never refused by the cap. A Call in progress is never cut, and the allowance starts again at 00:00 UTC. From 1.22.0 an outbound phone Call is checked before any room or dial exists, in this order, and refused with 403 dial_not_allowed and the detail reason named: a test key (live_environment_required); the Phone number it dials from, from_number_id, else the setting outbound.default_from, else the Organization's earliest active number with the outbound capability (number_not_outbound_capable, no_from_number), where a from_number_id of another Organization answers 404 not_found; the destination country against the dial policy's allowed_countries (country_not_allowed); a premium-rate or special-service destination while block_premium_rate is on (premium_rate); in Phase 0, the api's environment allowlist VOCAL_OUTBOUND_ALLOWLIST of workspace ADR 0070, which stays a second gate after the policy (not_on_environment_allowlist); and the policy's max_concurrent_outbound (outbound_cap_reached). A refusal places no carrier request and is recorded as a denied call.create Audit event with the destination hint, never the number. A server with no outbound dialling configured still answers 422 capability_not_available. From 1.38.0 (workspace ADR 0086 and its amendment of 2026-10-17) admission re-resolves the pinned version over the vendor price rows in force at the admission instant: a reference the version names, primary or Agent secondary, whose model has no list price above 0 for every unit of its stage refuses the Call with 409 agent_version_unavailable and a provider_not_allowed issue with the reason model_unpriced at its pointer, even when its stage keeps another entry, while a registry secondary so unpriced is dropped silently; and an outbound phone Call whose carrier minute has no list price above 0 in force is refused with 422 capability_not_available and one provider_not_allowed issue of stage telephony and reason carrier_unpriced. A web Call has no carrier leg. The Organization's own key changes neither rule. From 1.57.0 (workspace ADR 0048 decision 5) capture asks for verbose capture, and admission refuses it with 403 capture_not_allowed and one detail whose reason is a CaptureRefusalReason when the pinned Compliance profile's verbose_capture is off, or test_only for a live Call; without capture, an open capture window of the Agent that applies to the Call makes it verbose, never refusing it. From 1.61.0 (roadmap slice 2.15) the Call may name its Contact by contact_id or contact, resolved asserted in the admission transaction (a deleted Contact is 409 contact_not_active, an identity several Contacts share 409 contact_match_conflict), and an outbound Call that names one may omit to to dial its primary phone identity (contact_phone_missing). Whether or not it names a Contact, an outbound Call whose destination is opted out of voice for the Organization or the caller ID number is refused with 422 contact_opted_out (step 4a), one detail whose reason is a ConsentCheckReason; nothing is dialled and the Audit event carries the destination hint only. schedule creates the Call scheduled, admitted by its start job at scheduled_at (schedule_in_past, schedule_too_far, window_outside_platform_bound, and schedule_not_outbound for a Call that is not an outbound phone Call, each a detail of validation_failed); a window in the callee's zone with no zone known is 422 calling_window_zone_unknown. retry and voicemail apply to the Call and its retry.

Request

Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the calls:write scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.

curl -X POST "$VOCAL_API/v1/calls" \
  -H "Authorization: Bearer $VOCAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "transport": "web", "agent_id": "agt_..." }'

const response = await fetch(`${process.env.VOCAL_API}/v1/calls`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "transport": "web",
    "agent_id": "agt_..."
  }),
});
console.log(response.status, await response.text());

import os
import uuid

import requests

response = requests.post(
    f"{os.environ['VOCAL_API']}/v1/calls",
    headers={
        "Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "transport": "web",
        "agent_id": "agt_...",
    },
)
print(response.status_code, response.text)

Parameters

Request body

Content type application/json, required: CallCreateRequest.

Responses

Fields of the 201 answer

The shape is CallCreateResponse.