> ## Documentation Index
> Fetch the complete documentation index at: https://docs.revenueable.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 new campaign. Once uploaded, you can start the campaign to begin making calls.
## 📋 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 (e.g., +91xxxxxxxxxx)
* ✅ Download exact template from campaigns 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** | 2-letter code | "IN", "US" |
| **Start Time** | DD/MM/YYYY, HH:MM | 18/10/2025, 09:00 |
| **End Time** | DD/MM/YYYY, HH:MM | 18/10/2025, 21:00 |
### Optional Settings
| Setting | Default | Purpose |
| ------------------- | ------- | -------------------- |
| Remove Invalid Rows | false | Auto-remove bad data |
| Transliterate Names | 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.
## 🔗 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}}` → "John Doe"
* `@{{company_name}}` → "XYZ Corp"
## ⏰ Call Configuration
Control when and how your campaign calls are made:
📞 Call Timing & 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 this!** You need it to start your 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
### 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
**💡 Pro Tip**: 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: Revenueable AI API Documentation
description: >-
This is the documentation for the Revenueable AI APIs. The Revenueable 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.revenueable.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 Revenueable AI API key.
required: true
schema:
type: string
example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
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) Country code for the campaign
example: US
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
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.
````