POST
/
api
/
v1
/
calls

​
Initiate Call

Initiate an outbound call from an AI agent to a specified phone number.

​
Endpoint

POST /api/v1/calls

​
Authentication

This endpoint requires an API key with the can_initiate_calls permission.

​
Request Body

ParameterTypeRequiredDescription
phone_numberstringYesThe phone number to call in E.164 format (e.g., +15551234567)
agent_idstring/integerYesThe ID of the AI agent to use (can be database ID or assistant_id)
contact_idintegerNoThe ID of an existing contact (if known)
variablesobjectNoContext variables to be used in the call

​
Example Request Body

{
  "phone_number": "+15551234567",
  "agent_id": 123,
  "contact_id": 456,
  "variables": {
    "customer_name": "John Doe",
    "appointment_time": "3:30 PM tomorrow",
    "custom_context": {
      "previous_purchase": "Premium Plan",
      "account_status": "Active"
    }
  }
}

​
Response

{
  "id": 789,
  "call_id": "klen_call_id",
  "status": "queued",
  "type": "outbound",
  "phone_number": "+15551234567",
  "agent": {
    "id": 123,
    "name": "Appointment Scheduler",
    "assistant_id": "assistant_abc123"
  },
  "created_at": "2025-04-24T10:15:30Z",
  "estimated_start": "2025-04-24T10:15:35Z"
}

​
Error Codes

Status CodeError CodeDescription
400missing_phone_numberPhone number is required
400missing_agent_idAgent ID is required
400invalid_phone_numberThe provided phone number is not valid
400invalid_jsonInvalid JSON payload
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
402insufficient_fundsInsufficient funds to make call
403permission_deniedThe API key doesn’t have the required permission
403do_not_callThe phone number is on your Do Not Call list
404agent_not_foundAI agent not found or you do not have access
404no_phone_numberThe agent does not have an assigned phone number
500server_errorAn unexpected server error occurred

​
Example Request

curl -X POST 'https://api.klen.ai/api/v1/calls' \
  -H 'Authorization: Bearer klen_abcdef123456789' \
  -H 'Content-Type: application/json' \
  -d '{
    "phone_number": "+15551234567",
    "agent_id": 123,
    "variables": {
      "customer_name": "John Doe",
      "appointment_time": "3:30 PM tomorrow"
    }
  }'

​
Example Response

{
  "id": 789,
  "call_id": "call_def456",
  "status": "queued",
  "type": "outbound",
  "phone_number": "+15551234567",
  "agent": {
    "id": 123,
    "name": "Appointment Scheduler",
    "assistant_id": "assistant_abc123"
  },
  "created_at": "2025-04-24T10:15:30Z",
  "estimated_start": "2025-04-24T10:15:35Z"
}

​
Wallet Balance Requirements

This endpoint requires that your account has sufficient wallet balance to initiate a call. If your balance is insufficient, you’ll receive a 402 Payment Required response with details about your current balance and the required rate.

​
Phone Number Validation

The API validates phone numbers to ensure they’re in a proper format. We recommend using the E.164 format (e.g., +15551234567) for all phone numbers.

​
Context Variables

You can provide context variables to the agent for personalized conversations. These variables can be referenced in the agent’s instructions using the {{variable_name}} syntax.

Common variable uses:

  • Customer information (customer_name, company, etc.)
  • Appointment details (appointment_time, appointment_type, etc.)
  • Custom context for specific business needs