Developer Campaign APIs

The Campaign APIs allow you to automate outbound voice outreach at scale. You can create campaigns, configure telephony dialing parameters, import contacts via CSV, trigger auto-dialing, and fetch call recordings and lead qualifications. All endpoints require the x-api-key header containing the API key provided by your workspace admin. See API Authentication.

The Outbound Campaign Lifecycle

Executing an automated campaign requires following this 5-step sequence:

Step 1: Create Base Campaign Info

Initializes the campaign record, assigns the AI agent, and associates products/services.

Endpoint: POST /api/v1/external/campaign/add-update-CampaignInfo

{
  "CampaignKeyID": null,
  "TenantID": 1,
  "AgentID": 1,
  "CampaignName": "Q4 Loan Renewal Outreach",
  "CampaignType": "Outbound",
  "CampaignBehaviour": "Single Batch Campaign",
  "CampaignDescription": "Outreach campaign to existing customers regarding pre-approved loan renewals.",
  "ProductList": [1],
  "ServiceList": [1],
  "IsCompleted": false
}

Field	Type	Description
`CampaignKeyID`	UUID string	Pass `null` for a new campaign. Returns a new UUID to use in subsequent steps.
`AgentID`	Integer	The internal integer ID of the AI agent handling the calls.
`CampaignType`	String	Set to `"Outbound"`.
`CampaignBehaviour`	String	`"Single Batch Campaign"` or `"Recurring Campaign"`.
`ProductList` / `ServiceList`	Array of Integers	Product/service IDs from KB Catalog Lookups.

Step 2: Configure Dialing Rules & Telephony

Defines calling hours, retry intervals, virtual numbers, and transfer rules.

Endpoint: POST /api/v1/external/campaign/add-update-outCampaign

{
  "OutboundCampignKeyID": null,
  "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "PhoneNumberKeyID": "c3723e9d-9fa0-11f1-9559-345a60d76a0d",
  "LanguageID": "1",
  "TimeZoneID": "1",
  "CallingHours": { "start": "10:00", "end": "18:00" },
  "MaxConcurrentCalls": 2,
  "DailyCallLimit": 100,
  "RetryUnansweredCalls": true,
  "maxRetries": 2,
  "RetryInterval": 15,
  "VoiceMailDetection": true,
  "TransferToHuman": true,
  "TransferCallTo": "+919876543210",
  "LaunchStartDate": "2026-11-01 10:00:00",
  "LaunchEndDate": "2026-11-05 18:00:00",
  "LaunchStartTime": "10:00:00",
  "StopRuleID": 1,
  "IsCompleted": false
}

Field	Type	Description
`CampaignKeyID`	UUID string	The UUID generated in Step 1.
`PhoneNumberKeyID`	UUID string	Virtual number ID for outbound Caller ID (from Campaign Phone Numbers Lookup).
`CallingHours`	Object	Permitted calling window (`start` and `end` times). The dialer will not place calls outside this range.
`MaxConcurrentCalls`	Integer	Parallel active lines to dial simultaneously.
`DailyCallLimit`	Integer	Maximum numbers dialed per day.
`RetryUnansweredCalls`	Boolean	Whether to re-dial contacts who did not pick up.
`maxRetries`	Integer	Maximum retry attempts per contact.
`RetryInterval`	Integer	Waiting time in minutes before retrying an unanswered call.
`VoiceMailDetection`	Boolean	Automatically disconnect or hang up when answering machines are detected.
`TransferToHuman`	Boolean	Allow the agent to transfer interested callers to a human team.
`TransferCallTo`	String	Target phone number with country code for human transfer.
`StopRuleID`	Integer	Stop condition ID (from Stop Rule Lookup).

Step 3 & 4: Upload & Map Contacts

Option A: Bulk Upload CSV

Endpoint: POST /api/v1/external/campaign/upload
Content-Type: multipart/form-data

Form Field	Type	Description
`file`	File	CSV or Excel file containing contact names, phone numbers, and custom variables.
`CampaignKeyID`	Text	The campaign UUID.
`OutboundCampignKeyID`	Text	The outbound campaign setup UUID from Step 2.

Option B: Add Contacts Manually via JSON

Endpoint: POST /api/v1/external/campaign/add-update-Contacts

