Upload Campaign Contact List

POST

campaign

save

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
}

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

Prepare your CSV - Download template from your campaigns tab
Configure your agent - Set up prompts and custom variables
Upload & configure - Submit CSV with campaign settings
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:

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

Save the list_id from the response
Start your campaign using the list_id
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

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

Start CampaignInitiates a new campaign with the specified configuration.

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

​Quick start

​CSV file requirements

​Example CSV Structure

​Configuration parameters

​Required Fields

​Optional Settings

​CSV File Format

​Variable mapping

​How It Works

​Using Variables

​Call configuration

​Call timing and limits

​Retry settings

​What happens next?

​Success Response

​Next Steps

​Error Handling

Headers

Body

Response

Quick start

CSV file requirements

Example CSV Structure

Configuration parameters

Required Fields

Optional Settings

CSV File Format

Variable mapping

How It Works

Using Variables

Call configuration

Call timing and limits

Retry settings

What happens next?

Success Response

Next Steps

Error Handling