> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaanivoice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Campaign

> Create a new outbound calling campaign with CSV contacts

## 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

**csv\_file** `file` *required*

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

**campaign\_name** `string` *required*

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

**agent\_id** `string` *required*

UUID of the agent that will handle calls

**concurrency** `integer` *required*

Simultaneous calls (≥ 1, ≤ organization max)

**from\_date** `string` *required*

Campaign start date - `YYYY-MM-DD`

**to\_date** `string` *required*

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

**start\_time** `string` *required*

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

**end\_time** `string` *required*

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

**days\_of\_week** `string` *required*

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

**perform\_dnd\_check** `boolean` (default: false)

Run DND check on contacts before dialing

**max\_retries** `integer` (default: 3)

Max dial attempts per contact (1–10)

**retry\_delay\_mins** `integer` (default: 30)

Minutes between retry attempts (0–1440)

**notification\_emails** `string`

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

**campaign\_webhook\_url** `string`

HTTP/HTTPS URL to receive campaign status-change events

**per\_call\_webhook\_url** `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

```bash theme={null}
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 `201 Created`

```json theme={null}
{
  "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

**status\_code** `number`

HTTP status code

**error** `string`

Error name

**message** `string`

Human-readable error message

**code** `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

```json theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.