Create a new call

Authorizations

Authorization

string

header

required

Use Authorization: Bearer tc_live_xxxxx

Headers

Idempotency-Key

string

Makes a retry safe. A 2xx response is stored for 24 hours per account, and a retry with the same key gets it back with Idempotent-Replay: true instead of running again. Errors aren't stored, so a retry after one runs fresh. The key isn't tied to a path or body: use a new key for every different request. A malformed key gets 400.

Required string length: 8 - 255

Pattern: ^[A-Za-z0-9_-]+$

Example:

"a1b2c3d4-e5f6-7890-abcd-ef0123456789"

Body

application/json

Option 1
Option 2
Option 3

phone_number

string

required

The number to call, in E.164 format. Required. A number your account can't call (unknown country, toll-free, personal, pager, a high-cost range or a country not enabled) is refused with 422 destination_not_allowed.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+14155551234"

task

string

required

A short description of what the agent should do. Send this or instructions; if you send both, task is used.

Minimum string length: 10

Example:

"Call to confirm John's appointment tomorrow at 3 PM"

from_number

string

Caller ID the person sees. It must be an active or verified number on your account, or the call is refused with 422 from_number_not_owned. A scheduled call is checked again when it comes due and fails for good if the number has left your account. Omit it to call from the default number.

Pattern: ^\+[1-9]\d{1,14}$

Example:

"+18005551234"

first_sentence

string

The agent's opening line. Without it there's no scripted opening; in legacy mode the agent speaks up on its own after about 7 seconds of silence.

Minimum string length: 1

Example:

"Hi, this is Rachel from Bright Dental calling about your appointment."

first_sentence_delay_seconds

integer

default:0

Seconds the agent waits after answer before its opening line, billed as talk time. Useful when people need a moment to get the phone to their ear. With first_sentence_wait_for_caller, it's the longest the agent stays silent before speaking anyway.

Required range: 0 <= x <= 10

Example:

2

first_sentence_wait_for_caller

boolean

default:false

The agent stays silent until the person speaks, then gives its opening line as the reply; their words go to the model as context. Requires first_sentence_delay_seconds of at least 1.

Example:

false

instructions

string

The agent's full system prompt. Ignored when task is also sent.

Minimum string length: 10

Example:

"You are Rachel, a friendly appointment coordinator..."

mode

enum<string>

live runs one voice model that listens and speaks; it refuses block_interruption, bot_protection_enabled, stt_provider, stt_model, tts_provider, tts_model and requires_exact_greeting: true with 400, and ignores voice, transcript_correction_vocabulary, emotion_enabled and the other stt_* and tts_* tuning fields. legacy runs separate speech recognition, model and voice steps. When omitted, the call runs live, or legacy if you send any refused field, a voice, or a model other than the Live model.

Available options:

legacy,

live

voice

string

Legacy voice: a name from GET /v1/voices/builtin (such as rachel) or a voice id. Live calls use live_voice instead.

Minimum string length: 1

Example:

"rachel"

model

string

In legacy, the model that writes every reply, from legacy.llm in GET /v1/models. In live, the model that runs the agent's actions, from live.llm; anything else is refused with 400. Omit it for the default.

Minimum string length: 1

temperature

number

default:0.7

Higher values give more varied replies. Legacy only: Live ignores it, as do models with supports_temperature: false in GET /v1/models.

Required range: 0 <= x <= 1

live_voice

enum<string>

Voice for live calls. When omitted, Romanian calls use bossa and all others gleam, going by stt_language or the first stt_languages entry.

Available options:

marin,

quartz,

ripple,

vesper,

willow,

stone,

gleam,

meridian,

bossa,

tempo,

beacon,

delta,

cinder

requires_exact_greeting

boolean

Reserved. Live calls may paraphrase first_sentence, and true with mode: live is refused with 400. Legacy calls always speak it word for word.

stt_provider

enum<string>

default:deepgram

Legacy speech recognition engine. Its models, languages and settings are listed in GET /v1/models.

Available options:

deepgram,

gladia,

speechmatics,

soniox

Example:

"deepgram"

stt_model

string

default:nova-3

Legacy speech recognition model from GET /v1/models. Omit it for the engine's default.

Minimum string length: 1

Example:

"nova-3"

stt_language

string

The language a live call starts in, or the one legacy speech recognition listens for (default en-US). Send a code, or a regional variant of one, listed under supported_languages in GET /v1/models and by your stt_model if set; anything else gets 400.

Required string length: 2 - 35

Example:

"en-US"

stt_languages

string[]

Languages the caller may speak; each entry follows the stt_language rule. In live the agent speaks them. In legacy, the speech engine narrows detection to them, takes them as hints or ignores them, depending on the engine.

