Initiate Call

Initiate a call with an AI agent to a specified phone number

POST /api/v1/calls

Initiate Call

cURL

curl --request POST \
  --url https://api.example.com/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

Parameter	Type	Required	Description
phone_number	string	Yes	The phone number to call in E.164 format (e.g., [phone])
agent_id	string/integer	Yes	The ID of the AI agent to use (can be database ID or assistant_id)
contact_id	integer	No	The ID of an existing contact (if known)
variables	object	No	Context variables to be used in the call

Example Request Body

{
  "phone_number": "[phone]",
  "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": "[phone]",
  "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 Code	Error Code	Description
400	missing_phone_number	Phone number is required
400	missing_agent_id	Agent ID is required
400	invalid_phone_number	The provided phone number is not valid
400	invalid_json	Invalid JSON payload
401	authentication_required	No API key was provided
401	invalid_key	The API key is invalid or inactive
402	insufficient_funds	Insufficient funds to make call
403	permission_denied	The API key doesn’t have the required permission
403	do_not_call	The phone number is on your Do Not Call list
404	agent_not_found	AI agent not found or you do not have access
404	no_phone_number	The agent does not have an assigned phone number
500	server_error	An 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": "[phone]",
    "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": "[phone]",
  "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., [phone]) 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