Create Campaign

POST

api

campaigns

create

Create Campaign

curl --request POST \
  --url https://api.vaanivoice.ai/api/campaigns/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --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.vaanivoice.ai/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 = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', '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.vaanivoice.ai/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.vaanivoice.ai/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",
    "X-API-Key: <api-key>"
  ],
]);

$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.vaanivoice.ai/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("X-API-Key", "<api-key>")
	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.vaanivoice.ai/api/campaigns/create")
  .header("X-API-Key", "<api-key>")
  .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.vaanivoice.ai/api/campaigns/create")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
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>",
  "path": "<string>",
  "timestamp": "<string>",
  "request_id": "<string>",
  "code": "<string>"
}

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.vaanivoice.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 `200 OK`

The campaign is created with status populating while the contact file is being imported. It then moves to active (start date reached, inside calling hours), scheduled (start date in the future), paused_out_of_range (start date reached but outside calling hours) or failed (the file could not be imported). Poll Get Campaign Status to see the transition.

{
  "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": "populating",
  "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

Request path

string

When the error occurred

string

Request id, quote it when contacting support

string

Machine-readable error code, present when the failing check defines one (see the table below). Errors from the Vaani backend (for example campaign not found, insufficient balance) may carry their own code. Range errors that FastAPI rejects before the handler runs (422) have no code; read message.

Common Validation Errors

`code`	Status	Condition
`INVALID_TIME_FORMAT`	400	`start_time`/`end_time` not in `HH:MM`
`INVALID_TIME_WINDOW`	400	Time outside 02:30-14:29 UTC (TRAI compliance)
`CONCURRENCY_EXCEEDED`	400	`concurrency` above your organisation maximum
`INVALID_DATE_RANGE`	400	`from_date` after `to_date`, or an invalid date
`NO_DAYS_SELECTED`	400	`days_of_week` is empty
`INVALID_DAYS_OF_WEEK`	400	Unknown weekday name
`INVALID_WEBHOOK_URL`	400	Webhook URL is not a valid http/https URL
`TOO_MANY_EMAILS`	400	More than 5 `notification_emails`
`UPLOAD_FAILED`	500	The CSV was accepted but no blob URL came back
`2003`	400	The CSV has no `name` column (or no phone-number column). The message lists the accepted column names
`2011`	404	`agent_id` not found for your account
`2037`	400	The agent has no outbound number assigned
(none)	422	`max_retries` outside 1-10, `retry_delay_mins` outside 0-1440 or `concurrency` below 1. `message` is e.g. `body -> max_retries: Input should be less than or equal to 10`

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.245139+00:00",
  "request_id": "6f1c1c0e-6a4e-4a43-9d51-0f1d0e2b9c11",
  "detail": "concurrency 50 exceeds your organisation's maximum of 10."
}

Example Validation Error (422)

{
  "status_code": 422,
  "error": "Unprocessable Entity",
  "message": "body -> max_retries: Input should be less than or equal to 10",
  "path": "/api/campaigns/create",
  "timestamp": "2026-07-01T08:51:11.245139+00:00",
  "request_id": "0a9d2b5c-7c33-4a7e-9c0f-3a5f4f0e7d10",
  "detail": "body -> max_retries: Input should be less than or equal to 10"
}

Create Campaign

curl --request POST \
  --url https://api.vaanivoice.ai/api/campaigns/create \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --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.vaanivoice.ai/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 = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', '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.vaanivoice.ai/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.vaanivoice.ai/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",
    "X-API-Key: <api-key>"
  ],
]);

$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.vaanivoice.ai/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("X-API-Key", "<api-key>")
	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.vaanivoice.ai/api/campaigns/create")
  .header("X-API-Key", "<api-key>")
  .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.vaanivoice.ai/api/campaigns/create")

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

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
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>",
  "path": "<string>",
  "timestamp": "<string>",
  "request_id": "<string>",
  "code": "<string>"
}

Overview

Campaigns

Agents

Calls

Create Campaign

Create Campaign

Request Parameters

Time Window Reference

Example Request

Response `200 OK`

CSV File Requirements

Required Columns

Optional Columns

File Limits

Phone Number Formats Accepted

Error Responses

Common Validation Errors

Example Error Response

Example Validation Error (422)

​Create Campaign

​Request Parameters

​Time Window Reference

​Example Request

​Response 200 OK

​CSV File Requirements

​Required Columns

​Optional Columns

​File Limits

​Phone Number Formats Accepted

​Error Responses

​Common Validation Errors

​Example Error Response

​Example Validation Error (422)

Create Campaign

Request Parameters

Time Window Reference

Example Request

Response `200 OK`

CSV File Requirements

Required Columns

Optional Columns

File Limits

Phone Number Formats Accepted

Error Responses

Common Validation Errors

Example Error Response

Example Validation Error (422)