Skip to main content

​
Overview

The Campaigns API allows you to create, launch, and monitor outbound calling campaigns programmatically.

​
List Campaigns

Get all campaigns in your account. 
curl -X GET "https://api.getsmartalex.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDescription
statusstringFilter by status: draft, active, paused, completed
agent_idstringFilter by assigned agent
pageintegerPage number (default: 1)
per_pageintegerItems per page (default: 20)

​
Response

{
  "data": [
    {
      "id": "campaign_abc123",
      "name": "January Outreach",
      "agent_id": "agent_def456",
      "status": "active",
      "contacts_total": 500,
      "contacts_called": 234,
      "contacts_remaining": 266,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 20
  }
}

​
Get Campaign

Retrieve a single campaign with detailed statistics. 
curl -X GET "https://api.getsmartalex.com/v1/campaigns/campaign_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "campaign_abc123",
    "name": "January Outreach",
    "description": "Q1 lead generation campaign",
    "agent_id": "agent_def456",
    "status": "active",
    "contacts_total": 500,
    "contacts_called": 234,
    "contacts_remaining": 266,
    "contacts_connected": 156,
    "contacts_voicemail": 45,
    "contacts_failed": 33,
    "settings": {
      "calling_hours_start": "09:00",
      "calling_hours_end": "17:00",
      "timezone": "America/New_York",
      "concurrent_calls": 3
    },
    "stats": {
      "connect_rate": 0.667,
      "average_duration": 145,
      "total_cost": 12.50,
      "sentiment": {
        "positive": 89,
        "neutral": 52,
        "negative": 15
      }
    },
    "created_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T11:00:00Z"
  }
}

​
Create Campaign

Create a new outbound calling campaign. 
curl -X POST "https://api.getsmartalex.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "February Outreach",
    "description": "Follow-up campaign",
    "agent_id": "agent_def456",
    "settings": {
      "calling_hours_start": "10:00",
      "calling_hours_end": "16:00",
      "timezone": "America/New_York",
      "concurrent_calls": 2
    }
  }'

​
Parameters

ParameterTypeRequiredDescription
namestringYesCampaign name
descriptionstringNoCampaign description
agent_idstringYesAgent to make calls
settingsobjectNoCampaign configuration

​
Settings Object

FieldTypeDefaultDescription
calling_hours_startstring”09:00”Start time (HH:MM)
calling_hours_endstring”17:00”End time (HH:MM)
timezonestring”UTC”IANA timezone
concurrent_callsinteger1Simultaneous calls
max_retriesinteger3Retry attempts per contact

​
Response

{
  "data": {
    "id": "campaign_new789",
    "name": "February Outreach",
    "status": "draft",
    "contacts_total": 0,
    "created_at": "2024-01-16T09:00:00Z"
  }
}

​
Add Contacts to Campaign

Add contacts to a campaign for calling. 
curl -X POST "https://api.getsmartalex.com/v1/campaigns/campaign_abc123/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "phone": "+15551234567",
        "first_name": "John",
        "last_name": "Smith",
        "email": "john@example.com"
      },
      {
        "phone": "+15559876543",
        "first_name": "Jane",
        "last_name": "Doe"
      }
    ]
  }'

​
Parameters

ParameterTypeRequiredDescription
contactsarrayYesArray of contact objects
contacts[].phonestringYesPhone number (E.164 format)
contacts[].first_namestringNoFirst name
contacts[].last_namestringNoLast name
contacts[].emailstringNoEmail address
contacts[].companystringNoCompany name

​
Response

{
  "data": {
    "added": 2,
    "duplicates_skipped": 0,
    "invalid_skipped": 0,
    "campaign_total": 502
  }
}

​
Start Campaign

Start a campaign to begin making calls. 
curl -X POST "https://api.getsmartalex.com/v1/campaigns/campaign_abc123/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "campaign_abc123",
    "status": "active",
    "started_at": "2024-01-16T10:00:00Z"
  }
}

​
Pause Campaign

Pause an active campaign. 
curl -X POST "https://api.getsmartalex.com/v1/campaigns/campaign_abc123/pause" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "campaign_abc123",
    "status": "paused",
    "paused_at": "2024-01-16T14:30:00Z"
  }
}

​
Resume Campaign

Resume a paused campaign. 
curl -X POST "https://api.getsmartalex.com/v1/campaigns/campaign_abc123/resume" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "campaign_abc123",
    "status": "active",
    "resumed_at": "2024-01-16T15:00:00Z"
  }
}

​
Get Campaign Callbacks

Get pending callbacks for a campaign. 
curl -X GET "https://api.getsmartalex.com/v1/campaigns/campaign_abc123/callbacks" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": [
    {
      "id": "callback_xyz789",
      "contact": {
        "phone": "+15551234567",
        "first_name": "John"
      },
      "reason": "no_answer",
      "retry_count": 1,
      "scheduled_at": "2024-01-17T10:00:00Z"
    }
  ],
  "meta": {
    "total": 45,
    "page": 1,
    "per_page": 20
  }
}

​
Campaign Status

StatusDescription
draftCreated but not started
activeCurrently making calls
pausedTemporarily stopped
completedAll contacts processed
cancelledManually stopped

​
Error Codes

CodeDescription
campaign_not_foundCampaign ID doesn’t exist
campaign_already_activeCannot start an active campaign
campaign_not_activeCannot pause a non-active campaign
agent_not_foundSpecified agent doesn’t exist
no_contactsCampaign has no contacts to call