Required array length: 1 - 10 elements

Required string length: 2 - 35

Example:

["en", "ro"]

stt_vocabulary

(string | object)[]

Words and phrases speech recognition should catch, like product, company or person names. Legacy only, ignored in live, and read only by models with supports_vocabulary: true in GET /v1/models.

Required array length: 1 - 100 elements

Minimum string length: 1

Example:

[
  "Acme",
  { "value": "TopCalls", "language": "en" }
]

stt_endpoint_sensitivity

number

Seconds of silence before the caller's turn ends; lower answers faster. Each engine's range and default are under stt_settings in GET /v1/models. Legacy only, ignored in live and by engines without this setting.

Required range: 0.01 <= x <= 3

Example:

0.01

stt_endpoint_eagerness

number

default:-0.5

How readily the engine decides the caller has finished. Negative waits longer and cuts people off less; positive ends turns sooner. Legacy only, ignored in live and by engines without this setting in GET /v1/models.

Required range: -1 <= x <= 1

Example:

-0.5

stt_interrupt_sensitivity

number

default:0.6

How clearly sound must read as speech before it counts. Higher ignores more background noise; lower catches quiet speech but more noise. Legacy only, ignored in live and by engines without this setting in GET /v1/models.

Required range: 0 <= x <= 1

Example:

0.8

stt_max_delay

number

default:1.5

Longest wait in seconds before a transcript is final. Lower ends turns faster; higher gives slow speakers more room. Legacy only, ignored in live and by engines without this setting in GET /v1/models.

Required range: 0.7 <= x <= 4

Example:

1.5

transcript_correction_vocabulary

(string | object)[]

Legacy only. Terms speech recognition tends to mishear (product names, jargon), so the model reads the caller's meaning from context. Each item is a string or an object with sounds_like hints. The safety review reads it like instructions (a deceptive term gets 422 PROMPT_SAFETY_FRAUD), and a list over 8,000 rendered characters gets 400.

Required array length: 1 - 100 elements

Minimum string length: 1

Example:

[
  "TopCalls",
  {
    "correct": "Weaviate",
    "sounds_like": ["we activate", "web VT"]
  },
  {
    "correct": "Kubernetes",
    "sounds_like": ["cube net ease", "cooper nettie"],
    "context": "technology"
  }
]

tts_provider

enum<string>

default:cartesia

Legacy only, like tts_model: refused with mode: live, and sending it without mode makes the call legacy. Voices per provider are on GET /v1/voices/builtin.

Available options:

elevenlabs,

cartesia

Example:

"cartesia"

tts_model

string

Legacy only (same rule as tts_provider). Models are listed on GET /v1/models; some speak at a fixed pace and ignore tts_speed.

Minimum string length: 1

Example:

"eleven_flash_v2_5"

tts_stability

number

Lower is more expressive, higher is steadier. Default 0.75. Like every tts_* knob below, it's legacy only and ignored unless the selected voice engine lists it on GET /v1/models.

Required range: 0 <= x <= 1

Example:

0.75

tts_similarity_boost

number

How closely the output matches the original voice. Default 0.5.

Required range: 0 <= x <= 1

Example:

0.5

tts_speed

number

Speech rate. Each engine has its own range and default on GET /v1/models, and a value outside it is clamped. Fixed-pace models ignore it.

Required range: 0.6 <= x <= 1.5

Example:

1.15

tts_style

number

Style exaggeration, from 0 (neutral) to 1 (most expressive). Omitted means the engine default.

Required range: 0 <= x <= 1

Example:

0

tts_emotion

string

Baseline emotion, such as enthusiastic, confident or calm. The voice engine validates the value. Omitted means neutral.

Minimum string length: 1

Example:

"enthusiastic"

tts_volume

number

Speech volume. Omitted means the engine default.

Required range: 0.5 <= x <= 2

Example:

1

filler_enabled

boolean

deprecated

Accepted and ignored.

Example:

false

emotion_enabled

boolean

default:false

Lets the agent add inline prosody and interjections to what it says. Legacy only, and ignored unless the voice engine lists expressive markup on GET /v1/models.

Example:

false

block_interruption

boolean

default:false

Keeps the agent talking when the caller speaks over it: speech during the middle of a reply is discarded. The caller can still cut in during a reply's first 1.5 seconds and its last 30%, so short replies aren't blocked. Legacy only, with the same mode rule as tts_provider.

Example:

false

bot_protection_enabled

boolean

default:true

Ends calls answered by an automated or unresponsive line. Legacy only: true is refused with mode: live and makes a call without mode legacy; false is always accepted.

Example:

true

max_duration

integer

default:5

Hard limit on call length, in minutes. The call holds credit for the whole limit while it runs.

Required range: 1 <= x <= 60

