API Reference
Campaigns API
Create, manage, and control outbound calling campaigns.
Campaigns automate outbound communications. You can create campaigns, configure business hours, set rate limits, and control campaign status (start, pause, archive).
Available Endpoints
/api/v1/campaigns— List all campaigns/api/v1/campaigns— Create a campaign/api/v1/campaigns/:id— Get a campaign/api/v1/campaigns/:id— Update a campaign/api/v1/campaigns/:id— Archive a campaign/api/v1/campaigns/:id/start— Start a campaign/api/v1/campaigns/:id/pause— Pause a campaignList Campaigns
/api/v1/campaignsRetrieves a paginated list of campaigns with optional filtering.
Query Parameters
Parameters
| Name | Type | Description |
|---|---|---|
limit | integer | Number of campaigns to return (1-100, default: 20) |
offset | integer | Number of campaigns to skip (default: 0) |
status | string | Filter by status: draft, active, paused, completed, archived |
type | string | Filter by type: outbound, inbound, webhook |
Example Request
curl -X GET "https://dev.nutalk.ai/v1/campaigns?status=active&limit=10" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": [
{
"id": "camp_abc123",
"name": "Q1 Outreach",
"description": "First quarter customer outreach campaign",
"type": "outbound",
"status": "active",
"total_enrollments": 500,
"active_enrollments": 150,
"completed_enrollments": 320,
"goal_reached_count": 45,
"business_hours": {
"timezone": "America/New_York",
"days": {
"monday": { "start": "09:00", "end": "17:00" },
"tuesday": { "start": "09:00", "end": "17:00" }
}
},
"rate_limits": {
"max_concurrent_calls": 10,
"calls_per_minute": 5
},
"created_at": "2024-01-10T08:00:00Z",
"updated_at": "2024-01-25T12:00:00Z"
}
],
"pagination": {
"total": 15,
"limit": 10,
"offset": 0,
"has_more": true
}
}Create Campaign
/api/v1/campaignsCreates a new campaign in draft status.
Request Body
Parameters
| Name | Type | Description |
|---|---|---|
nameRequired | string | Campaign name (1-200 characters) |
description | string | Campaign description (max 1000 characters) |
type | string | Campaign type: outbound, inbound, or webhook (default: outbound) |
outbound_channel_id | uuid | Channel ID for outbound calls |
business_hours | object | Business hours configuration |
rate_limits | object | Rate limiting configuration |
Example Request
curl -X POST "https://dev.nutalk.ai/v1/campaigns" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Summer Sale Campaign", "description": "Outreach for summer promotion", "type": "outbound", "business_hours": { "timezone": "America/Los_Angeles", "days": { "monday": { "start": "10:00", "end": "18:00" }, "tuesday": { "start": "10:00", "end": "18:00" }, "wednesday": { "start": "10:00", "end": "18:00" } } }, "rate_limits": { "max_concurrent_calls": 5, "calls_per_minute": 3 }}'Response
{
"success": true,
"data": {
"id": "camp_def456",
"name": "Summer Sale Campaign",
"description": "Outreach for summer promotion",
"type": "outbound",
"status": "draft",
"business_hours": {
"timezone": "America/Los_Angeles",
"days": {
"monday": { "start": "10:00", "end": "18:00" },
"tuesday": { "start": "10:00", "end": "18:00" },
"wednesday": { "start": "10:00", "end": "18:00" }
}
},
"rate_limits": {
"max_concurrent_calls": 5,
"calls_per_minute": 3
},
"created_at": "2024-01-25T16:30:00Z",
"updated_at": "2024-01-25T16:30:00Z"
}
}Draft Status
New campaigns are created in draft status. Use the /start endpoint to activate them.
Start Campaign
/api/v1/campaigns/:id/startActivates a campaign. The campaign will begin processing enrollments according to its configuration.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The campaign's unique identifier |
Example Request
curl -X POST "https://dev.nutalk.ai/v1/campaigns/camp_abc123/start" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"id": "camp_abc123",
"name": "Q1 Outreach",
"status": "active",
"type": "outbound",
"updated_at": "2024-01-25T17:00:00Z"
},
"message": "Campaign started successfully"
}Requirements
Outbound campaigns require a channel to be configured before they can be started. Ensure outbound_channel_id is set.
Pause Campaign
/api/v1/campaigns/:id/pausePauses an active campaign. No new calls will be initiated while paused.
Path Parameters
Parameters
| Name | Type | Description |
|---|---|---|
idRequired | uuid | The campaign's unique identifier |
Example Request
curl -X POST "https://dev.nutalk.ai/v1/campaigns/camp_abc123/pause" \ -H "Authorization: Bearer YOUR_API_KEY"Response
{
"success": true,
"data": {
"id": "camp_abc123",
"name": "Q1 Outreach",
"status": "paused",
"type": "outbound",
"updated_at": "2024-01-25T18:00:00Z"
},
"message": "Campaign paused successfully"
}Campaign Statuses
| Status | Description | Allowed Actions |
|---|---|---|
| draft | Campaign is being configured | start, update, delete |
| active | Campaign is running and processing enrollments | pause, update |
| paused | Campaign is paused, no new calls | start, update, delete |
| completed | All enrollments have been processed | delete (archive) |
| archived | Campaign has been archived | none (read-only) |
Enrollments
To add contacts to a campaign, use the dashboard or create enrollments via webhook integrations. API enrollment support is coming soon.