{
  "ContactKeyID": null,
  "CustomerName": "Ramesh Sharma",
  "ContactNumber": "9876543210",
  "Email": "ramesh@example.com",
  "Address": "MG Road",
  "City": "Mumbai",
  "State": "Maharashtra",
  "Country": "India",
  "Pincode": "400001",
  "SourceID": 5,
  "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "OutboundCampignKeyID": "528a3ba9-c2d8-11f1-b170-00090ffe0001"
}

Map Contacts to Campaign

After contacts are added, associate their IDs to the dialer queue:

Endpoint: POST /api/v1/external/campaign/map-CampaignContacts

{
  "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "OutboundCampignKeyID": "71b36c1d-c2d9-11f1-b170-00090ffe0001",
  "ContactID": [153, 154, 155]
}

Step 5: Start, Stop, or Schedule the Campaign

Control the automated dialer execution:

Start Campaign

Endpoint: POST /api/v1/external/campaign/start

{
  "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "exotel_app_id": "46335",
  "exotel_virtual_number": "02240611251"
}

Stop Campaign

Immediately halts the auto-dialer:

Endpoint: POST /api/v1/external/campaign/stop

{ "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001" }

Restart Campaign

Resume a stopped or completed campaign:

Endpoint: POST /api/v1/external/campaign/restart

Step 6: Monitor Call Logs & Lead Qualification

1. Fetch Call Logs

Retrieve detailed call records including duration, outcome, and status:

Endpoint: POST /api/v1/external/CallLog/Campaign-log-list

{
  "CampaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "direction": null,
  "outcome": null,
  "pageSize": 10,
  "pageNo": 1,
  "searchName": "",
  "fromDate": null,
  "toDate": null,
  "sortColumn": "CreatedOn",
  "sortOrder": "DESC"
}

2. Download Call Audio Recording

Endpoint: GET /api/v1/external/CallLog/recording/{CallLogID}
Streams the raw .wav or .mp3 audio recording of the conversation.

3. Qualified Leads List

Review contacts that expressed positive intent or qualified through agent criteria:

Endpoint: POST /api/v1/external/lead/lead-list

{
  "campaignKeyID": "ac954a8e-c2d5-11f1-b170-00090ffe0001",
  "callOutcome": "Interested",
  "pageSize": 15,
  "pageNo": 1,
  "sortColumn": "CreatedAt",
  "sortOrder": "DESC"
}

Get Lead Details: GET /api/v1/external/lead/GetCampaignLeadDetails?LeadKeyID={uuid}
Get Lead Conversation Transcript: GET /api/v1/external/lead/get-conversation?LeadKeyID={uuid}

Developer Dashboard

Query live call counts and aggregate metrics.

Master Lookups

Look up virtual numbers and stop rule IDs.

Getting started

Dashboards

Campaigns

Teams

Agents and knowledge

Reference

Developer Campaign APIs

The Outbound Campaign Lifecycle

Step 1: Create Base Campaign Info

Step 2: Configure Dialing Rules & Telephony

Step 3 & 4: Upload & Map Contacts

Option A: Bulk Upload CSV

Option B: Add Contacts Manually via JSON

Map Contacts to Campaign

Step 5: Start, Stop, or Schedule the Campaign

Start Campaign

Stop Campaign

Restart Campaign

Step 6: Monitor Call Logs & Lead Qualification

1. Fetch Call Logs

2. Download Call Audio Recording

3. Qualified Leads List

Developer Dashboard

Master Lookups

​The Outbound Campaign Lifecycle

​Step 1: Create Base Campaign Info

​Step 2: Configure Dialing Rules & Telephony

​Step 3 & 4: Upload & Map Contacts

​Option A: Bulk Upload CSV

​Option B: Add Contacts Manually via JSON

​Map Contacts to Campaign

​Step 5: Start, Stop, or Schedule the Campaign

​Start Campaign

​Stop Campaign

​Restart Campaign

​Step 6: Monitor Call Logs & Lead Qualification

​1. Fetch Call Logs

​2. Download Call Audio Recording

​3. Qualified Leads List

Developer Dashboard

Master Lookups

The Outbound Campaign Lifecycle

Step 1: Create Base Campaign Info

Step 2: Configure Dialing Rules & Telephony

Step 3 & 4: Upload & Map Contacts

Option A: Bulk Upload CSV

Option B: Add Contacts Manually via JSON

Map Contacts to Campaign

Step 5: Start, Stop, or Schedule the Campaign

Start Campaign

Stop Campaign

Restart Campaign

Step 6: Monitor Call Logs & Lead Qualification

1. Fetch Call Logs

2. Download Call Audio Recording

3. Qualified Leads List