Create Campaign

Create a managed batch calling campaign with lifecycle controls.

POST /campaigns

Create a campaign

cURL

curl --request POST \
  --url https://api.dialnexa.com/v1/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q2 Lead Re-engagement",
  "agent_id": "agt_abc123",
  "from_phone_number": "[phone]",
  "scheduled_at": "2023-11-07T05:31:56Z",
  "max_concurrent_calls": 5,
  "retry_config": {
    "max_retries": 3,
    "retry_interval_minutes": 120
  }
}
'

201

{
  "id": "cmp_xyz789",
  "organization_id": "org_xyz",
  "name": "Q2 Lead Re-engagement",
  "agent_id": "agt_abc123",
  "from_phone_number": "[phone]",
  "status": "running",
  "max_concurrent_calls": 5,
  "scheduled_at": null,
  "retry_config": {
    "max_retries": 3,
    "retry_interval_minutes": 120
  },
  "created_at": "2024-03-01T09:00:00.000Z"
}

A campaign is a managed outreach effort where you have full lifecycle control. You can pause, resume, and cancel it at any time. Unlike a batch call (which is one-shot), a campaign lets you add leads incrementally and control the pace of calling.

Batch calls vs. campaigns

	Batch Call	Campaign
Leads added via	File upload at creation	File upload or one-by-one after creation
Lifecycle controls	None	Pause, resume, cancel
Best for	Fixed one-shot outreach	Ongoing or large-scale campaigns

Workflow

1. Create the campaign with this endpoint.
2. Add leads via Bulk Upload or Add Lead.
3. Monitor delivery using campaign lead endpoints and call logs.
4. Update campaign details when needed.
5. Track each lead’s progress through campaign lead endpoints and call logs.

Request example

{
  "name": "Q2 Lead Re-engagement",
  "agent_id": "agt_abc123",
  "from_phone_number": "[phone]",
  "max_concurrent_calls": 5,
  "retry_config": {
    "max_retries": 2,
    "retry_interval_minutes": 120
  }
}

Request

curl "https://api.dialnexa.com/v1/campaigns" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Response

{
  "id": "cmp_5tw8vz2rnx1q",
  "name": "Q2 Lead Re-engagement",
  "status": "active",
  "agent_id": "agt_k7m2nq9xw4p8",
  "from_phone_number": "[phone]",
  "max_concurrent_calls": 5,
  "total_leads": 1200,
  "completed_calls": 438,
  "pending_calls": 762,
  "created_at": "2024-05-01T09:00:00.000Z"
}

Authorizations

Authorization · string · header · required

Pass your API key as a Bearer token in the Authorization header.

Body

application/json

name · string · required

Display name for the campaign.

Example:

"Q2 Lead Re-engagement"

agent_id · string · required

Example:

"agt_abc123"

from_phone_number · string

Example:

"[phone]"

scheduled_at · string<date-time>

max_concurrent_calls · integer

Example:

5

retry_config · object

Show child attributes

Response

201 - application/json

Created.

id · string

Example:

"cmp_xyz789"

organization_id · string

Example:

"org_xyz"

name · string

Example:

"Q2 Lead Re-engagement"

agent_id · string

Example:

"agt_abc123"

from_phone_number · string

Example:

"[phone]"

status · enum<string>

Batch campaign lifecycle status.

Available options: draft, active, running, paused, completed, cancelled

Example:

"running"

max_concurrent_calls · integer

Example:

5

scheduled_at · string<date-time> | null

Example:

null

retry_config · object

Example:

{
  "max_retries": 3,
  "retry_interval_minutes": 120
}

created_at · string<date-time>

Example:

"2024-03-01T09:00:00.000Z"