Making Calls

Your First Call

The simplest call needs a destination number and a task:

curl -X POST https://api.topcalls.ai/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "from_number": "+18005551234",
    "task": "You are calling to confirm the dental appointment for John tomorrow at 3 PM. Be friendly and professional."
  }'

from_number must be one of your own numbers; leave it out to call from the default number. Every call needs task (a short brief) or instructions (full control), at least 10 characters.

Complete Example: Appointment Reminder

{
  "phone_number": "+14155551234",
  "from_number": "+18005551234",
  "instructions": "You are Rachel, a friendly appointment coordinator at Bright Dental. Confirm the patient's appointment for tomorrow at 3 PM. Be warm and brief.",
  "first_sentence": "Hi {{name}}, this is Rachel from Bright Dental. I'm calling to confirm your appointment tomorrow at {{appointment_time}}.",
  "live_voice": "marin",
  "max_duration": 5,
  "lead_context": {
    "name": "John Smith",
    "appointment_time": "3:00 PM"
  },
  "webhook_url": "https://your-app.com/webhooks/call-complete"
}

Optional Parameters

Voice and Mode

Live (the default) runs one voice model that listens and speaks. Legacy chains speech recognition, a language model and a voice you pick. A call without mode runs Legacy if it sets voice, model or a Legacy-only field such as stt_provider. See the Voice Library for voices and GET /v1/models for models.

Opening and Length

Without first_sentence, no scripted opening plays. Legacy speaks it word for word; Live may reword it slightly. max_duration caps the call in minutes (default 5). Office ambience plays underneath unless background_audio is none.

Lead Context

Placeholders such as {{name}} fill from lead_context in first_sentence only. In task or instructions they stay as written, so put per-lead facts in the lead’s name and notes, which the model reads. lead_id loads a stored lead, and keys you also send in lead_context override it. campaign_id adds that campaign’s knowledge base and nothing else.

Webhooks and Summaries

webhook_url gets one payload when the call ends, limited to the call_status values in webhook_call_status_filter if you set it. For account-wide delivery, use webhook subscriptions. Each finished call carries a written summary; summary_prompt changes what it covers.

More Options

Also available: analysis_schema for structured extraction, scheduled_at to call later, and an Idempotency-Key header for safe retries. temperature, bot_protection_enabled and the speech and voice tuning fields apply to Legacy only. The API reference lists every field.

Response

{
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "provider_call_id": "64e9bf0e-7c2f-4443-a759-7eb1731cd583",
  "status": "queued"
}

A scheduled call answers scheduled plus scheduled_at. pending means it’s still being admitted. Sending the same phone_number again within 5 seconds returns the first call instead of placing another.

Call Status

curl https://api.topcalls.ai/v1/calls/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

Status	Meaning
`pending`	Created, not yet queued
`queued`	Waiting to dial
`in_progress`	On the line
`completed`	Finished
`failed`	Busy, no answer or error
`cancelled`	Cancelled

How Calls End

The agent hangs up when the caller wraps up, asks to stop, or asks not to be contacted again. It won’t end the call over a pause, and it says a short goodbye first. Shape this in your instructions, for example: “Confirm the next step before you say goodbye.” Silence works the same in Live and Legacy. After about 7 seconds with nothing from the caller, the agent checks in. If 7 more seconds pass in silence, the call hangs up with no goodbye.

Calling in Another Language

{
  "phone_number": "+14155551234",
  "instructions": "Habla solo en español. Eres un asistente de servicio al cliente...",
  "mode": "legacy",
  "stt_language": "es-ES",
  "voice": "your-spanish-voice-id"
}

stt_language must be a code GET /v1/models lists, or a regional form of one. Anything else gets a 400.

Error Handling

Invalid Phone Number

{
  "status": 400,
  "title": "Invalid request body",
  "errors": [
    {
      "path": "phone_number",
      "message": "Phone number must be in E.164 format (e.g., +14155551234)",
      "code": "invalid_string"
    }
  ]
}

Insufficient Quota

Your credit wallet can’t cover the call’s max_duration. Calls in progress hold theirs until they end, so add credit or wait for one to finish.

{
  "status": 402,
  "title": "Insufficient Quota",
  "code": "insufficient_quota",
  "detail": "Not enough credit to place this call. Add credit in Billing.",
  "available": 0,
  "requested": 10
}

Every Concurrent-Call Slot in Use

With every concurrent-call slot busy, a new call gets a 429 and nothing is created. The per-minute rate limit also answers 429, but with code: RATE_LIMITED and a Retry-After header. A scheduled call is never refused for concurrency; it waits for a free slot.

{
  "type": "https://api.topcalls.ai/errors/concurrency_limit",
  "title": "Concurrency Limit Reached",
  "status": 429,
  "code": "concurrency_limit",
  "detail": "Every concurrent-call slot on this account is in use. Place the call again once a call in progress ends."
}

Other Refusals

Status	`code`	Cause
`404`		`lead_id` or `campaign_id` isn’t on your account
`422`	`from_number_not_owned`	`from_number` isn’t one of your numbers
`422`	`destination_not_allowed`	Calls to that destination aren’t enabled for your account
`422`	varies	The prompt safety review refused the instructions
`503`	`destination_policy_unavailable`	The destination check is down. Retry shortly

None of these places a call or holds credit.

Keep instructions focused (200 to 500 words is plenty), and call your own number before you call real leads.

Next Steps

Function Calling

Let the agent act in your systems during a call.

Webhooks

Receive real-time notifications when calls complete.

Credit and Billing

What calls cost, and how a call reserves credit while it runs.

Getting Started

Core Concepts

Guides

Use Cases

Integrations

Your First Call

Complete Example: Appointment Reminder

Optional Parameters

Voice and Mode

Opening and Length

Lead Context

Webhooks and Summaries

More Options

Response

Call Status

How Calls End

Calling in Another Language

Error Handling

Invalid Phone Number

Insufficient Quota

Every Concurrent-Call Slot in Use

Other Refusals

Next Steps

Function Calling

Webhooks

Credit and Billing

​Your First Call

​Complete Example: Appointment Reminder

​Optional Parameters

​Voice and Mode

​Opening and Length

​Lead Context

​Webhooks and Summaries

​More Options

​Response

​Call Status

​How Calls End

​Calling in Another Language

​Error Handling

​Invalid Phone Number

​Insufficient Quota

​Every Concurrent-Call Slot in Use

​Other Refusals

​Next Steps

Function Calling

Webhooks

Credit and Billing

Your First Call

Complete Example: Appointment Reminder

Optional Parameters

Voice and Mode

Opening and Length

Lead Context

Webhooks and Summaries

More Options

Response

Call Status

How Calls End

Calling in Another Language

Error Handling

Invalid Phone Number

Insufficient Quota

Every Concurrent-Call Slot in Use

Other Refusals

Next Steps