background_audio

enum<string>

default:office

Ambient sound looped under the conversation. office is quiet office noise.

Available options:

office,

none

Example:

"office"

background_audio_gain

enum<string>

default:medium

Background volume relative to speech: low is -10 dB, medium -4 dB, high 0 dB.

Available options:

low,

medium,

high

Example:

"medium"

webhook_url

string<uri>

Receives a notification when the call ends or fails, with the recording URL and summary when they exist.

Example:

"https://your-app.com/webhooks/call-complete"

webhook_call_status_filter

string[] | null

Fires webhook_url only when the final call_status is in this list. Omitted, null or empty fires on every outcome. Account webhook subscriptions aren't filtered.

Maximum array length: 20

Minimum string length: 1

Example:

["completed", "failed"]

summary_prompt

string

How to write call_summary on the call and in the webhook. Omitted uses the platform's default summary.

Required string length: 1 - 5000

Example:

"Summarize the objections raised and the agreed callback time."

analysis_schema

object

Fields the model extracts from the transcript after the call. The values come back as analysis on the call and in the webhook. A call_outcome field also sets the call's disposition.

Give each field a type (date is ISO 8601), or a type plus a description to guide the model:

{ "converted": "boolean", "appointment_time": { "type": "date", "description": "Booked slot, if any" } }

Show child attributes

Example:

{
  "converted": {
    "type": "boolean",
    "description": "Whether the lead agreed to schedule an appointment or expressed buying interest"
  },
  "objections": {
    "type": "string",
    "description": "Any concerns or objections the lead raised during the call"
  },
  "appointment_time": {
    "type": "date",
    "description": "The scheduled appointment date and time if one was booked"
  }
}

mcp_url

string<uri>

Accepted and ignored, like mcp_tool_allowlist and tool_call_timeout_ms. A direct call gets no remote tools; tools come from the flows selected on a campaign in Integrations.

Example:

"https://integrations.example.com/mcp/abc123"

mcp_tool_allowlist

string[]

Accepted and ignored.

Example:

["book_callback", "send_sms_confirmation"]

tool_call_timeout_ms

integer

default:8000

Accepted and ignored.

Required range: 500 <= x <= 10000

metadata

object

Your own key-value data, returned on call reads and webhooks. Placeholders like {{name}} never fill from here, and platform keys are dropped: every call setting, name, first_name, last_name, lead_name, company_name, lead_context, attempt_number, campaign_id, lead_id, live, and any key with a reserved prefix such as stt_, tts_, transfer_ or internal. The one key that acts is from_number, which sets the caller ID when the top-level field is absent (same ownership check) and isn't returned.

Example:

{
  "patient_id": "pat_123",
  "source": "reminder_system"
}

lead_id

string<uuid>

Loads the lead's name, email, notes, status and custom fields into lead_context for the agent. 404 if the lead isn't in your account.

campaign_id

string<uuid>

Gives the call that campaign's knowledge base. Nothing else from the campaign applies: not its prompt, voice or other settings. 404 if the campaign isn't in your account.

attempt_number

integer

Stored with the call and returned in its metadata.

Required range: x >= 1

idempotency_key

string

Stored with the call. For safe retries of this request, send the Idempotency-Key header instead.

Minimum string length: 8

scheduled_at

string<date-time>

Dial at this time instead of now. A future time returns status: scheduled, and credit is held only when the call comes due. A past time dials at once.

lead_context

object

Key-value context the agent sees during the call. With lead_id, these keys merge over the lead's own and win on collision. The platform ignores direction, _is_test, _browser_test and _sip_username, here and in lead metadata.

crew

object

Up to five agents share one call and pass it on the conditions you write. Crews work in both modes. A duplicate id, or a handoff to an unknown member or to itself, is refused with 400.

Show child attributes

Response

Accepted. status is queued once dialed, scheduled (with scheduled_at) for a future call, or pending while an identical request is still being placed.

call_id

string<uuid>

Call UUID

Example:

"550e8400-e29b-41d4-a716-446655440000"

provider_call_id

string | null

Telephony call ID. Null while the call is scheduled or pending.

Example:

"64e9bf0e-7c2f-4443-a759-7eb1731cd583"

status

enum<string>

queued: the call is dialing. pending: an identical request is still being set up, so poll GET /v1/calls/{call_id}. scheduled: it dials at scheduled_at. A request for the same number within 5 seconds returns the earlier call.

Available options:

queued,

pending,

scheduled

Example:

"queued"

scheduled_at

string<date-time>

Present when status is scheduled.

Overview

Calls

Phone Numbers

Lead lists

Leads

Campaigns

Knowledge Bases

Webhooks

Configuration

Account

Authorizations

Headers

Body

Response