API Reference

Complete REST API documentation for authentication and call management

Calls API

Manage voice calls through the Kalem.me API. Create, retrieve, and control your automated voice interactions.

Quick Reference

Base Endpoint

https://api.kalem.me/v1/calls

Supported Formats

JSON only

List Calls

Retrieve a paginated list of your calls with optional filtering.

GET /api/v1/calls

Example Request

curl -X GET "https://api.kalem.me/v1/calls?limit=10&status=completed" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": "call_abc123",
      "phone_number": "+1234567890",
      "agent_id": "agent_xyz789",
      "status": "completed",
      "duration": 120,
      "started_at": "2025-01-15T14:30:00Z",
      "ended_at": "2025-01-15T14:32:00Z",
      "outcome": "interested"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_items": 47,
    "per_page": 10
  }
}

Create Call

Initiate a new voice call with your configured AI agent.

POST /api/v1/calls

Example Request

curl -X POST "https://api.kalem.me/v1/calls" \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+1234567890",
    "agent_id": "agent_abc123",
    "metadata": {
      "campaign_id": "camp_123",
      "customer_id": "cust_456"
    }
  }'

Example Response

{
  "id": "call_def456",
  "phone_number": "+1234567890",
  "agent_id": "agent_abc123",
  "status": "queued",
  "created_at": "2025-01-15T15:30:00Z",
  "metadata": {
    "campaign_id": "camp_123",
    "customer_id": "cust_456"
  }
}

Get Call Details

Retrieve detailed information about a specific call.

GET /api/v1/calls/{call_id}

Example Request

curl -X GET "https://api.kalem.me/v1/calls/call_abc123" \
  -H "Authorization: Bearer your_api_token" \
  -H "Accept: application/json"

Call Status Reference

Understanding call status values and their meanings.

Status	Description
queued	Call is waiting to be initiated
ringing	Call is being placed, phone is ringing
in_progress	Call is active and in conversation
completed	Call ended successfully
failed	Call failed to connect
cancelled	Call was cancelled before completion