> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Upload Campaign Contact List
> Uploads a contact list for a campaign. Accepts a CSV file and campaign configuration as form data.
Upload a CSV file with contact data to create a campaign. This is the primary upload endpoint for the standard campaign flow: first call `POST /campaign/save`, then start calls with `POST /campaign/start`.
For CSVs with 5,000 or more rows, use the beta large-campaign flow instead: [Upload large campaign CSV](/api-reference/endpoint/campaign/upload-large-campaign-csv), poll upload status, check balance, then start calls asynchronously.
## Quick start
1. **Prepare your CSV** - Download template from your campaigns tab
2. **Configure your agent** - Set up prompts and custom variables
3. **Upload & configure** - Submit CSV with campaign settings
4. **Start calling** - Use the returned `list_id` to start your campaign
## CSV file requirements
**Important File Rules:**
* CSV format only
* Must include "Mobile Number" column
* Phone numbers need country code, for example `+919876543210`
* Download the exact template from the campaign tab for your agent
### Example CSV Structure
```
Mobile Number,Name,Company,Email
+918882876897,John Doe,XYZ Corp,user@example.com
+918882876898,Jane Smith,ABC Inc,user@example.com
```
## Configuration parameters
### Required Fields
| Field | Format | Example |
| ----------------------- | -------------------- | ------------------------------------ |
| **CSV File** | .csv file | contacts.csv |
| **Agent ID** | UUID | 830f767a-397e-4b39-82ff-235cd344e2f9 |
| **Campaign Name** | Text | "Q1 Sales Outreach" |
| **Country Code** | Phone dialing prefix | "+91", "+1" |
| **Campaign Start Time** | DD/MM/YYYY, HH:MM | 18/10/2026, 09:00 |
| **Campaign End Time** | DD/MM/YYYY, HH:MM | 18/10/2026, 21:00 |
### Optional Settings
| Setting | Default | Purpose |
| ------------------------- | ------- | -------------------- |
| Remove Invalid Rows | false | Auto-remove bad data |
| Transliterate Callee Name | false | Convert to English |
## CSV File Format
**Download the exact CSV template from your campaigns tab** to get the correct format according to your specific agent configuration. The required columns vary based on your agent's custom variables.
`campaign_start_time` and `campaign_end_time` use the timezone in `call_config.call_time.timezone`. The backend expects the `DD/MM/YYYY, HH:MM` format and validates that the start time is in the future.
## Variable mapping
Connect your CSV columns to agent variables so your AI can use the contact data during calls.
### How It Works
Map CSV column names to your agent's custom variables:
```json theme={null}
{
"callee_name": "Name",
"company_name": "Company",
"email": "Email",
"custom_field": "Custom Field 1"
}
```
### Using Variables
Reference mapped variables in your agent prompt with `@{{variable_name}}`:
* `@{{callee_name}}` becomes "John Doe"
* `@{{company_name}}` becomes "XYZ Corp"
## Call configuration
Control when and how your campaign calls are made:
### Call timing and limits
```json theme={null}
{
"idle_timeout_warning": 10,
"idle_timeout_end": 15,
"max_call_length": 300,
"call_time": {
"call_start_time": "09:00",
"call_end_time": "18:00",
"timezone": "Asia/Kolkata"
}
}
```
### Retry settings
```json theme={null}
{
"call_retry_config": {
"retry_count": 3,
"retry_busy": 30,
"retry_not_picked": 30,
"retry_failed": 30
}
}
```
## What happens next?
### Success Response
You'll receive a `list_id`. Save it because you need it to start the campaign.
```json theme={null}
{
"message": "Contacts imported successfully!",
"list_id": "123e4567-e89b-12d3-a456-426614174000",
"total_rows": 100,
"successful_rows": 98,
"failed_rows": 2
}
```
### Next Steps
1. **Save the `list_id`** from the response
2. **[Start your campaign](/api-reference/endpoint/campaign/start-campaign)** using the `list_id`
3. **[Monitor progress](/api-reference/endpoint/campaign/get-all-campaigns)** and view results
For 5,000+ row CSVs, the beta flow returns `bulk_list_id` and requires status polling before calls can start.
### Error Handling
If upload fails, check:
* CSV format and required columns
* Valid phone number format with country codes
* Agent ID exists and is active
* API key permissions
Set `remove_invalid_rows=true` to automatically skip problematic contacts instead of failing the entire upload.
## OpenAPI
````yaml post /campaign/save
openapi: 3.0.0
info:
title: Ringg AI API Documentation
description: >-
This is the documentation for the Ringg AI APIs. The Ringg AI API follows
RESTful principles, making it intuitive and easy to integrate with your
applications. All API requests should be made to the base URL. The API
accepts and returns data in JSON format. Ensure your requests include the
appropriate Content-Type header for POST and PATCH requests.
version: 2.0.0
servers:
- url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
- name: workspace
description: Endpoints for managing your workspace.
- name: agent
description: Endpoints for managing assistants (agents).
- name: calling
description: Endpoints for making and managing calls.
- name: campaign
description: Endpoints for managing campaigns.
- name: analytics
description: Endpoints for accessing call analytics and performance metrics.
- name: termination
description: Endpoints for terminating active calls using different methods.
- name: knowledgebase
description: Endpoints for managing knowledge bases.
paths:
/campaign/save:
post:
tags:
- campaign
summary: Upload Campaign Contact List
description: >-
Uploads a contact list for a campaign. Accepts a CSV file and campaign
configuration as form data.
operationId: uploadCampaignContactList
parameters:
- name: X-API-KEY
in: header
description: (Required) Your Ringg AI API key.
required: true
schema:
type: string
example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- variables_map
- agent_id
- call_config
- country_code
- campaign_start_time
- campaign_end_time
- campaign_name
- file
properties:
variables_map:
type: string
description: (Required) JSON string mapping variable names to columns
example:
callee_name: Name
company_name: Company
agent_id:
type: string
description: (Required) Unique identifier for the agent
example: 830f767a-397e-4b39-82ff-235cd344e2f9
call_config:
type: string
description: (Required) JSON string of call configuration
example:
idle_timeout_warning: 10
max_call_length: 300
country_code:
type: string
description: >-
(Required) Phone number country code (e.g., +91 for India,
+1 for US)
example: '+91'
campaign_start_time:
type: string
description: >-
(Required) Start time for the campaign (DD/MM/YYYY, HH:MM
format)
example: 18/10/2025, 09:00
campaign_end_time:
type: string
description: >-
(Required) End time for the campaign (DD/MM/YYYY, HH:MM
format)
example: 18/10/2025, 21:05
campaign_name:
type: string
description: (Required) Name of the campaign.
example: Q1 Sales Campaign
file:
type: string
format: binary
description: (Required) CSV file containing the contact list.
example: contacts.csv
remove_invalid_rows:
type: boolean
description: (Optional) Auto-remove invalid rows from CSV
default: false
example: false
transliterate_callee_name:
type: boolean
description: >-
(Optional) Transliterate callee names to the agent's
language
default: false
example: false
responses:
'200':
description: Contact list uploaded and campaign saved successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Contacts imported successfully!
list_id:
type: string
description: ID of the created campaign list
example: 123e4567-e89b-12d3-a456-426614174000
custom_args_values:
type: array
description: Array of custom variables for each contact
items:
type: object
example:
- callee_name: John Doe
company_name: XYZ Corp
mobile_number: '+1234567890'
total_rows:
type: integer
description: Total number of rows in uploaded CSV
example: 100
successful_rows:
type: integer
description: Number of successfully processed rows
example: 98
failed_rows:
type: integer
description: Number of rows that failed validation
example: 2
'400':
description: Bad Request - Invalid input or file.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: Invalid file format.
'401':
description: Unauthorized - Invalid or missing authentication.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: Invalid credentials
'500':
description: Internal Server Error.
content:
application/json:
schema:
type: object
properties:
detail:
type: string
example: An unexpected error occurred.
````