Outbound Calls

The Outbound Calls API allows you to programmatically initiate phone calls from your AI agents to any phone number.

Base URL: https://api.krosai.com/v1/outbound-calls

Initiate Outbound Call

Start a new outbound call from your KrosAI phone number to a destination.

POST /outbound-calls

Request Body

Field	Type	Required	Description
from_number	string	Yes	Your KrosAI phone number (E.164 format)
to_number	string	Yes	Destination phone number (E.164 format)
endpoint_id	string	Yes	The endpoint (AI agent) to handle the call
metadata	object	No	Custom metadata to attach to the call
webhook_url	string	No	Override webhook URL for this call
max_duration	integer	No	Maximum call duration in seconds

Request

curl

curl -X POST "https://api.krosai.com/v1/outbound-calls" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "[phone]",
    "to_number": "[phone]",
    "endpoint_id": "ep_abc123",
    "metadata": {
      "customer_id": "cust_xyz",
      "campaign": "follow-up-q1"
    }
  }'

Response

response.json

{
  "call_id": "call_xyz789",
  "status": "initiated",
  "from_number": "[phone]",
  "to_number": "[phone]",
  "endpoint_id": "ep_abc123",
  "created_at": "2025-01-10T12:00:00Z"
}

Phone Number Format

All phone numbers must be in E.164 format:

Format	Example	Valid
E.164	[phone]	✅
E.164	[phone]	✅
Local	08012345678	❌
Formatted	[phone]	❌

The from_number must be a phone number owned by your organization.

Call Lifecycle

When you initiate an outbound call, it goes through these stages:

initiated → ringing → answered → in_progress → completed ↓ ↓ failed failed/no_answer

Status Values

Status	Description
initiated	Call request accepted, setting up
ringing	Destination phone is ringing
answered	Destination answered
in_progress	Call is active with AI agent
completed	Call ended normally
failed	Call failed to connect
no_answer	Destination didn't answer
busy	Destination was busy

Metadata

Attach custom metadata to calls for tracking and analytics:

metadata.json

{
  "from_number": "[phone]",
  "to_number": "[phone]",
  "endpoint_id": "ep_abc123",
  "metadata": {
    "customer_id": "cust_123",
    "campaign_id": "camp_456",
    "lead_source": "website",
    "custom_field": "any value"
  }
}

Metadata is:

• Included in webhook payloads

• Searchable in call logs

• Available in analytics exports

Maximum Duration

Set a maximum call duration to prevent unexpectedly long calls:

max_duration.json

{
  "from_number": "[phone]",
  "to_number": "[phone]",
  "endpoint_id": "ep_abc123",
  "max_duration": 600
}

When the limit is reached, the call is automatically terminated.

Error Responses

Status	Code	Description
400	INVALID_PHONE_NUMBER	Invalid E.164 format
400	NUMBER_NOT_OWNED	from_number not in your inventory
400	OUTBOUND_DISABLED	Outbound calls disabled for this number
400	INSUFFICIENT_BALANCE	Not enough credits
404	ENDPOINT_NOT_FOUND	Invalid endpoint_id
429	RATE_LIMIT_EXCEEDED	Too many concurrent calls

Error Response Format

error.json

{
  "error": "Phone number format is invalid. Use E.164 format ([phone])",
  "code": "INVALID_PHONE_NUMBER",
  "details": {
    "field": "to_number",
    "value": "4155551234"
  }
}

Concurrent Call Limits

Plan	Concurrent Outbound Calls
Free	1
Pro	10
Business	50
Enterprise	Unlimited

Code Examples

TypeScript

outbound.ts

interface OutboundCallOptions {
  fromNumber: string;
  toNumber: string;
  endpointId: string;
  metadata?: Record<string, string>;
  maxDuration?: number;
}

async function initiateOutboundCall(options: OutboundCallOptions) {
  const response = await fetch('https://api.krosai.com/v1/outbound-calls', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.KROSAI_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      from_number: options.fromNumber,
      to_number: options.toNumber,
      endpoint_id: options.endpointId,
      metadata: options.metadata,
      max_duration: options.maxDuration,
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Call failed: ${error.code} - ${error.error}`);
  }

  return response.json();
}

// Usage
const call = await initiateOutboundCall({
  fromNumber: '[phone]',
  toNumber: '[phone]',
  endpointId: 'ep_abc123',
  metadata: {
    customer_id: 'cust_123',
    campaign: 'welcome-series',
  },
  maxDuration: 300, // 5 minutes max
});

console.log(`Call initiated: ${call.call_id}`);

Python

Batch (TypeScript)

Webhook Integration

Receive real-time updates about your outbound calls:

webhook-event.json

{
  "event": "call.completed",
  "call_id": "call_xyz789",
  "direction": "outbound",
  "from_number": "[phone]",
  "to_number": "[phone]",
  "duration": 180,
  "cost_cents": 12,
  "metadata": {
    "customer_id": "cust_123"
  }
}

→ Set up Webhooks

Best Practices

Do's ✅

• Validate phone numbers before calling

• Use metadata to track campaign performance

• Set max_duration to prevent runaway calls

• Handle errors gracefully

• Respect rate limits in batch operations

• Test with small batches first

Don'ts ❌

• Don't hardcode phone numbers in source code

• Don't exceed concurrent limits — queue calls instead

• Don't ignore webhook failures — implement retries

• Don't call without consent — follow local regulations

Compliance Notes

When making outbound calls, ensure compliance with:

• TCPA (US) - Prior consent required

• GDPR (EU) - Data protection requirements

• Local regulations - Check destination country laws

KrosAI provides the infrastructure; you're responsible for compliance.