> ## 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.
# Initiate Individual Call
> Starts one outbound call to a recipient. **Exactly one caller-number option is required: from_number_id or from_number.**
**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)](/api-reference/endpoint/calling/initiate-individual-call-v2), 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
| Field | Purpose |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Recipient name. Ringg also uses this as `callee_name` if you do not provide one in `custom_args_values`. |
| `mobile_number` | Recipient phone number in E.164 format, for example `+919876543210`. |
| `agent_id` | Assistant that will handle the conversation. Get it from `GET /agent/all`. |
| `from_number_id` or `from_number` | Caller 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
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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:
* Match webhook events to your internal record.
* Fetch details with [Get call details](/api-reference/endpoint/history/get-call-details).
* Reconcile rows from [Get call history](/api-reference/endpoint/history/get-call-history).
## Common failure checks
| Symptom | Check |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid `X-API-KEY`. |
| Validation error | Missing required field, both `from_number_id` and `from_number` provided, or invalid phone number. |
| Call remains queued | Calling window, scheduled time, workspace credits, or provider health. |
| Assistant says wrong data | Prompt placeholders do not match `custom_args_values` keys. |
## OpenAPI
````yaml post /calling/outbound/individual
openapi: 3.0.0
info:
title: Ringg AI API Documentation
description: >-
This is the documentation for the Ringg AI APIs. The Ringg AI API follows
RESTful principles, making it intuitive and easy to integrate with your
applications. All API requests should be made to the base URL. The API
accepts and returns data in JSON format. Ensure your requests include the
appropriate Content-Type header for POST and PATCH requests.
version: 2.0.0
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 assistants (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:
/calling/outbound/individual:
post:
tags:
- calling
summary: Initiate Individual Call
description: >-
Starts one outbound call to a recipient. **Exactly one caller-number
option is required: from_number_id or from_number.**
operationId: initiateIndividualCall
parameters:
- name: X-API-KEY
in: header
description: (Required) Your Ringg AI API key.
required: true
schema:
type: string
example: 7251cb4b-3373-43a4-844c-b27a1d45e0c9
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- mobile_number
- agent_id
properties:
name:
type: string
description: The name of the person to call
example: John Doe
mobile_number:
type: string
description: >-
The phone number to call (must include country code, e.g.,
+91 for India)
example: '+1234567890'
agent_id:
type: string
description: UUID of the agent that will handle the call
example: 830f767a-397e-4b39-82ff-235cd344e2f9
from_number:
oneOf:
- type: string
- type: array
items:
type: string
description: >-
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:
type: object
description: >-
Custom variables that will be replaced in the agent's prompt
using @{{variable_name}} syntax
properties:
company_name:
type: string
description: Company name for context
example: XYZ Corp
appointment_date:
type: string
description: Appointment date
example: '2025-01-20'
product_name:
type: string
description: Product name for sales calls
example: Premium Service
example:
company_name: XYZ Corp
appointment_date: '2025-01-20'
product_name: Premium Service
smart_formatter:
type: object
description: >-
(Optional) Smart formatting for callee name — supports first
name extraction and dictionary-based transliteration
properties:
extract_first_name:
type: boolean
description: >-
Extract the first actual name from the full name,
skipping common prefixes (Mr, Mrs, Dr, etc.)
default: false
example: true
transliteration:
type: boolean
description: >-
Transliterate the extracted name to the target language
using a local dictionary. When enabled,
extract_first_name is automatically applied.
default: false
example: true
transliteration_language:
type: object
description: Language configuration for transliteration
properties:
source:
type: string
description: 'Source language code (default: en)'
default: en
example: en
target:
type: string
description: 'Target language code (default: hi)'
default: hi
example: hi
example:
source: en
target: hi
example:
extract_first_name: true
transliteration: true
transliteration_language:
source: en
target: hi
call_config:
type: object
description: (Optional) Override default call configuration
properties:
idle_timeout_warning:
type: integer
description: 'Seconds before idle warning (default: 5)'
default: 5
example: 10
idle_timeout_end:
type: integer
description: 'Seconds before call termination (default: 10)'
default: 10
example: 15
max_call_length:
type: integer
description: 'Maximum call duration in seconds (default: 240)'
default: 240
example: 300
call_retry_config:
type: object
description: Retry configuration for failed calls
properties:
retry_count:
type: integer
description: Number of retry attempts
example: 3
retry_busy:
type: integer
description: 'Minutes to wait if busy (default: 30)'
example: 30
retry_not_picked:
type: integer
description: 'Minutes to wait if not picked (default: 30)'
example: 30
retry_failed:
type: integer
description: 'Minutes to wait if failed (default: 30)'
example: 30
example:
retry_count: 3
retry_busy: 30
retry_not_picked: 30
retry_failed: 30
call_time:
type: object
description: Time window configuration for calls
properties:
call_start_time:
type: string
description: 'When calls can start (default: 00:00)'
default: '00:00'
example: '00:00'
call_end_time:
type: string
description: 'When calls must end (default: 23:00)'
default: '23:00'
example: '23:00'
timezone:
type: string
description: 'Timezone for call times (default: Asia/Kolkata)'
default: Asia/Kolkata
example: Asia/Kolkata
example:
call_start_time: '00:00'
call_end_time: '23:59'
timezone: Asia/Kolkata
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
from_number_id:
oneOf:
- type: string
- type: array
items:
type: string
description: >-
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
callback_url:
type: string
description: Optional webhook URL for call events for this request.
example: https://api.example.com/ringg/callback
callback_args:
type: object
description: >-
Optional headers and query params Ringg should include when
calling callback_url.
properties:
headers:
type: object
additionalProperties:
type: string
params:
type: object
additionalProperties:
type: string
version_id:
type: string
description: >-
Optional assistant version ID. Defaults to the active
version.
example: 387bd8f1-5748-4006-b7fe-6a6455e9d45d
call_category:
type: string
description: >-
Optional category for internal reporting or workflow
grouping.
example: renewal_reminder
parent_call_id:
type: string
description: Optional parent call ID for follow-up or chained-call flows.
example: 550e8400-e29b-41d4-a716-446655440000
oneOf:
- required:
- from_number_id
- required:
- from_number
example:
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
responses:
'200':
description: 'Successful Response: Details about the initiated call.'
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: success
data:
type: object
properties:
call_id:
type: string
example: 31106b7c-9d02-4723-8b07-5bb8d90240cb
call_direction:
type: string
example: outbound
call_status:
type: string
description: The current status of the call
enum:
- registered
- ongoing
- retry
- error
- completed
- failed
- cancelled
- forwarded
example: ongoing
initiated_at:
type: string
format: date-time
example: '2025-11-24T07:33:49.629642'
agent_id:
type: string
example: a31f36c4-c8ea-4c4b-9ad6-743dabacafbd
custom_args_values:
type: object
description: Custom variables passed in the request
example:
callee_name: abhishek
mobile_number: '+912332423423'
transfer_to: '+917404243687'
message:
type: string
example: Call initiated successfully
'400':
description: Bad Request - Invalid parameters or request format.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: invalid_parameter
message:
type: string
example: Missing required field
'401':
description: Unauthorized - Invalid or missing API key.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: 401 Unauthorized
message:
type: string
example: Invalid credentials
'500':
description: Internal Server Error - Something went wrong on our end.
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
example: 500 Internal Server Error
message:
type: string
example: An unexpected error occurred on the server.
````