Outbound calls

Outbound calls are calls initiated by your KolaVoice account. Use a direct call when you need to contact one person immediately, or use a campaign when you need to call a list of contacts with instructions, retries, outcomes, and follow-ups.

Requirements

A valid KolaVoice API key
An agent in the account
An active outbound-enabled number, or access to the system default outbound number
Enough wallet balance to start the call or campaign

Direct calls

Create a call

POST /outbound/calls

Launches one outbound AI phone call immediately.

curl -X POST "https://cloud.kolavoice.com/api/v1/outbound/calls" \
  -H "X-API-Key: kva_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number": "+256782435630",
    "agent_id": "836ca07f-98ad-47ec-bfc6-afd457fa2b16",
    "from_number": "+256323200643"
  }'

{
  "call_id": "ec40a1f1-0b15-408b-a6f4-79314c0b89f9",
  "room_name": "call-836ca07f-1783580857-94e4c116",
  "status": "dialing",
  "to_number": "+256782435630",
  "agent": "General Outbound Agent"
}

Check a call

GET /outbound/calls/{call_id}

curl "https://cloud.kolavoice.com/api/v1/outbound/calls/ec40a1f1-0b15-408b-a6f4-79314c0b89f9" \
  -H "X-API-Key: kva_live_xxxxxxxxxxxx_xxxxxxxxxxxxxxxxx"

The response includes status, duration, transcript, summary, recording URL, cost, and ended reason when available.

Campaign calls

Campaigns are outbound calls to multiple contacts. The campaign request creates the campaign and its contacts in one operation.

Create a campaign

POST /campaigns

curl -X POST https://cloud.kolavoice.com/api/v1/campaigns \
  -H "X-API-Key: kva_live_your_key" \
  -H "Idempotency-Key: campaign-2026-08-12-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "School fee reminders",
    "instructions": "Call on behalf of Valley School. Explain the outstanding balance respectfully and capture a payment promise or callback time.",
    "agent_id": "agent-id",
    "phone_number_id": "phone-number-id",
    "timezone": "Africa/Nairobi",
    "contacts": [
      {"customer_name": "Maria Modesta", "phone_number": "256782435630", "metadata": {"balance": "120000"}}
    ],
    "max_attempts": 3,
    "concurrent_calls": 2,
    "allow_followups": true,
    "max_followups_per_contact": 2
  }'

Contacts can include campaign-specific metadata such as balance, due date, location, event, or customer status. The agent receives the contact context together with the campaign instructions.

Campaign operations

Method	Endpoint	Scope
`GET`	`/campaigns`	`campaigns:read`
`GET`	`/campaigns/{id}`	`campaigns:read`
`POST`	`/campaigns/{id}/action/start`	`campaigns:write`
`POST`	`/campaigns/{id}/action/pause`	`campaigns:write`
`POST`	`/campaigns/{id}/action/resume`	`campaigns:write`
`POST`	`/campaigns/{id}/action/stop`	`campaigns:write`
`GET`	`/campaigns/{id}/contacts`	`campaigns:read`

Contact results include status, outcome, summary, attempt count, next attempt time, and follow-up status.

Idempotency

Use a unique Idempotency-Key on POST /outbound/calls and POST /campaigns. Repeating the same request with the same key returns the original response and does not create a duplicate call or campaign. Keys are retained for 24 hours.

Common errors

Status	Meaning
`400`	Invalid number, missing required field, or invalid request
`401`	Invalid or missing API key
`402`	Wallet balance is too low
`404`	Agent, number, call, or campaign not found
`503`	Calling is under maintenance

Overview

Dashboard Guides

API Reference

Requirements

Direct calls

Create a call

Check a call

Campaign calls

Create a campaign

Campaign operations

Idempotency

Common errors

​Requirements

​Direct calls

​Create a call

​Check a call

​Campaign calls

​Create a campaign

​Campaign operations

​Idempotency

​Common errors

Requirements

Direct calls

Create a call

Check a call

Campaign calls

Create a campaign

Campaign operations

Idempotency

Common errors