Make large campaign calls async (Beta)

Start outbound calls for a beta large campaign after upload processing and balance checks.

POST /campaign/make-call-async

Start Large Campaign Calls (Beta)

cURL

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "country_code": "+91",
  "campaign_start_time": "18/10/2026, 09:00",
  "campaign_end_time": "18/10/2026, 18:00",
  "call_config": {
    "call_retry_config": {
      "retry_count": 1,
      "retry_busy": 30,
      "retry_not_picked": 30,
      "retry_failed": 30
    },
    "call_time": {
      "call_start_time": "09:00",
      "call_end_time": "18:00",
      "timezone": "Asia/Kolkata",
      "scheduled_at": null
    }
  },
  "from_numbers": [
    "from-number-id"
  ],
  "number_pool_id": "pool-uuid-here",
  "concurrency_percentage": 25,
  "callback_url": "https://api.example.com/ringg/campaign-callback",
  "email_completion_user_ids": [
    "<string>"
  ]
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async"

payload = {
    "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
    "country_code": "+91",
    "campaign_start_time": "18/10/2026, 09:00",
    "campaign_end_time": "18/10/2026, 18:00",
    "call_config": {
        "call_retry_config": {
            "retry_count": 1,
            "retry_busy": 30,
            "retry_not_picked": 30,
            "retry_failed": 30
        },
        "call_time": {
            "call_start_time": "09:00",
            "call_end_time": "18:00",
            "timezone": "Asia/Kolkata",
            "scheduled_at": None
        }
    },
    "from_numbers": ["from-number-id"],
    "number_pool_id": "pool-uuid-here",
    "concurrency_percentage": 25,
    "callback_url": "https://api.example.com/ringg/campaign-callback",
    "email_completion_user_ids": ["<string>"]
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bulk_list_id: '123e4567-e89b-12d3-a456-426614174000',
    agent_id: '830f767a-397e-4b39-82ff-235cd344e2f9',
    country_code: '+91',
    campaign_start_time: '18/10/2026, 09:00',
    campaign_end_time: '18/10/2026, 18:00',
    call_config: {
      call_retry_config: {retry_count: 1, retry_busy: 30, retry_not_picked: 30, retry_failed: 30},
      call_time: {
        call_start_time: '09:00',
        call_end_time: '18:00',
        timezone: 'Asia/Kolkata',
        scheduled_at: null
      }
    },
    from_numbers: ['from-number-id'],
    number_pool_id: 'pool-uuid-here',
    concurrency_percentage: 25,
    callback_url: 'https://api.example.com/ringg/campaign-callback',
    email_completion_user_ids: ['<string>']
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'bulk_list_id' => '123e4567-e89b-12d3-a456-426614174000',
    'agent_id' => '830f767a-397e-4b39-82ff-235cd344e2f9',
    'country_code' => '+91',
    'campaign_start_time' => '18/10/2026, 09:00',
    'campaign_end_time' => '18/10/2026, 18:00',
    'call_config' => [
        'call_retry_config' => [
                'retry_count' => 1,
                'retry_busy' => 30,
                'retry_not_picked' => 30,
                'retry_failed' => 30
        ],
        'call_time' => [
                'call_start_time' => '09:00',
                'call_end_time' => '18:00',
                'timezone' => 'Asia/Kolkata',
                'scheduled_at' => null
        ]
    ],
    'from_numbers' => [
        'from-number-id'
    ],
    'number_pool_id' => 'pool-uuid-here',
    'concurrency_percentage' => 25,
    'callback_url' => 'https://api.example.com/ringg/campaign-callback',
    'email_completion_user_ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async"

	payload := strings.NewReader("{\n  \"bulk_list_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"country_code\": \"+91\",\n  \"campaign_start_time\": \"18/10/2026, 09:00\",\n  \"campaign_end_time\": \"18/10/2026, 18:00\",\n  \"call_config\": {\n    \"call_retry_config\": {\n      \"retry_count\": 1,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"09:00\",\n      \"call_end_time\": \"18:00\",\n      \"timezone\": \"Asia/Kolkata\",\n      \"scheduled_at\": null\n    }\n  },\n  \"from_numbers\": [\n    \"from-number-id\"\n  ],\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"concurrency_percentage\": 25,\n  \"callback_url\": \"https://api.example.com/ringg/campaign-callback\",\n  \"email_completion_user_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"bulk_list_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"country_code\": \"+91\",\n  \"campaign_start_time\": \"18/10/2026, 09:00\",\n  \"campaign_end_time\": \"18/10/2026, 18:00\",\n  \"call_config\": {\n    \"call_retry_config\": {\n      \"retry_count\": 1,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"09:00\",\n      \"call_end_time\": \"18:00\",\n      \"timezone\": \"Asia/Kolkata\",\n      \"scheduled_at\": null\n    }\n  },\n  \"from_numbers\": [\n    \"from-number-id\"\n  ],\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"concurrency_percentage\": 25,\n  \"callback_url\": \"https://api.example.com/ringg/campaign-callback\",\n  \"email_completion_user_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bulk_list_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"country_code\": \"+91\",\n  \"campaign_start_time\": \"18/10/2026, 09:00\",\n  \"campaign_end_time\": \"18/10/2026, 18:00\",\n  \"call_config\": {\n    \"call_retry_config\": {\n      \"retry_count\": 1,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"09:00\",\n      \"call_end_time\": \"18:00\",\n      \"timezone\": \"Asia/Kolkata\",\n      \"scheduled_at\": null\n    }\n  },\n  \"from_numbers\": [\n    \"from-number-id\"\n  ],\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"concurrency_percentage\": 25,\n  \"callback_url\": \"https://api.example.com/ringg/campaign-callback\",\n  \"email_completion_user_ids\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

200

{
  "message": "Campaign calls scheduled",
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "scheduled"
}

{
  "detail": "Bulk list is not ready to start."
}

This endpoint is beta. Use it only after Get large campaign upload status shows processing is complete and Check large campaign balance confirms sufficient balance.

POST /campaign/make-call-async queues outbound calls for a beta large campaign. Use it instead of POST /campaign/start for 5,000+ row campaigns created with POST /campaign/upload-csv.

Endpoint

POST /campaign/make-call-async

Request body

Send JSON.

Field	Required	Description
agent_id	Yes	Assistant that will handle the campaign calls
bulk_list_id	Yes	Large campaign list ID returned by POST /campaign/upload-csv
from_numbers	Yes	Workspace caller numbers or number IDs to use for outbound calls
callback_url	No	URL that should receive post-call events, if configured

curl --request POST "https://prod-api.ringg.ai/ca/api/v0/campaign/make-call-async" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agent_id": "your-agent-id",
    "bulk_list_id": "your-bulk-list-id",
    "from_numbers": ["your-from-number-id"],
    "callback_url": "https://api.example.com/ringg/campaign-callback"
  }'

Response guidance

A successful response means the large campaign was accepted for async scheduling.

{
  "bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "scheduled",
  "message": "Large campaign calls queued"
}

Avoid submitting the same bulk_list_id more than once unless a previous attempt clearly failed.

Next step

Monitor progress with Get all campaigns and inspect call rows with Get call history filtered by the same bulk_list_id.

Headers

X-API-KEY · string · required

(Required) Your Ringg AI API key.

Example:

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

Body

application/json

Exactly one of from_numbers or number_pool_id must be provided. Sending both or neither results in a 422.

bulk_list_id · string · required

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

Example:

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

agent_id · string · required

Assistant ID used during upload.

Example:

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

country_code · string · required

Phone number country code.

Example:

"+91"

campaign_start_time · string · required

Campaign start time in DD/MM/YYYY, HH:MM format.

Example:

"18/10/2026, 09:00"

campaign_end_time · string · required

Campaign end time in DD/MM/YYYY, HH:MM format.

Example:

"18/10/2026, 18:00"

call_config · object · required

Show child attributes

from_numbers · string[] | null

Explicit list of FromNumber UUIDs / phone numbers. Provide exactly one of from_numbers or number_pool_id.

Example:

["from-number-id"]

number_pool_id · string | null

Managed number pool ID (rotation, spam skipping, auto-purchase). Provide exactly one of from_numbers or number_pool_id.

Example:

"pool-uuid-here"

concurrency_percentage · integer · default: 0

Required range: 0 <= x <= 100

Example:

25

callback_url · string | null

Example:

"https://api.example.com/ringg/campaign-callback"

email_completion_user_ids · string[] | null

Response

200

application/json

Large campaign call creation accepted.

message · string

bulk_list_id · string

status · string