Campaigns

Campaigns are the primary unit of work in Akol. A campaign owns its calls, contacts, stats, and one or more phone numbers, and references one Agent (voice persona).

List campaigns

GET /api/v1/campaigns?status=RUNNING&page=1&limit=20

Filters:

• status — DRAFT | SCHEDULED | RUNNING | PAUSED | COMPLETED | FAILED
• agentId — filter to campaigns using a specific agent

Create a campaign

POST /api/v1/campaigns
Content-Type: application/json
 
{
  "name": "Q2 follow-up calls",
  "agentId": "agt_xxx",
  "businessId": "biz_xxx",
  "phoneNumberIds": ["pn_xxx"],
  "status": "DRAFT"
}

businessId carries all the agent behavior (system prompt, services, hours, business context). The agent only contributes voice + name.

Start / pause / resume

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

State transitions are validated server-side. Trying to start a COMPLETED campaign returns 409 Conflict.

Add contacts

POST /api/v1/campaigns/:id/contacts
Content-Type: application/json
 
{
  "contacts": [
    { "phoneNumber": "+15551234567", "name": "Alice", "email": "alice@example.com" },
    { "phoneNumber": "+15557654321", "name": "Bob" }
  ]
}

Bulk endpoint — accepts up to 1000 contacts per request. Phone numbers must be E.164. Duplicates within the campaign are de-duped (returns the existing contact ID).

Get campaign stats

GET /api/v1/campaigns/:id/stats

Returns:

{
  "success": true,
  "data": {
    "totalContacts": 1000,
    "completedCalls": 743,
    "successfulCalls": 612,
    "failedCalls": 131,
    "voicemails": 88,
    "averageCallDuration": 145,
    "totalMinutes": 1798
  }
}

Get calls for a campaign

GET /api/v1/campaigns/:id/calls?page=1&limit=20

Returns the same shape as /api/v1/calls but pre-filtered to this campaign.