Create Campaign - DialNexa Documentation

POST

campaigns

Create a new campaign

curl --request POST \
  --url https://api.dialnexa.com/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "title": "New Product Launch",
  "agent_id": 101,
  "agent_version_number": 1,
  "starts_at": "2025-05-10T09:00:00Z",
  "ends_at": "2025-05-20T18:00:00Z",
  "calling_hours_start": "09:00",
  "calling_hours_end": "18:00",
  "total_lead_count": "10",
  "status": "draft",
  "number_of_retries": 3,
  "interval_between_retries": 15
}
'

import requests

url = "https://api.dialnexa.com/campaigns"

payload = {
    "title": "New Product Launch",
    "agent_id": 101,
    "agent_version_number": 1,
    "starts_at": "2025-05-10T09:00:00Z",
    "ends_at": "2025-05-20T18:00:00Z",
    "calling_hours_start": "09:00",
    "calling_hours_end": "18:00",
    "total_lead_count": "10",
    "status": "draft",
    "number_of_retries": 3,
    "interval_between_retries": 15
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'New Product Launch',
    agent_id: 101,
    agent_version_number: 1,
    starts_at: '2025-05-10T09:00:00Z',
    ends_at: '2025-05-20T18:00:00Z',
    calling_hours_start: '09:00',
    calling_hours_end: '18:00',
    total_lead_count: '10',
    status: 'draft',
    number_of_retries: 3,
    interval_between_retries: 15
  })
};

fetch('https://api.dialnexa.com/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/campaigns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'New Product Launch',
    'agent_id' => 101,
    'agent_version_number' => 1,
    'starts_at' => '2025-05-10T09:00:00Z',
    'ends_at' => '2025-05-20T18:00:00Z',
    'calling_hours_start' => '09:00',
    'calling_hours_end' => '18:00',
    'total_lead_count' => '10',
    'status' => 'draft',
    'number_of_retries' => 3,
    'interval_between_retries' => 15
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/campaigns"

	payload := strings.NewReader("{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/campaigns")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}"

response = http.request(request)
puts response.read_body

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. A public v1 replacement is not currently listed in the v1 reference. This endpoint remains available for existing integrations until then.

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

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

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-id

string

required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

Body

application/json

title

string

required

Title of the campaign (max 150 characters)

Maximum string length: 150

Example:

"New Product Launch"

agent_id

string

required

Agent ID associated with the campaign

Example:

101

agent_version_number

number

Agent Version ID associated with the campaign

Example:

1

starts_at

string

Start timestamp of the campaign (ISO string)

Example:

"2025-05-10T09:00:00Z"

ends_at

string

End timestamp of the campaign (ISO string)

Example:

"2025-05-20T18:00:00Z"

calling_hours_start

string

Start of allowed calling hours (HH:mm format only, not full datetime)

Example:

"09:00"

calling_hours_end

string

End of allowed calling hours (HH:mm format only, not full datetime)

Example:

"18:00"

total_lead_count

number

Total Number of Leads for this Campaign

Example:

"10"

status

enum<string>

Status of the campaign

Available options:

draft,

active,

running,

paused,

completed,

cancelled

Example:

"draft"

number_of_retries

number

Number of retries for the campaign (0-5)

Example:

3

interval_between_retries

number

Interval between retries in minutes (0-1440)

Example:

15

Response

Campaign created successfully

List CampaignsRetrieve every calling campaign in your workspace, with status and live progress counters, ordered newest first.

Create a new campaign

curl --request POST \
  --url https://api.dialnexa.com/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "title": "New Product Launch",
  "agent_id": 101,
  "agent_version_number": 1,
  "starts_at": "2025-05-10T09:00:00Z",
  "ends_at": "2025-05-20T18:00:00Z",
  "calling_hours_start": "09:00",
  "calling_hours_end": "18:00",
  "total_lead_count": "10",
  "status": "draft",
  "number_of_retries": 3,
  "interval_between_retries": 15
}
'

import requests

url = "https://api.dialnexa.com/campaigns"

payload = {
    "title": "New Product Launch",
    "agent_id": 101,
    "agent_version_number": 1,
    "starts_at": "2025-05-10T09:00:00Z",
    "ends_at": "2025-05-20T18:00:00Z",
    "calling_hours_start": "09:00",
    "calling_hours_end": "18:00",
    "total_lead_count": "10",
    "status": "draft",
    "number_of_retries": 3,
    "interval_between_retries": 15
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'New Product Launch',
    agent_id: 101,
    agent_version_number: 1,
    starts_at: '2025-05-10T09:00:00Z',
    ends_at: '2025-05-20T18:00:00Z',
    calling_hours_start: '09:00',
    calling_hours_end: '18:00',
    total_lead_count: '10',
    status: 'draft',
    number_of_retries: 3,
    interval_between_retries: 15
  })
};

fetch('https://api.dialnexa.com/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/campaigns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'New Product Launch',
    'agent_id' => 101,
    'agent_version_number' => 1,
    'starts_at' => '2025-05-10T09:00:00Z',
    'ends_at' => '2025-05-20T18:00:00Z',
    'calling_hours_start' => '09:00',
    'calling_hours_end' => '18:00',
    'total_lead_count' => '10',
    'status' => 'draft',
    'number_of_retries' => 3,
    'interval_between_retries' => 15
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/campaigns"

	payload := strings.NewReader("{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/campaigns")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"New Product Launch\",\n  \"agent_id\": 101,\n  \"agent_version_number\": 1,\n  \"starts_at\": \"2025-05-10T09:00:00Z\",\n  \"ends_at\": \"2025-05-20T18:00:00Z\",\n  \"calling_hours_start\": \"09:00\",\n  \"calling_hours_end\": \"18:00\",\n  \"total_lead_count\": \"10\",\n  \"status\": \"draft\",\n  \"number_of_retries\": 3,\n  \"interval_between_retries\": 15\n}"

response = http.request(request)
puts response.read_body

​Batch calls vs. campaigns

​Workflow

Authorizations

Headers

Body

Response

Batch calls vs. campaigns

Workflow