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": "+919876543210",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "from_number_id": "from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  },
  "callback_url": "https://api.example.com/ringg/callback"
}
'
{
  "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"
}
Deprecated. This endpoint requires you to pass and manage caller numbers yourself via from_number_id or from_number. New integrations should use Initiate Individual Call (Pool), which can resolve numbers automatically from a managed pool (rotation, spam skipping, and auto-purchase).
Start one outbound call with a configured assistant. Use this endpoint for transactional calls, test calls before campaigns, and product workflows where one user action should trigger one phone call.

​
Required inputs

FieldPurpose
nameRecipient name. Ringg also uses this as callee_name if you do not provide one in custom_args_values.
mobile_numberRecipient phone number in E.164 format, for example +919876543210.
agent_idAssistant that will handle the conversation. Get it from GET /agent/all.
from_number_id or from_numberCaller ID to use. Exactly one is required. Use from_number_id when possible because it is stable across number formatting changes.
Provide either from_number_id or from_number, not both. Phone numbers passed as from_number must include country code.

​
Minimal request

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

​
Custom variables

Use custom_args_values to pass dynamic data to your assistant.
  • Reference variables in prompts with @{{variable_name}}.
  • Keep keys stable across your code, prompts, CSV mappings, and analytics.
  • Common keys include callee_name, mobile_number, company_name, appointment_date, and your product-specific IDs.

​
Scheduled calls

Add call_config.call_time.scheduled_at when the call should be queued for a specific date and time. 
{
  "call_config": {
    "call_time": {
      "call_start_time": "09:00",
      "call_end_time": "18:00",
      "timezone": "Asia/Kolkata",
      "scheduled_at": "2026-10-18T10:30:00"
    }
  }
}
call_start_time and call_end_time still act as the allowed calling window in the specified timezone.

​
Retry configuration

Use retry settings when a recipient is busy, does not answer, or the provider fails the call. 
{
  "call_config": {
    "call_retry_config": {
      "retry_count": 1,
      "retry_busy": 30,
      "retry_not_picked": 30,
      "retry_failed": 30
    }
  }
}
The retry delay values are in minutes.

​
Smart formatter

smart_formatter can normalize callee names before the call. 
{
  "smart_formatter": {
    "extract_first_name": true,
    "transliteration": true,
    "transliteration_language": {
      "source": "en",
      "target": "hi"
    }
  }
}
For example, Mr Rajesh Kumar can become Rajesh or a transliterated value in callee_name. The original name is preserved as original_callee_name in custom_args_values.

​
Result handling

Store the returned call ID. Use it to:

​
Common failure checks

SymptomCheck
401 UnauthorizedMissing or invalid X-API-KEY.
Validation errorMissing required field, both from_number_id and from_number provided, or invalid phone number.
Call remains queuedCalling window, scheduled time, workspace credits, or provider health.
Assistant says wrong dataPrompt placeholders do not match custom_args_values keys.

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_id
required

Workspace number ID, or array of workspace number IDs, to use as caller ID. Provide either from_number_id or from_number, not both.

Example:

"from-number-id"

​
from_number

Caller phone number, or array of caller phone numbers, with country code. Provide either from_number or from_number_id, not both.

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"
  }
}
​
callback_url
string

Optional webhook URL for call events for this request.

Example:

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

​
callback_args
object

Optional headers and query params Ringg should include when calling callback_url.

​
version_id
string

Optional assistant version ID. Defaults to the active version.

Example:

"387bd8f1-5748-4006-b7fe-6a6455e9d45d"

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

Response

Successful Response: Details about the initiated call.

​
status
string
Example:

"success"

​
data
object
​
message
string
Example:

"Call initiated successfully"