API Reference

Integrate KestrelVoice into your applications

Authentication

All API requests require authentication using an API key. You can generate API keys from your dashboard.

curl https://api.kestrelvoice.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Getting Your API Key

Navigate to Settings → API Keys in your dashboard
Click "Generate New API Key"
Give your key a descriptive name (e.g., "Production Server")
Copy the key immediately - it won't be shown again
Store it securely (use environment variables, never commit to git)

Base URL

https://api.kestrelvoice.com/v1

All API endpoints are relative to this base URL. The API uses RESTful conventions and returns JSON responses.

API Endpoints

GET

/calls

Retrieve a list of calls for your account.

Query Parameters

limit	Number of results (default: 20, max: 100)
offset	Pagination offset
status	Filter by status: completed, in-progress, missed
from_date	ISO 8601 date (e.g., 2024-01-01)

Example Response

{
  "data": [
    {
      "id": "call_abc123",
      "phone_number": "+15551234567",
      "status": "completed",
      "duration": 180,
      "recording_url": "https://...",
      "transcript": "Hello, this is...",
      "created_at": "2024-03-09T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

GET

/calls/:id

Retrieve details for a specific call.

Example Request

GET /v1/calls/call_abc123

GET

/appointments

Retrieve appointments booked through your AI agent.

Query Parameters

status	scheduled, completed, cancelled
from_date	Filter appointments from this date
to_date	Filter appointments until this date

GET

/analytics

Retrieve analytics data for your account.

Available Metrics

Total calls (by day, week, month)
Appointment booking rate
Average call duration
Emergency call detection rate
Missed call recovery

Webhooks

Receive real-time notifications when events occur in your account.

Available Events

call.completed

Triggered when a call ends

appointment.booked

Triggered when an appointment is scheduled

emergency.detected

Triggered when emergency keywords are detected

call.missed

Triggered when a call is not answered

Example Webhook Payload

{
  "event": "call.completed",
  "timestamp": "2024-03-09T10:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "phone_number": "+15551234567",
    "duration": 180,
    "outcome": "appointment_booked",
    "transcript": "...",
    "recording_url": "https://..."
  }
}

Webhook Security

All webhook requests include a signature header for verification:

X-Kestrel-Signature

Verify this signature using your webhook secret to ensure requests are from KestrelVoice.

Rate Limits

Plan	Rate Limit
Personal	100 requests/minute
Business	500 requests/minute
Business Plus	1000 requests/minute

Rate limit headers are included in all API responses. Contact support for higher limits.

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Contact support

Need API Support?

Our developer team is here to help with your integration

Contact Support