Skip to main content
POST
/
campaign
/
save
Upload Campaign Contact List
curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/campaign/save \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-KEY: <x-api-key>' \
  --form 'variables_map={
  "callee_name": "Name",
  "company_name": "Company"
}' \
  --form agent_id=830f767a-397e-4b39-82ff-235cd344e2f9 \
  --form 'call_config={
  "idle_timeout_warning": 10,
  "max_call_length": 300
}' \
  --form country_code=US \
  --form 'campaign_start_time=18/10/2025, 09:00' \
  --form 'campaign_end_time=18/10/2025, 21:05' \
  --form 'campaign_name=Q1 Sales Campaign' \
  --form file='@example-file'
{
  "message": "Contacts imported successfully!",
  "list_id": "123e4567-e89b-12d3-a456-426614174000",
  "custom_args_values": [
    {
      "callee_name": "John Doe",
      "company_name": "XYZ Corp",
      "mobile_number": "+1234567890"
    }
  ],
  "total_rows": 100,
  "successful_rows": 98,
  "failed_rows": 2
}

​
Upload Campaign Contact List

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,[email protected]
+918882876898,Jane Smith,ABC Inc,[email protected]

​
⚙️ Configuration Parameters

​
Required Fields

FieldFormatExample
CSV File.csv filecontacts.csv
Agent IDUUID830f767a-397e-4b39-82ff-235cd344e2f9
Campaign NameText”Q1 Sales Outreach”
Country Code2-letter code”IN”, “US”
Start TimeDD/MM/YYYY, HH:MM18/10/2025, 09:00
End TimeDD/MM/YYYY, HH:MM18/10/2025, 21:00

​
Optional Settings

SettingDefaultPurpose
Remove Invalid RowsfalseAuto-remove bad data
Transliterate NamesfalseConvert 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: 
{
  "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:

​
✅ What Happens Next?

​
Success Response

You’ll receive a list_id - save this! You need it to start your campaign. 
{
  "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 using the list_id
  3. Monitor progress 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.

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Body

multipart/form-data
​
variables_map
string

(Required) JSON string mapping variable names to columns

Example:
{
  "callee_name": "Name",
  "company_name": "Company"
}
​
agent_id
string

(Required) Unique identifier for the agent

Example:

"830f767a-397e-4b39-82ff-235cd344e2f9"

​
call_config
string

(Required) JSON string of call configuration

Example:
{
  "idle_timeout_warning": 10,
  "max_call_length": 300
}
​
country_code
string

(Required) Country code for the campaign

Example:

"US"

​
campaign_start_time
string

(Required) Start time for the campaign (DD/MM/YYYY, HH:MM format)

Example:

"18/10/2025, 09:00"

​
campaign_end_time
string

(Required) End time for the campaign (DD/MM/YYYY, HH:MM format)

Example:

"18/10/2025, 21:05"

​
campaign_name
string

(Required) Name of the campaign.

Example:

"Q1 Sales Campaign"

​
file
file

(Required) CSV file containing the contact list.

Example:

"contacts.csv"

Response

Contact list uploaded and campaign saved successfully.

​
message
string
Example:

"Contacts imported successfully!"

​
list_id
string

ID of the created campaign list

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
custom_args_values
object[]

Array of custom variables for each contact

Example:
[
  {
    "callee_name": "John Doe",
    "company_name": "XYZ Corp",
    "mobile_number": "+1234567890"
  }
]
​
total_rows
integer

Total number of rows in uploaded CSV

Example:

100

​
successful_rows
integer

Number of successfully processed rows

Example:

98

​
failed_rows
integer

Number of rows that failed validation

Example:

2