> ## 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.
> ## Agent Instructions
> To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md
> The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id.
> API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only.
> Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling.
> To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md
# Make large campaign calls async (Beta)
> Schedule the calls of a validated large campaign: set the campaign window, calling hours, retries and caller numbers or a number pool for the bulk_list_id.
export const RelatedTopics = ({items}) =>
;
Call it once the [upload status](/api-reference/calling/large-campaigns/get-large-campaign-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](/api-reference/inventory/numbers/get-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](/api-reference/account/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`.
```bash theme={null}
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 '{
"bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
"agent_id": "your-agent-id",
"country_code": "+91",
"campaign_start_time": "18/10/2026, 09:00",
"campaign_end_time": "18/10/2026, 18:00",
"number_pool_id": "your-number-pool-id",
"call_config": {
"call_time": { "call_start_time": "09:00", "call_end_time": "18:00", "timezone": "Asia/Kolkata" },
"call_retry_config": { "retry_count": 1, "retry_busy": 30, "retry_not_picked": 30, "retry_failed": 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`.
```json theme={null}
{
"call_slots": {
"mode": "weekly",
"until": "31/10/2026, 18:00",
"windows": [{ "days": ["mon", "wed", "fri"], "start": "10:00", "end": "13:00" }]
}
}
```
`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
```json theme={null}
{
"message": "Campaign calls scheduled",
"bulk_list_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "scheduled"
}
```
A `402` means the balance does not cover the campaign: it moves to `insufficient_balance`. Add balance, run [Check large campaign balance](/api-reference/calling/large-campaigns/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](/api-reference/calling/campaigns/get-all-campaigns) and the calls with [call history](/api-reference/monitoring/call-history/get-call-history) filtered by the same `bulk_list_id`.
## OpenAPI
````yaml post /campaign/make-call-async
openapi: 3.0.0
info:
title: Ringg AI API Documentation
description: >-
The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send
your workspace API key in the X-API-KEY header from server-side code only.
Requests and responses are JSON.
version: 2.0.0
contact:
name: Ringg AI support
email: admin@ringg.ai
url: https://docs.ringg.ai
servers:
- url: https://prod-api.ringg.ai/ca/api/v0
security: []
tags:
- name: workspace
description: Endpoints for managing your workspace.
- name: agent
description: Endpoints for managing agents.
- name: calling
description: Endpoints for making and managing calls.
- name: campaign
description: Endpoints for managing campaigns.
- name: analytics
description: Endpoints for accessing call analytics and performance metrics.
- name: termination
description: Endpoints for terminating active calls using different methods.
- name: knowledgebase
description: Endpoints for managing knowledge bases.
paths:
/campaign/make-call-async:
post:
tags:
- campaign
summary: Start Large Campaign Calls (Beta)
description: >-
Beta endpoint for starting calls from a draft bulk list created by
/campaign/upload-csv.
operationId: makeCampaignCallAsyncBeta
parameters:
- name: X-API-KEY
in: header
description: (Required) Your Ringg AI API key.
required: true
schema:
type: string
example: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- bulk_list_id
- agent_id
- country_code
- call_config
properties:
bulk_list_id:
type: string
description: Draft bulk list ID returned by /campaign/upload-csv.
example: 123e4567-e89b-12d3-a456-426614174000
agent_id:
type: string
description: Agent ID used during upload.
example: 00000000-0000-4000-8000-0000000000a1
country_code:
type: string
description: Phone number country code.
example: '+91'
campaign_start_time:
type: string
description: >-
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:
type: string
description: >-
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:
type: array
items:
type: string
nullable: true
description: >-
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:
type: string
nullable: true
description: >-
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
call_config:
type: object
properties:
call_retry_config:
type: object
properties:
retry_count:
type: integer
default: 0
example: 1
retry_busy:
type: integer
default: 30
example: 30
retry_not_picked:
type: integer
default: 30
example: 30
retry_failed:
type: integer
default: 30
example: 30
description: >-
Retries for unanswered, busy and failed calls. Without
it the campaign makes no retries.
call_time:
type: object
properties:
call_start_time:
type: string
default: '09:00'
example: '09:00'
call_end_time:
type: string
default: '21:00'
example: '18:00'
timezone:
type: string
default: Asia/Kolkata
example: Asia/Kolkata
scheduled_at:
type: string
nullable: true
description: >-
ISO 8601 datetime for scheduled call (e.g.
'2026-10-18T09:00:00'). Uses the timezone above.
example: null
concurrency_percentage:
type: integer
minimum: 0
maximum: 100
default: 0
example: 25
description: >-
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.
email_completion_user_ids:
type: array
items:
type: string
nullable: true
call_slots:
description: >-
(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.
oneOf:
- type: object
required:
- mode
- intervals
properties:
mode:
type: string
enum:
- absolute
intervals:
type: array
maxItems: 500
items:
type: object
required:
- start
- end
properties:
start:
type: string
example: 18/10/2026, 10:00
end:
type: string
example: 18/10/2026, 13:00
- type: object
required:
- mode
- until
- windows
properties:
mode:
type: string
enum:
- weekly
until:
type: string
description: >-
`DD/MM/YYYY, HH:MM`. Windows repeat from
`campaign_start_time` (or now) until this time, at
most 90 days.
example: 31/10/2026, 18:00
windows:
type: array
maxItems: 21
items:
type: object
required:
- days
- start
- end
properties:
days:
type: array
items:
type: string
enum:
- mon
- tue
- wed
- thu
- fri
- sat
- sun
example:
- mon
- wed
- fri
start:
type: string
example: '10:00'
end:
type: string
example: '13:00'
description: >-
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.
examples:
number_pool:
summary: Caller numbers from a number pool
value:
bulk_list_id: 123e4567-e89b-12d3-a456-426614174000
agent_id: 00000000-0000-4000-8000-0000000000a1
country_code: '+91'
campaign_start_time: 18/10/2026, 09:00
campaign_end_time: 18/10/2026, 18:00
number_pool_id: 00000000-0000-4000-8000-0000000000b1
call_config:
call_time:
call_start_time: '09:00'
call_end_time: '18:00'
timezone: Asia/Kolkata
call_retry_config:
retry_count: 1
retry_busy: 30
retry_not_picked: 30
retry_failed: 30
from_numbers:
summary: Caller numbers you list
value:
bulk_list_id: 123e4567-e89b-12d3-a456-426614174000
agent_id: 00000000-0000-4000-8000-0000000000a1
country_code: '+91'
campaign_start_time: 18/10/2026, 09:00
campaign_end_time: 18/10/2026, 18:00
from_numbers:
- 00000000-0000-4000-8000-0000000000c1
call_config:
call_time:
call_start_time: '09:00'
call_end_time: '18:00'
timezone: Asia/Kolkata
call_retry_config:
retry_count: 1
retry_busy: 30
retry_not_picked: 30
retry_failed: 30
responses:
'200':
description: Large campaign call creation accepted.
content:
application/json:
schema:
type: object
properties:
message:
type: string
bulk_list_id:
type: string
status:
type: string
example:
message: Campaign calls scheduled
bulk_list_id: 123e4567-e89b-12d3-a456-426614174000
status: scheduled
'400':
description: Bad Request - Invalid input.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Bulk list is not ready to start.
'401':
description: Unauthorized - Invalid or missing authentication.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Invalid credentials
'402':
description: >-
Payment Required - The balance (or available credit limit) does not
cover the campaign. The campaign is set to `insufficient_balance`;
add balance, call Check Campaign Balance, then send this request
again.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
Insufficient balance to start this campaign. Please top up
and use /check-balance to re-verify.
'422':
description: >-
Validation Error - Both or neither of `from_numbers` and
`number_pool_id`, only one of `campaign_start_time` and
`campaign_end_time`, invalid `call_slots`, or a field with the wrong
type.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: >-
Provide exactly one of from_numbers / number_pool_id, not
both
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.