Initiate Individual Call (Number Pool)
curl --request POST \
--url https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "John Doe",
"mobile_number": "+1234567890",
"agent_id": "00000000-0000-4000-8000-0000000000a1",
"number_pool_id": "00000000-0000-4000-8000-0000000000b1",
"from_number_id": "from-number-id",
"from_number": "+1987654321",
"custom_args_values": {
"company_name": "XYZ Corp",
"appointment_date": "2025-01-20",
"product_name": "Premium Service"
},
"smart_formatter": {
"extract_first_name": true,
"transliteration": true,
"transliteration_language": {
"source": "en",
"target": "hi"
}
},
"call_config": {
"idle_timeout_warning": 10,
"idle_timeout_end": 15,
"max_call_length": 300,
"call_retry_config": {
"retry_count": 3,
"retry_busy": 30,
"retry_not_picked": 30,
"retry_failed": 30
},
"call_time": {
"call_start_time": "00:00",
"call_end_time": "23:00",
"timezone": "Asia/Kolkata",
"scheduled_at": "2026-10-18T15:30:00"
}
},
"voice_id": "voice-uuid-here",
"version_id": "00000000-0000-4000-8000-0000000000d1",
"call_category": "renewal_reminder",
"parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
"purpose": "transactional",
"call_validity_hours": 6,
"call_deadline": "2026-10-18T18:00:00+05:30"
}
'import requests
url = "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual"
payload = {
"name": "John Doe",
"mobile_number": "+1234567890",
"agent_id": "00000000-0000-4000-8000-0000000000a1",
"number_pool_id": "00000000-0000-4000-8000-0000000000b1",
"from_number_id": "from-number-id",
"from_number": "+1987654321",
"custom_args_values": {
"company_name": "XYZ Corp",
"appointment_date": "2025-01-20",
"product_name": "Premium Service"
},
"smart_formatter": {
"extract_first_name": True,
"transliteration": True,
"transliteration_language": {
"source": "en",
"target": "hi"
}
},
"call_config": {
"idle_timeout_warning": 10,
"idle_timeout_end": 15,
"max_call_length": 300,
"call_retry_config": {
"retry_count": 3,
"retry_busy": 30,
"retry_not_picked": 30,
"retry_failed": 30
},
"call_time": {
"call_start_time": "00:00",
"call_end_time": "23:00",
"timezone": "Asia/Kolkata",
"scheduled_at": "2026-10-18T15:30:00"
}
},
"voice_id": "voice-uuid-here",
"version_id": "00000000-0000-4000-8000-0000000000d1",
"call_category": "renewal_reminder",
"parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
"purpose": "transactional",
"call_validity_hours": 6,
"call_deadline": "2026-10-18T18:00:00+05:30"
}
headers = {
"X-API-KEY": "<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': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'John Doe',
mobile_number: '+1234567890',
agent_id: '00000000-0000-4000-8000-0000000000a1',
number_pool_id: '00000000-0000-4000-8000-0000000000b1',
from_number_id: 'from-number-id',
from_number: '+1987654321',
custom_args_values: {
company_name: 'XYZ Corp',
appointment_date: '2025-01-20',
product_name: 'Premium Service'
},
smart_formatter: {
extract_first_name: true,
transliteration: true,
transliteration_language: {source: 'en', target: 'hi'}
},
call_config: {
idle_timeout_warning: 10,
idle_timeout_end: 15,
max_call_length: 300,
call_retry_config: {retry_count: 3, retry_busy: 30, retry_not_picked: 30, retry_failed: 30},
call_time: {
call_start_time: '00:00',
call_end_time: '23:00',
timezone: 'Asia/Kolkata',
scheduled_at: '2026-10-18T15:30:00'
}
},
voice_id: 'voice-uuid-here',
version_id: '00000000-0000-4000-8000-0000000000d1',
call_category: 'renewal_reminder',
parent_call_id: '550e8400-e29b-41d4-a716-446655440000',
purpose: 'transactional',
call_validity_hours: 6,
call_deadline: '2026-10-18T18:00:00+05:30'
})
};
fetch('https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "success",
"data": {
"call_id": "00000000-0000-4000-8000-00000000010b",
"call_direction": "outbound",
"call_status": "ongoing",
"initiated_at": "2025-11-24T07:33:49.629642",
"agent_id": "00000000-0000-4000-8000-000000000115",
"custom_args_values": {
"callee_name": "Priya",
"order_id": "ORD-1042"
}
},
"message": "Call initiated successfully"
}{
"message": "Number pool has no available numbers"
}{
"message": "Invalid credentials"
}{
"message": "Your current balance is insufficient to initiate this call!"
}{
"message": "Provide at least one of: number_pool_id, from_number_id, from_number"
}{
"message": "An unexpected error occurred. Please try again later."
}Initiate Individual Call (Number Pool)
Place one outbound call with an agent and let Ringg pick the caller number from a number pool, or pass a caller number yourself; optionally override the voice.
POST
/
calling
/
v2
/
outbound
/
individual
Initiate Individual Call (Number Pool)
curl --request POST \
--url https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '
{
"name": "John Doe",
"mobile_number": "+1234567890",
"agent_id": "00000000-0000-4000-8000-0000000000a1",
"number_pool_id": "00000000-0000-4000-8000-0000000000b1",
"from_number_id": "from-number-id",
"from_number": "+1987654321",
"custom_args_values": {
"company_name": "XYZ Corp",
"appointment_date": "2025-01-20",
"product_name": "Premium Service"
},
"smart_formatter": {
"extract_first_name": true,
"transliteration": true,
"transliteration_language": {
"source": "en",
"target": "hi"
}
},
"call_config": {
"idle_timeout_warning": 10,
"idle_timeout_end": 15,
"max_call_length": 300,
"call_retry_config": {
"retry_count": 3,
"retry_busy": 30,
"retry_not_picked": 30,
"retry_failed": 30
},
"call_time": {
"call_start_time": "00:00",
"call_end_time": "23:00",
"timezone": "Asia/Kolkata",
"scheduled_at": "2026-10-18T15:30:00"
}
},
"voice_id": "voice-uuid-here",
"version_id": "00000000-0000-4000-8000-0000000000d1",
"call_category": "renewal_reminder",
"parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
"purpose": "transactional",
"call_validity_hours": 6,
"call_deadline": "2026-10-18T18:00:00+05:30"
}
'import requests
url = "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual"
payload = {
"name": "John Doe",
"mobile_number": "+1234567890",
"agent_id": "00000000-0000-4000-8000-0000000000a1",
"number_pool_id": "00000000-0000-4000-8000-0000000000b1",
"from_number_id": "from-number-id",
"from_number": "+1987654321",
"custom_args_values": {
"company_name": "XYZ Corp",
"appointment_date": "2025-01-20",
"product_name": "Premium Service"
},
"smart_formatter": {
"extract_first_name": True,
"transliteration": True,
"transliteration_language": {
"source": "en",
"target": "hi"
}
},
"call_config": {
"idle_timeout_warning": 10,
"idle_timeout_end": 15,
"max_call_length": 300,
"call_retry_config": {
"retry_count": 3,
"retry_busy": 30,
"retry_not_picked": 30,
"retry_failed": 30
},
"call_time": {
"call_start_time": "00:00",
"call_end_time": "23:00",
"timezone": "Asia/Kolkata",
"scheduled_at": "2026-10-18T15:30:00"
}
},
"voice_id": "voice-uuid-here",
"version_id": "00000000-0000-4000-8000-0000000000d1",
"call_category": "renewal_reminder",
"parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
"purpose": "transactional",
"call_validity_hours": 6,
"call_deadline": "2026-10-18T18:00:00+05:30"
}
headers = {
"X-API-KEY": "<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': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'John Doe',
mobile_number: '+1234567890',
agent_id: '00000000-0000-4000-8000-0000000000a1',
number_pool_id: '00000000-0000-4000-8000-0000000000b1',
from_number_id: 'from-number-id',
from_number: '+1987654321',
custom_args_values: {
company_name: 'XYZ Corp',
appointment_date: '2025-01-20',
product_name: 'Premium Service'
},
smart_formatter: {
extract_first_name: true,
transliteration: true,
transliteration_language: {source: 'en', target: 'hi'}
},
call_config: {
idle_timeout_warning: 10,
idle_timeout_end: 15,
max_call_length: 300,
call_retry_config: {retry_count: 3, retry_busy: 30, retry_not_picked: 30, retry_failed: 30},
call_time: {
call_start_time: '00:00',
call_end_time: '23:00',
timezone: 'Asia/Kolkata',
scheduled_at: '2026-10-18T15:30:00'
}
},
voice_id: 'voice-uuid-here',
version_id: '00000000-0000-4000-8000-0000000000d1',
call_category: 'renewal_reminder',
parent_call_id: '550e8400-e29b-41d4-a716-446655440000',
purpose: 'transactional',
call_validity_hours: 6,
call_deadline: '2026-10-18T18:00:00+05:30'
})
};
fetch('https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"status": "success",
"data": {
"call_id": "00000000-0000-4000-8000-00000000010b",
"call_direction": "outbound",
"call_status": "ongoing",
"initiated_at": "2025-11-24T07:33:49.629642",
"agent_id": "00000000-0000-4000-8000-000000000115",
"custom_args_values": {
"callee_name": "Priya",
"order_id": "ORD-1042"
}
},
"message": "Call initiated successfully"
}{
"message": "Number pool has no available numbers"
}{
"message": "Invalid credentials"
}{
"message": "Your current balance is insufficient to initiate this call!"
}{
"message": "Provide at least one of: number_pool_id, from_number_id, from_number"
}{
"message": "An unexpected error occurred. Please try again later."
}The number pool rotates numbers and skips ones flagged as spam.
Caller number
Send at least one of these. Withnumber_pool_id, Ringg picks the number from the pool and ignores the other two. Without a pool, outbound numbers set on the agent version are used before from_number_id or from_number.
| Field | When to use it |
|---|---|
number_pool_id | Ringg picks the number from the pool. Copy the ID with Copy pool ID on the Number pools page. |
from_number_id | A specific workspace number, from List workspace numbers. |
from_number | A specific number written out with country code. |
{
"name": "John Doe",
"mobile_number": "+919876543210",
"agent_id": "your-agent-id",
"number_pool_id": "your-number-pool-id",
"custom_args_values": {
"callee_name": "John",
"order_id": "ORD-1042"
}
}
name, mobile_number, agent_id, custom_args_values, smart_formatter, call_config, version_id, purpose, call_validity_hours and call_deadline work as on Initiate individual call. The response’s data.call_id identifies the call everywhere else.
Troubleshooting
As for Initiate individual call, plus:| Symptom | Check |
|---|---|
422 | No caller number source, or both from_number_id and from_number. |
400 | The pool does not exist (Number pool not found) or has no usable number (Number pool has no available numbers). |
Authorizations
Headers
(Required) Your Ringg AI API key.
Example:
"rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Body
application/json
Send at least one of number_pool_id, from_number_id or from_number. from_number_id and from_number cannot both be set. When number_pool_id is sent, the pool wins.
The name of the person to call.
Example:
"John Doe"
The phone number to call (must include country code).
Example:
"+1234567890"
UUID of the agent that will handle the call.
Example:
"00000000-0000-4000-8000-0000000000a1"
Number pool ID. Ringg picks the caller number from the pool, rotating numbers and skipping ones flagged as spam. When it is sent, from_number_id and from_number are ignored.
Example:
"00000000-0000-4000-8000-0000000000b1"
Workspace number ID, or array of workspace number IDs. Used when no number_pool_id is sent. Send either from_number_id or from_number, not both (422).
Example:
"from-number-id"
Caller phone number, or array of caller phone numbers, with country code. Used when no number_pool_id is sent. Send either from_number or from_number_id, not both (422).
Example:
"+1987654321"
Custom variables replaced in the agent's prompt using @{{variable_name}} syntax.
Example:
{
"company_name": "XYZ Corp",
"appointment_date": "2025-01-20",
"product_name": "Premium Service"
}
(Optional) Smart formatting for callee name — supports first name extraction and transliteration.
Show child attributes
Show child attributes
Example:
{
"extract_first_name": true,
"transliteration": true,
"transliteration_language": { "source": "en", "target": "hi" }
}
(Optional) Override default call configuration.
Show child attributes
Show child attributes
Optional AgentVoice ID for this call. Overrides the agent version's default voice.
Example:
"voice-uuid-here"
Optional agent version ID. Defaults to the active version.
Example:
"00000000-0000-4000-8000-0000000000d1"
Optional category for internal reporting or workflow grouping.
Example:
"renewal_reminder"
Optional parent call ID for follow-up or chained-call flows.
Example:
"550e8400-e29b-41d4-a716-446655440000"
Send transactional so the workspace and agent call limits do not apply to this call. Leave it out for other calls.
Example:
"transactional"
Hours the call may wait before it is cancelled with sub-status DEADLINE_PASSED, counted from when the call is created, or from call_config.call_time.scheduled_at when it is scheduled. When both this and call_deadline are sent, the earlier one applies. A call held by a call limit waits until its deadline; a call with no deadline is cancelled when a limit blocks it (FREQUENCY_CAPPED).
Example:
6
Latest time the call may be placed. After it the call is cancelled with sub-status DEADLINE_PASSED. See call_validity_hours.
Example:
"2026-10-18T18:00:00+05:30"
Was this page helpful?