Create Campaign

curl --request POST \
  --url https://api.example.com/api/campaigns/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaign_name": "<string>",
  "agent_id": "<string>",
  "concurrency": 123,
  "from_date": "<string>",
  "to_date": "<string>",
  "start_time": "<string>",
  "end_time": "<string>",
  "days_of_week": "<string>",
  "perform_dnd_check": true,
  "max_retries": 123,
  "retry_delay_mins": 123,
  "notification_emails": "<string>",
  "campaign_webhook_url": "<string>",
  "per_call_webhook_url": "<string>"
}
'

import requests

url = "https://api.example.com/api/campaigns/create"

payload = {
    "campaign_name": "<string>",
    "agent_id": "<string>",
    "concurrency": 123,
    "from_date": "<string>",
    "to_date": "<string>",
    "start_time": "<string>",
    "end_time": "<string>",
    "days_of_week": "<string>",
    "perform_dnd_check": True,
    "max_retries": 123,
    "retry_delay_mins": 123,
    "notification_emails": "<string>",
    "campaign_webhook_url": "<string>",
    "per_call_webhook_url": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    campaign_name: '<string>',
    agent_id: '<string>',
    concurrency: 123,
    from_date: '<string>',
    to_date: '<string>',
    start_time: '<string>',
    end_time: '<string>',
    days_of_week: '<string>',
    perform_dnd_check: true,
    max_retries: 123,
    retry_delay_mins: 123,
    notification_emails: '<string>',
    campaign_webhook_url: '<string>',
    per_call_webhook_url: '<string>'
  })
};

