Skip to main content
POST
/
campaign
/
upload-csv
Upload Campaign CSV (Beta)
curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/campaign/upload-csv \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-KEY: <x-api-key>' \
  --form 'variables_map={"mobile_number":"Mobile Number","callee_name":"Name"}' \
  --form agent_id=830f767a-397e-4b39-82ff-235cd344e2f9 \
  --form 'country_code=+91' \
  --form 'campaign_name=Renewal reminders - large upload' \
  --form file='@example-file' \
  --form remove_invalid_rows=true \
  --form transliterate_callee_name=false
{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "verifying",
  "campaign_name": "Renewal reminders - large upload",
  "total_callees": 0,
  "invalidated_rows_count": 0,
  "invalidated_rows_csv_url": null
}

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.

This endpoint is beta. Use it only when large-campaign access is enabled for your workspace. For most campaigns, use Upload campaign contact list and then Start campaign.
POST /campaign/upload-csv starts the beta large-campaign flow. It accepts a large CSV and campaign configuration, then returns a bulk_list_id that you use for status polling, balance checking, and async call scheduling.

​
Endpoint

POST /campaign/upload-csv

​
When to use

Use this endpoint for CSVs with 5,000 or more rows. It lets Ringg process and validate the upload asynchronously instead of making the initial upload request wait for the full import.

​
Request guidance

Send multipart/form-data. Use the same CSV template and campaign fields as the standard POST /campaign/save flow.
FieldRequiredNotes
fileYesCSV file with Mobile Number and assistant variable columns
agent_idYesAssistant that will handle the campaign calls
campaign_nameYesHuman-readable campaign name
country_codeYesDialing prefix, such as +91 or +1
variables_mapYesJSON string mapping assistant variables to CSV columns
campaign_start_timeYesCampaign start time in DD/MM/YYYY, HH:MM format
campaign_end_timeYesCampaign end time in DD/MM/YYYY, HH:MM format
call_configYesJSON string for call window, retry, and call limit settings
remove_invalid_rowsNoSet to true to skip invalid rows when supported
transliterate_callee_nameNoSet to true when callee names should be transliterated
curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/upload-csv" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --form 'agent_id="your-agent-id"' \
  --form 'campaign_name="Renewal reminders - large batch"' \
  --form 'country_code="+91"' \
  --form 'variables_map="{\"mobile_number\":\"Mobile Number\",\"callee_name\":\"Name\"}"' \
  --form 'campaign_start_time="18/10/2026, 09:00"' \
  --form 'campaign_end_time="18/10/2026, 18:00"' \
  --form 'call_config="{\"call_time\":{\"call_start_time\":\"09:00\",\"call_end_time\":\"18:00\",\"timezone\":\"Asia/Kolkata\"}}"' \
  --form "file=@contacts-5000-plus.csv"
Do not set Content-Type manually in browser or Node FormData clients. Let the client include the multipart boundary.

​
Response guidance

Persist the returned bulk_list_id. It identifies the uploaded list for every later beta endpoint. 
{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "uploaded",
  "message": "CSV upload accepted for processing"
}

​
Next step

Poll Get large campaign upload status until the upload is processed. Do not check balance or start calls until processing is complete.

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 assistant variable names to CSV columns.

Example:

"{\"mobile_number\":\"Mobile Number\",\"callee_name\":\"Name\"}"

​
agent_id
string
required

(Required) Assistant ID used to validate campaign variables.

Example:

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

​
country_code
string
required

(Required) Phone number country code, for example +91 or +1.

Example:

"+91"

​
campaign_name
string
required

(Required) Name of the campaign draft.

Example:

"Renewal reminders - large upload"

​
file
file
required

(Required) CSV file containing campaign contacts.

​
remove_invalid_rows
boolean
default:false

When true, invalid rows are removed instead of failing the upload.

Example:

true

​
transliterate_callee_name
boolean
default:false

When true, callee names are transliterated for the assistant language.

Example:

false

Response

CSV upload accepted for asynchronous validation.

​
bulk_list_id
string
Example:

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

​
status
string
Example:

"verifying"

​
campaign_name
string
Example:

"Renewal reminders - large upload"

​
total_callees
integer
Example:

5000

​
invalidated_rows_count
integer
Example:

12

​
invalidated_rows_csv_url
string | null
Example:

"https://storage.example.com/invalid-rows.csv"