API reference
API Reference

REST API

Integrate OutboundCalls.ai into your stack. Manage agents, contacts, campaigns, and calls programmatically.

Base URL:https://api.outboundcalls.ai/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings > API Keys.

Authorization: Bearer YOUR_API_KEY

Never expose your API keys in client-side code. Use environment variables and server-side requests.

Endpoints

Agents

POST/v1/agents
GET/v1/agents
GET/v1/agents/:id
PATCH/v1/agents/:id
DELETE/v1/agents/:id

Contacts

POST/v1/contacts
POST/v1/contacts/import
GET/v1/contacts
PATCH/v1/contacts/:id
DELETE/v1/contacts/:id

Campaigns

POST/v1/campaigns
GET/v1/campaigns
GET/v1/campaigns/:id
POST/v1/campaigns/:id/start
POST/v1/campaigns/:id/pause
POST/v1/campaigns/:id/resume

Calls

GET/v1/calls
GET/v1/calls/:id
GET/v1/calls/:id/recording
GET/v1/calls/:id/transcript

Credits

GET/v1/credits/balance
GET/v1/credits/usage
POST/v1/credits/purchase

Code Examples

cURL
curl -X POST https://api.outboundcalls.ai/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Sales Outreach",
    "agent_id": "agent_abc123",
    "contact_list_id": "list_xyz789",
    "schedule": {
      "start_date": "2026-03-25",
      "calling_hours": {"start": "09:00", "end": "18:00"},
      "timezone": "Europe/London"
    },
    "retry_rules": {
      "max_attempts": 3,
      "delay_minutes": 60
    },
    "concurrent_calls": 20
  }'
JavaScript / Node.js
const response = await fetch('https://api.outboundcalls.ai/v1/campaigns', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Q1 Sales Outreach',
    agent_id: 'agent_abc123',
    contact_list_id: 'list_xyz789',
    schedule: {
      start_date: '2026-03-25',
      calling_hours: { start: '09:00', end: '18:00' },
      timezone: 'Europe/London',
    },
    retry_rules: {
      max_attempts: 3,
      delay_minutes: 60,
    },
    concurrent_calls: 20,
  }),
});

const campaign = await response.json();
console.log(campaign.id); // "camp_def456"

Webhooks

Receive real-time notifications for call events. Configure webhook URLs in your dashboard under Settings > Webhooks. All payloads are signed with HMAC-SHA256 for verification.

call.startedFired when a call connects to the recipient
call.completedFired when a call ends, includes transcript and outcome
call.failedFired when a call fails to connect
campaign.completedFired when all contacts in a campaign have been called
contact.updatedFired when a contact status changes after a call
credits.lowFired when credit balance drops below threshold

Rate Limits

TierRequestsConcurrentBurst
Standard100 req/min10 concurrent20 req/sec
Professional500 req/min50 concurrent50 req/sec
EnterpriseUnlimitedCustomCustom

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Ready to integrate?

Generate your API key and start building in minutes.

Get Your API Key