Initiate Individual Call

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "00000000-0000-4000-8000-0000000000a1",
  "from_number_id": "from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual"

payload = {
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "00000000-0000-4000-8000-0000000000a1",
    "from_number_id": "from-number-id",
    "custom_args_values": {
        "callee_name": "John",
        "order_id": "ORD-1042"
    }
}
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: '+919876543210',
    agent_id: '00000000-0000-4000-8000-0000000000a1',
    from_number_id: 'from-number-id',
    custom_args_values: {callee_name: 'John', order_id: 'ORD-1042'}
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/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",
      "mobile_number": "+919876543210",
      "transfer_to": "+919876543211"
    }
  },
  "message": "Call initiated successfully"
}

{
  "message": "Either from_number_id or from_number must be provided, or configure default outbound numbers on the agent version"
}

{
  "message": "Invalid credentials"
}

{
  "message": "Your current balance is insufficient to initiate this call!"
}

{
  "message": "Provide either from_number_id or from_number, not both"
}

{
  "message": "An unexpected error occurred. Please try again later."
}

POST

calling

outbound

individual

Initiate Individual Call

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "00000000-0000-4000-8000-0000000000a1",
  "from_number_id": "from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual"

payload = {
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "00000000-0000-4000-8000-0000000000a1",
    "from_number_id": "from-number-id",
    "custom_args_values": {
        "callee_name": "John",
        "order_id": "ORD-1042"
    }
}
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: '+919876543210',
    agent_id: '00000000-0000-4000-8000-0000000000a1',
    from_number_id: 'from-number-id',
    custom_args_values: {callee_name: 'John', order_id: 'ORD-1042'}
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/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",
      "mobile_number": "+919876543210",
      "transfer_to": "+919876543211"
    }
  },
  "message": "Call initiated successfully"
}

{
  "message": "Either from_number_id or from_number must be provided, or configure default outbound numbers on the agent version"
}

{
  "message": "Invalid credentials"
}

{
  "message": "Your current balance is insufficient to initiate this call!"
}

{
  "message": "Provide either from_number_id or from_number, not both"
}

{
  "message": "An unexpected error occurred. Please try again later."
}

Use it for calls triggered by an event in your product, such as a missed EMI or a new lead, and to test an agent before a campaign. To have Ringg choose the caller number from a number pool (rotation and spam skipping), use the number-pool variant. agent_id comes from List agents and from_number_id from List workspace numbers. Send from_number_id or from_number, not both. When the agent version has its own outbound numbers, those are used instead, and both fields may be left out. name is used as callee_name when custom_args_values does not set one.

{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "your-agent-id",
  "from_number_id": "your-from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  }
}

The response’s data.call_id identifies the call in call details, call history and webhook payloads. Store it with your own record.

Call settings for this call

call_config overrides the agent’s settings for this call only:

max_call_length (seconds), idle_timeout_warning and idle_timeout_end (seconds of silence);
call_time: call_start_time, call_end_time (HH:MM) and timezone, the window the call may be placed in, and scheduled_at to place the call later;
call_retry_config: retry_count, and the wait in minutes before retrying a busy (retry_busy), unanswered (retry_not_picked) or failed (retry_failed) call.

{
  "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 }
  }
}

Schedule the call

call_config.call_time.scheduled_at places the call later. Write it as a local time without an offset, YYYY-MM-DDTHH:MM:SS, in call_time.timezone (the agent’s timezone when that is not sent). It must be in the future; a time outside the calling window moves to the next opening.

{
  "call_config": {
    "call_time": { "scheduled_at": "2026-10-18T15:30:00", "timezone": "Asia/Kolkata" }
  }
}

The response says “Call has been scheduled successfully for …” and returns data.scheduled_at, data.scheduled_timezone and data.scheduled_time_utc.

Call limits and deadlines

The workspace and agent call limits apply to calls placed by API. The request is still accepted with 200; the limit is checked just before dialling.

