Skip to main content
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: <x-api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "+1234567890",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "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:59",
      "timezone": "Asia/Kolkata"
    }
  }
}
'
{
  "status": "success",
  "data": {
    "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
    "call_direction": "outbound",
    "call_status": "ongoing",
    "initiated_at": "2025-11-24T07:33:49.629642",
    "agent_id": "a31f36c4-c8ea-4c4b-9ad6-743dabacafbd",
    "custom_args_values": {
      "callee_name": "abhishek",
      "mobile_number": "+912332423423",
      "transfer_to": "+917404243687"
    }
  },
  "message": "Call initiated successfully"
}

​
Initiate Individual Call

Start a new outbound call to a specific recipient using your configured AI agent. This endpoint supports both immediate calls and scheduled calls for future execution.
Phone Number Format:
  • All phone numbers must include country code (e.g., +91 for India, +1 for US)
  • Invalid formats will result in call failure

​
Scheduled Calls

Use scheduled_at to schedule calls for a specific date and time: 
"call_time": {
  "call_start_time": "09:00",
  "call_end_time": "18:00", 
  "timezone": "Asia/Kolkata",
  "scheduled_at": "2025-11-24T01:55:00"
}
Scheduled Calls: When scheduled_at is provided, the call will be queued and executed at that specific date and time. The time window (call_start_time and call_end_time) still applies as additional validation. Use this for precise scheduling of important calls.

​
Custom Variables

Use the custom_args_values field to pass dynamic data to your agent:
  • Reference variables in your agent prompt using @{{variable_name}} syntax
  • Common variables: callee_name, company_name, appointment_date, etc.
  • Variables are replaced with actual values during the call

​
Smart Formatter

Use smart_formatter to automatically process callee names before the call:
  • extract_first_name: Extracts the first actual name, skipping common prefixes like Mr, Mrs, Dr, Shri, Mohammad, etc.
  • transliteration: Transliterates the extracted name to the target language (e.g., Hindi) using a local dictionary. Automatically enables extract_first_name.
"smart_formatter": {
  "extract_first_name": true,
  "transliteration": true,
  "transliteration_language": {
    "source": "en",
    "target": "hi"
  }
}
For example, with the above config, "Mr Rajesh Kumar" becomes "राजेश" in callee_name, and the original name is preserved in original_callee_name.
When transliteration is enabled, the original name is stored as original_callee_name in custom_args_values for reference. If a name is not found in the dictionary, the original extracted name is used as-is.

​
Important Notes

  • Agent Configuration: Ensure your agent is properly configured with prompts and variables
  • From Numbers: Use phone numbers that are provisioned in your workspace
  • Credits: Each call consumes credits based on duration and destination
  • Retry Logic: Configure retry attempts for busy/failed calls in call_config

Headers

​
X-API-KEY
string
required

(Required) Your Ringg AI API key.

Example:

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

Body

application/json
​
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:

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

​
from_number
string
required

The phone number to call from (with country code)

Example:

"+1987654321"

​
custom_args_values
object

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

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

Example:
{
  "extract_first_name": true,
  "transliteration": true,
  "transliteration_language": { "source": "en", "target": "hi" }
}
​
call_config
object

(Optional) Override default call configuration

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

Response

Successful Response: Details about the initiated call.

​
status
string
Example:

"success"

​
data
object
​
message
string
Example:

"Call initiated successfully"