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=+91' \
  --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' \
  --form remove_invalid_rows=false \
  --form transliterate_callee_name=false
{
  "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
}

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

FieldFormatExample
CSV File.csv filecontacts.csv
Agent IDUUID830f767a-397e-4b39-82ff-235cd344e2f9
Campaign NameText”Q1 Sales Outreach”
Country CodePhone dialing prefix”+91”, “+1”
Campaign Start TimeDD/MM/YYYY, HH:MM18/10/2026, 09:00
Campaign End TimeDD/MM/YYYY, HH:MM18/10/2026, 21:00

​
Optional Settings

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

{
  "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

{
  "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. 
{
  "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
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.

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

(Required) JSON string mapping variable names to columns

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

(Required) Unique identifier for the agent

Example:

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

​
call_config
string
required

(Required) JSON string of call configuration

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

(Required) Phone number country code (e.g., +91 for India, +1 for US)

Example:

"+91"

​
campaign_start_time
string
required

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

Example:

"18/10/2025, 09:00"

​
campaign_end_time
string
required

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

Example:

"18/10/2025, 21:05"

​
campaign_name
string
required

(Required) Name of the campaign.

Example:

"Q1 Sales Campaign"

​
file
file
required

(Required) CSV file containing the contact list.

​
remove_invalid_rows
boolean
default:false

(Optional) Auto-remove invalid rows from CSV

Example:

false

​
transliterate_callee_name
boolean
default:false

(Optional) Transliterate callee names to the agent's language

Example:

false

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