fetch('https://api.example.com/api/campaigns/create', 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.example.com/api/campaigns/create",
  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([
    'campaign_name' => '<string>',
    'agent_id' => '<string>',
    'concurrency' => 123,
    'from_date' => '<string>',
    'to_date' => '<string>',
    'start_time' => '<string>',
    'end_time' => '<string>',
    'days_of_week' => '<string>',
    'perform_dnd_check' => true,
    'max_retries' => 123,
    'retry_delay_mins' => 123,
    'notification_emails' => '<string>',
    'campaign_webhook_url' => '<string>',
    'per_call_webhook_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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.example.com/api/campaigns/create"

	payload := strings.NewReader("{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}")

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

	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.example.com/api/campaigns/create")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}"

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

{
  "status_code": 123,
  "error": "<string>",
  "message": "<string>",
  "code": "<string>"
}

POST

api

campaigns

create

Create Campaign

curl --request POST \
  --url https://api.example.com/api/campaigns/create \
  --header 'Content-Type: application/json' \
  --data '
{
  "campaign_name": "<string>",
  "agent_id": "<string>",
  "concurrency": 123,
  "from_date": "<string>",
  "to_date": "<string>",
  "start_time": "<string>",
  "end_time": "<string>",
  "days_of_week": "<string>",
  "perform_dnd_check": true,
  "max_retries": 123,
  "retry_delay_mins": 123,
  "notification_emails": "<string>",
  "campaign_webhook_url": "<string>",
  "per_call_webhook_url": "<string>"
}
'

import requests

url = "https://api.example.com/api/campaigns/create"

payload = {
    "campaign_name": "<string>",
    "agent_id": "<string>",
    "concurrency": 123,
    "from_date": "<string>",
    "to_date": "<string>",
    "start_time": "<string>",
    "end_time": "<string>",
    "days_of_week": "<string>",
    "perform_dnd_check": True,
    "max_retries": 123,
    "retry_delay_mins": 123,
    "notification_emails": "<string>",
    "campaign_webhook_url": "<string>",
    "per_call_webhook_url": "<string>"
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    campaign_name: '<string>',
    agent_id: '<string>',
    concurrency: 123,
    from_date: '<string>',
    to_date: '<string>',
    start_time: '<string>',
    end_time: '<string>',
    days_of_week: '<string>',
    perform_dnd_check: true,
    max_retries: 123,
    retry_delay_mins: 123,
    notification_emails: '<string>',
    campaign_webhook_url: '<string>',
    per_call_webhook_url: '<string>'
  })
};

fetch('https://api.example.com/api/campaigns/create', 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.example.com/api/campaigns/create",
  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([
    'campaign_name' => '<string>',
    'agent_id' => '<string>',
    'concurrency' => 123,
    'from_date' => '<string>',
    'to_date' => '<string>',
    'start_time' => '<string>',
    'end_time' => '<string>',
    'days_of_week' => '<string>',
    'perform_dnd_check' => true,
    'max_retries' => 123,
    'retry_delay_mins' => 123,
    'notification_emails' => '<string>',
    'campaign_webhook_url' => '<string>',
    'per_call_webhook_url' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$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.example.com/api/campaigns/create"

	payload := strings.NewReader("{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}")

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

	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.example.com/api/campaigns/create")
  .header("Content-Type", "application/json")
  .body("{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"campaign_name\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"concurrency\": 123,\n  \"from_date\": \"<string>\",\n  \"to_date\": \"<string>\",\n  \"start_time\": \"<string>\",\n  \"end_time\": \"<string>\",\n  \"days_of_week\": \"<string>\",\n  \"perform_dnd_check\": true,\n  \"max_retries\": 123,\n  \"retry_delay_mins\": 123,\n  \"notification_emails\": \"<string>\",\n  \"campaign_webhook_url\": \"<string>\",\n  \"per_call_webhook_url\": \"<string>\"\n}"

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

{
  "status_code": 123,
  "error": "<string>",
  "message": "<string>",
  "code": "<string>"
}

Create Campaign

Create a new outbound calling campaign by uploading a CSV file with contacts and configuring campaign parameters. This is a multipart/form-data endpoint — send the CSV file and all configuration fields together in a single request.

Request Parameters

file

required

CSV file with contact data. Required columns: name, phone_number

string

required

Human-readable name for the campaign (max 255 characters)

string

required

UUID of the agent that will handle calls

integer

required

Simultaneous calls (≥ 1, ≤ organization max)

string

required

Campaign start date — YYYY-MM-DD

string

required

Campaign end date — YYYY-MM-DD (≥ from_date)

string

required

Daily call window open — UTC HH:MM 24-hour format (e.g. 02:30)

string

required

Daily call window close — UTC HH:MM 24-hour format (e.g. 14:00)

string

required

Comma-separated weekdays, e.g. monday,tuesday,friday

boolean

default:"false"

Run DND check on contacts before dialing

integer

default:"3"

Max dial attempts per contact (1–10)

integer

default:"30"

Minutes between retry attempts (0–1440)

string

Comma-separated email addresses for completion notifications (max 5)

string

HTTP/HTTPS URL to receive campaign status-change events

string

HTTP/HTTPS URL to receive per-call post-processing events

Time Window Reference

All times must be in 24-hour HH:MM format in UTC only.

Allowed UTC range	Equivalent IST range
`02:30` – `14:29`	`08:00` – `19:59`

TRAI compliance window is 08:00–19:59 IST. Submit the UTC equivalent.
To convert: IST − 5:30 = UTC (e.g. 13:00 IST = 07:30 UTC)

Example Request

curl -X POST https://api.vaani.ai/api/campaigns/create \
  -H "X-API-Key: vaani_abc123..." \
  -F "csv_file=@contacts.csv" \
  -F "campaign_name=Summer Promo 2024" \
  -F "agent_id=5e737076-fea2-4157-8343-a8e49e5f0990" \
  -F "concurrency=3" \
  -F "from_date=2026-07-10" \
  -F "to_date=2026-07-31" \
  -F "start_time=07:30" \
  -F "end_time=13:30" \
  -F "days_of_week=monday,tuesday,wednesday,thursday,friday" \
  -F "notification_emails=ops@company.com"

Response `201 Created`

{
  "id": "57fbcf93-a809-4038-8ea9-d676cf7d7fd4",
  "client_id": "1b9e0250-d265-4a67-bb03-c40c98978c76",
  "agent_id": "5e737076-fea2-4157-8343-a8e49e5f0990",
  "campaign_name": "Summer Promo 2024",
  "excel_blob_url": "https://vaani-dev-storage.s3.ap-south-1.amazonaws.com/campaigns/...",
  "campaign_status": "active",
  "contact_source_type": "csv",
  "days_of_week": "monday,tuesday,wednesday,thursday,friday",
  "time_range_from": "07:30:00Z",
  "time_range_to": "13:30:00Z",
  "max_retries": 3,
  "retry_after_mins": 30,
  "call_concurrency": 3,
  "start_date": "2026-07-10T02:00:00",
  "end_date": "2026-07-31T04:00:00",
  "notification_emails": ["ops@company.com"],
  "webhook_url": null,
  "perform_dnd_check": false,
  "created_at": "2026-07-01T08:59:33.063483",
  "updated_at": "2026-07-01T08:59:33.063487"
}

CSV File Requirements

Required Columns

Column	Aliases accepted
`name`	`contact_name`, `customer_name`, `full_name`
`phone_number`	`phone`, `mobile`, `contact`, `contact_number`, `mobile_number`

Optional Columns

Any extra columns are treated as dynamic variables passed to the agent. Column names must exactly match (case-sensitive) the variable names configured on the agent.

File Limits

Property	Limit
Formats	`.csv`, `.xlsx`, `.xls`
Encoding	UTF-8
Max rows	10,000 contacts
Min rows	1 contact

Phone Number Formats Accepted

+91XXXXXXXXXX (E.164 with country code)
91XXXXXXXXXX (country code without +)
0XXXXXXXXXX (leading zero, Indian trunk prefix)
XXXXXXXXXX (bare 10-digit number)

Error Responses

number

HTTP status code

string

Error name

string

Human-readable error message

string

Machine-readable error code

Common Error Codes

Code	Description
`INVALID_TIME_WINDOW`	Time outside 02:30-14:29 UTC (TRAI compliance)
`CONCURRENCY_EXCEEDED`	Concurrency exceeds organization maximum
`INVALID_DATE_RANGE`	from_date > to_date
`NO_DAYS_SELECTED`	days_of_week is empty
`INVALID_RETRY_CONFIG`	max_retries or retry_delay_mins out of range
`TOO_MANY_EMAILS`	More than 5 notification_emails

Example Error Response

{
  "status_code": 400,
  "error": "Bad Request",
  "message": "concurrency 50 exceeds your organisation's maximum of 10.",
  "code": "CONCURRENCY_EXCEEDED",
  "path": "/api/campaigns/create",
  "timestamp": "2026-07-01T08:51:11.245139Z",
  "request_id": "unknown"
}

Overview

Campaigns

Agents

Calls

Create Campaign

Create Campaign

Request Parameters

Time Window Reference

Example Request

Response `201 Created`

CSV File Requirements

Required Columns

Optional Columns

File Limits

Phone Number Formats Accepted

Error Responses

Common Error Codes

Example Error Response

​Create Campaign

​Request Parameters

​Time Window Reference

​Example Request

​Response 201 Created

​CSV File Requirements

​Required Columns

​Optional Columns

​File Limits

​Phone Number Formats Accepted

​Error Responses

​Common Error Codes

​Example Error Response

Create Campaign

Request Parameters

Time Window Reference

Example Request

Response `201 Created`

CSV File Requirements

Required Columns

Optional Columns

File Limits

Phone Number Formats Accepted

Error Responses

Common Error Codes

Example Error Response