Calls API Overview

The Calls API provides comprehensive endpoints for managing voice call interactions with your AI agents. Schedule calls, initiate outbound calls, manage call queues, and retrieve call details and history.

Base URL

https://v2.heppu.ai/api/v1

Authentication

All Calls API endpoints require authentication using an API key. Include your API key in the request headers:

x-api-key: YOUR_API_KEY

Or using Bearer token:

Authorization: Bearer YOUR_API_KEY

Available Endpoints

List Calls

GET /api/v1/calls - Retrieve a paginated list of calls with filtering and sorting

Get Call Details

GET /api/v1/calls/{callId} - Get detailed information about a specific call

Cancel Call

DELETE /api/v1/calls/{callId} - Cancel an active or scheduled call

Schedule Call

POST /api/v1/calls/schedule - Schedule a single outbound call

Batch Schedule

POST /api/v1/calls/batch - Schedule up to 1,000 calls at once

Outbound Call

POST /api/v1/calls/outbound - Initiate an immediate outbound call via LiveKit

Common Features

Phone Number Format

All phone numbers must be in E.164 format:

+[country_code][subscriber_number]

Examples:

US: +14155552671
UK: +442071838750
AU: +61291234567

Call Status Values

Calls can have the following status values:

initiated - Call has been created but not yet started
scheduled - Call is scheduled for a future time
connecting - Call is being established
ringing - Phone is ringing
active - Call is in progress
completed - Call finished successfully
failed - Call failed to connect or complete
cancelled - Call was cancelled before completion
no_answer - Call was not answered
busy - Line was busy

Call Direction

inbound - Incoming call to your agent
outbound - Outgoing call from your agent

Priority Levels

Priority is an integer from 0 to 10:

0-3: High priority
4-6: Normal priority (default: 5)
7-10: Low priority

Error Handling

All endpoints return errors in a consistent format:

{
  "error": {
    "message": "Error description",
    "code": 400
  }
}

Common HTTP status codes:

200 - Success
201 - Created
207 - Multi-status (partial success in batch operations)
400 - Bad request (invalid parameters)
401 - Unauthorized (invalid or missing API key)
403 - Forbidden (insufficient permissions)
404 - Not found
500 - Internal server error

Rate Limiting

API requests are subject to rate limiting:

Standard tier: 60 requests per minute
Premium tier: 300 requests per minute
Enterprise tier: Custom limits

When rate limited, you'll receive a 429 status code with a Retry-After header.

Quick Start Examples

Schedule a Call

curl -X POST https://v2.heppu.ai/api/v1/calls/schedule \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-uuid",
    "contactPhone": "+14155552671",
    "contactName": "John Doe",
    "scheduledAt": "2025-12-02T14:00:00Z"
  }'

List Recent Calls

curl -X GET "https://v2.heppu.ai/api/v1/calls?limit=10&sortOrder=desc" \
  -H "x-api-key: YOUR_API_KEY"

Initiate Immediate Outbound Call

curl -X POST https://v2.heppu.ai/api/v1/calls/outbound \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent-uuid",
    "phoneNumber": "+14155552671",
    "priority": 5
  }'

Integration Guides

The Calls API is compatible with:

Make.com - Use webhooks and HTTP modules
Zapier - Custom API integration
n8n - HTTP Request nodes
Custom applications - Any HTTP client

Next Steps

Explore the individual endpoint documentation to learn about specific features, request/response formats, and advanced options:

List Calls - Query and filter call history
Get Call Details - Retrieve complete call information
Cancel Call - Stop active or scheduled calls
Schedule Call - Schedule individual calls with metadata
Batch Schedule - Bulk scheduling with timezone awareness
Outbound Call - Immediate call initiation