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/api/v1/outbound-calls
Initiate Outbound Call
Start a new outbound call from your KrosAI phone number to a destination.
Endpoint
POST /outbound-call
Request Body
| string | Yes | Your KrosAI phone number (E.164 format) |
| string | Yes | Destination phone number (E.164 format) |
| string | Yes | The endpoint (AI agent) to handle the call |
| object | No | Custom metadata to attach to the call |
| string | No | Override webhook URL for this call |
| integer | No | Maximum call duration in seconds |
Phone Number Format
All phone numbers must be in E.164 format:
Format | Example | Valid |
E.164 |
| ✅ |
E.164 |
| ✅ |
Local |
| ❌ |
Formatted |
| ❌ |
Note: 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
Possible failure outcomes include failed, no_answer, and busy.
Status Values
| Call request accepted, setting up |
| Destination phone is ringing |
| Destination answered |
| Call is active with AI agent |
| Call ended normally |
| Call failed to connect |
| Destination didn't answer |
| Destination was busy |
Metadata
Attach custom metadata to calls for tracking and analytics:
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, When the limit is reached, the call is automatically terminated.
Error Responses
400 |
| Invalid E.164 format |
400 |
|
|
400 |
| Outbound calls disabled for this number |
400 |
| Not enough credits |
404 |
| Invalid |
429 |
| Too many concurrent calls |
Concurrent Call Limits
Free | 1 |
Pro | 10 |
Business | 15 |
Enterprise | Unlimited |
→ 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.
On this page
- Outbound Calls