call_validity_hours and call_deadline give the call a deadline. A call held by a limit waits until then (call_status registered, call_sub_status FREQUENCY_DEFERRED), and is cancelled with DEADLINE_PASSED if it has not been placed by the deadline. call_validity_hours counts from when the call is created, or from scheduled_at; when both are sent, the earlier deadline applies.
A call with no deadline is cancelled as soon as a limit blocks it (cancelled, FREQUENCY_CAPPED).
purpose: "transactional" marks a transactional call; the call limits do not apply to it.

{
  "call_validity_hours": 6,
  "purpose": "transactional"
}

Name formatting

smart_formatter cleans callee_name before the call. extract_first_name drops titles and keeps the first name (Mr Rajesh Kumar becomes Rajesh). transliteration also converts the name to transliteration_language.target (default hi) and turns on first-name extraction. The original name stays available as original_callee_name in custom_args_values.

{
  "smart_formatter": {
    "extract_first_name": true,
    "transliteration": true,
    "transliteration_language": { "source": "en", "target": "hi" }
  }
}

Troubleshooting

Symptom	Check
`401`	`X-API-KEY` is missing or the key was regenerated.
`400`	No caller number and no outbound numbers on the agent version, a Ringg test number as the caller number, or a missing variable in `custom_args_values`.
`402`	The balance, or the available credit limit, does not cover the call.
`422`	A required field is missing or has the wrong type, or both `from_number_id` and `from_number` are set.
The call stays `registered`	The current time is outside `call_time`, or a call limit is holding it (`call_sub_status` `FREQUENCY_DEFERRED`).
The agent says the wrong name or value	A `custom_args_values` key does not match the variable name in the prompt.

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

Option 1
Option 2

name

string

required

The name of the person to call

Example:

"John Doe"

mobile_number

string

required

The phone number to call (must include country code, e.g., +91 for India)

Example:

"+1234567890"

agent_id

string

required

UUID of the agent that will handle the call

Example:

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

from_number_id

required

Workspace number ID, or array of workspace number IDs, from List workspace numbers. Send either from_number_id or from_number, not both (422).

Example:

"from-number-id"

from_number

Caller phone number, or array of caller phone numbers, with country code. Send either from_number or from_number_id, not both (422).

Example:

"+1987654321"

custom_args_values

object

Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax

Show child attributes

Example:

{
  "company_name": "XYZ Corp",
  "appointment_date": "2025-01-20",
  "product_name": "Premium Service"
}

smart_formatter

object

(Optional) Smart formatting for callee name — supports first name extraction and dictionary-based transliteration

Show child attributes

Example:

{
  "extract_first_name": true,
  "transliteration": true,
  "transliteration_language": { "source": "en", "target": "hi" }
}

call_config

object

(Optional) Override default call configuration

Show child attributes

Example:

{
  "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:59",
    "timezone": "Asia/Kolkata"
  }
}

version_id

string

Optional agent version ID. Defaults to the active version.

Example:

"00000000-0000-4000-8000-0000000000d1"

call_category

string

Optional category for internal reporting or workflow grouping.

Example:

"renewal_reminder"

parent_call_id

string

Optional parent call ID for follow-up or chained-call flows.

Example:

"550e8400-e29b-41d4-a716-446655440000"

purpose

string | null

Send transactional so the workspace and agent call limits do not apply to this call. Leave it out for other calls.

Example:

"transactional"

call_validity_hours

number | null

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

call_deadline

string<date-time> | null

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"

Response

Successful Response: Details about the initiated call.

status

string

Example:

"success"

data

object

Show child attributes

message

string

Example:

"Call initiated successfully"

Introduction

Agents

Inventory

Calling

Monitoring

Account

Initiate Individual Call

Call settings for this call

Schedule the call

Call limits and deadlines

Name formatting

Troubleshooting

Authorizations

Headers

Body

Response

​Call settings for this call

​Schedule the call

​Call limits and deadlines

​Name formatting

​Troubleshooting

Authorizations

Headers

Body

Response

Call settings for this call

Schedule the call

Call limits and deadlines

Name formatting

Troubleshooting