Skip to main content
POST
Call it once the upload status is draft.

​
Fields

country_code must be the same dialling code as the upload. Send exactly one of from_numbers or number_pool_id: both, or neither, returns 422. from_numbers takes workspace number IDs from List workspace numbers; a number that is not in the workspace makes the campaign failed after launch. campaign_start_time and campaign_end_time (DD/MM/YYYY, HH:MM) are required unless call_slots is sent, and go together. email_completion_user_ids are workspace user IDs from List workspace users, emailed when the campaign completes. call_config has two parts:
  • call_time: call_start_time and call_end_time (HH:MM, defaults 09:00 and 21:00) and timezone (default Asia/Kolkata) set the daily calling hours. They replace the agent’s calling window for this campaign. scheduled_at (ISO 8601, in that timezone) schedules the start.
  • call_retry_config: retry_count (default 0, so leaving the block out means no retries) and the wait in minutes before retrying a busy (retry_busy), unanswered (retry_not_picked) or failed (retry_failed) call, each defaulting to 30.

​
Calling slots

call_slots limits dialling to exact windows, in call_time.timezone. Without campaign_start_time and campaign_end_time, the campaign runs from the first slot’s start to the last slot’s end.
  • absolute: dated intervals, each {"start": "DD/MM/YYYY, HH:MM", "end": "DD/MM/YYYY, HH:MM"}, up to 500.
  • weekly: windows of days (mon to sun) with start and end (HH:MM), up to 21, repeated until until (DD/MM/YYYY, HH:MM), at most 90 days ahead.
Each slot lasts 1 minute to 24 hours, is not in the past and sits inside the daily call_time window; the last one must end at least 5 minutes from now. Mixing the two modes returns 422.
concurrency_percentage (0–100) is this campaign’s share of the workspace’s concurrent calls while several campaigns are ongoing; campaigns at 0 share what is left equally.

​
Response

A 402 means the balance does not cover the campaign: it moves to insufficient_balance. Add balance, run Check large campaign balance, then send this request again with the same bulk_list_id. Send each bulk_list_id once. Follow progress with Get all campaigns and the calls with call history filtered by the same bulk_list_id.

Authorizations

​
X-API-KEY
string
header
required

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Body

application/json

Send exactly one of from_numbers or number_pool_id; both or neither returns 422. campaign_start_time and campaign_end_time are required unless call_slots is sent, and must be sent together.

​
bulk_list_id
string
required

Draft bulk list ID returned by /campaign/upload-csv.

Example:

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

​
agent_id
string
required

Agent ID used during upload.

Example:

"00000000-0000-4000-8000-0000000000a1"

​
country_code
string
required

Phone number country code.

Example:

"+91"

​
call_config
object
required
​
campaign_start_time
string

Campaign start time, DD/MM/YYYY, HH:MM, in call_config.call_time.timezone. Required unless call_slots is sent; send it with campaign_end_time.

Example:

"18/10/2026, 09:00"

​
campaign_end_time
string

Campaign end time, DD/MM/YYYY, HH:MM. Required unless call_slots is sent; send it with campaign_start_time.

Example:

"18/10/2026, 18:00"

​
from_numbers
string[] | null

Caller numbers, as workspace number IDs from List workspace numbers (recommended) or as numbers written exactly as listed there. Send exactly one of from_numbers or number_pool_id. A number that is not in the workspace makes the campaign failed after launch.

​
number_pool_id
string | null

Number pool ID. Ringg picks caller numbers from the pool, rotating numbers and skipping ones flagged as spam. Send exactly one of from_numbers or number_pool_id.

Example:

"00000000-0000-4000-8000-0000000000b1"

​
concurrency_percentage
integer
default:0

This campaign's share, in percent, of the workspace's concurrent calls while several campaigns are ongoing. Campaigns at 0 share what is left equally.

Required range: 0 <= x <= 100
Example:

25

​
email_completion_user_ids
string[] | null
​
call_slots
object

(Optional) Exact windows the campaign may dial in, in call_config.call_time.timezone. absolute lists dated intervals (DD/MM/YYYY, HH:MM); weekly repeats day-of-week windows (HH:MM). Each slot is 1 minute to 24 hours, not in the past, and inside the daily call_time window; the last must end at least 5 minutes from now. Without campaign_start_time/campaign_end_time, the campaign runs from the first slot's start to the last slot's end.

Response

Large campaign call creation accepted.

​
message
string
​
bulk_list_id
string
​
status
string