> ## 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. > ## Agent Instructions > To search or read these docs, connect the Ringg docs MCP server at https://docs.ringg.ai/mcp (no key needed; tools search_ringg_ai and query_docs_filesystem_ringg_ai) instead of browsing pages one by one. Setup for each client: https://docs.ringg.ai/resources/mcp-server/docs-mcp-server/mcp-for-ai-assistants.md > The dashboard labels agents "Assistants"; these docs say "agent". Both mean the same object, identified by agent_id. > API base URL: https://prod-api.ringg.ai/ca/api/v0. Send the workspace API key in the X-API-KEY header, from server-side code only. > Placing a call dials a real phone number and spends credits. Confirm the number with the user before calling. > To act on a Ringg workspace (place calls, edit agents, read transcripts), use the separate Ringg workspace MCP server at https://mcp.ringg.ai/mcp: https://docs.ringg.ai/resources/mcp-server/workspace-mcp-server/overview.md > Place one outbound call with an agent to one phone number, passing a caller number, the variables the prompt uses, and optional retry and timing settings. # Initiate Individual Call export const RelatedTopics = ({items}) =>
Related topics
{items.map(([title, href]) => {title} )}
; 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](/documentation/build-agents/test-and-improve/test-an-agent) before a campaign. To have Ringg choose the caller number from a [number pool](/documentation/inventory/phone-numbers/number-pools) (rotation and spam skipping), use the [number-pool variant](/api-reference/calling/individual-calls/initiate-individual-call-v2). `agent_id` comes from [List agents](/api-reference/agents/get-assistants) and `from_number_id` from [List workspace numbers](/api-reference/inventory/numbers/get-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. ```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" } } ``` The response's `data.call_id` identifies the call in [call details](/api-reference/monitoring/call-history/get-call-details), [call history](/api-reference/monitoring/call-history/get-call-history) and [webhook payloads](/documentation/build-agents/customize-agent-behaviour/webhooks/call-events). 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. ```json theme={null} { "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. ```json theme={null} { "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](/documentation/manage-account/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. ```json theme={null} { "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`. ```json theme={null} { "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. | ## OpenAPI ````yaml post /calling/outbound/individual openapi: 3.0.0 info: title: Ringg AI API Documentation description: >- The Ringg AI REST API. Base URL https://prod-api.ringg.ai/ca/api/v0; send your workspace API key in the X-API-KEY header from server-side code only. Requests and responses are JSON. version: 2.0.0 contact: name: Ringg AI support email: admin@ringg.ai url: https://docs.ringg.ai 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 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. Send `from_number_id` or `from_number` as the caller number, not both. Both may be left out when the agent version has its own outbound numbers; those numbers also take precedence over the request's caller number. operationId: initiateIndividualCall parameters: - name: X-API-KEY in: header description: (Required) Your Ringg AI API key. required: true schema: type: string example: rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 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: 00000000-0000-4000-8000-0000000000a1 from_number: oneOf: - type: string - type: array items: type: string description: >- 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: 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 scheduled_at: type: string nullable: true description: >- Schedule the call: a local date and time without an offset, `YYYY-MM-DDTHH:MM:SS`, read in `timezone` (the agent's timezone when `timezone` is not sent). It must be in the future. A time outside `call_start_time`–`call_end_time` moves to the next opening. example: '2026-10-18T15:30:00' 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, from List workspace numbers. Send either `from_number_id` or `from_number`, not both (422). example: from-number-id version_id: type: string description: Optional agent version ID. Defaults to the active version. example: 00000000-0000-4000-8000-0000000000d1 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 purpose: type: string nullable: true description: >- Send `transactional` so the workspace and agent [call limits](/documentation/manage-account/call-limits) do not apply to this call. Leave it out for other calls. example: transactional call_validity_hours: type: number nullable: true description: >- 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: type: string format: date-time nullable: true description: >- 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' oneOf: - required: - from_number_id - required: - from_number example: 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 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: 00000000-0000-4000-8000-00000000010b 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: 00000000-0000-4000-8000-000000000115 custom_args_values: type: object description: Custom variables passed in the request example: callee_name: Priya mobile_number: '+919876543210' transfer_to: '+919876543211' message: type: string example: Call initiated successfully '400': description: >- Bad Request - For example, no caller number and no outbound numbers on the agent version, a Ringg test number used as the caller number, a DND number, or a missing variable. content: application/json: schema: type: object properties: message: type: string example: >- Either from_number_id or from_number must be provided, or configure default outbound numbers on the agent version '401': description: Unauthorized - Invalid or missing API key. content: application/json: schema: type: object properties: message: type: string example: Invalid credentials '402': description: >- Payment Required - The workspace balance (or available credit limit) does not cover the call. content: application/json: schema: type: object properties: message: type: string example: >- Your current balance is insufficient to initiate this call! '422': description: >- Validation Error - A field is missing or has the wrong type, or both `from_number_id` and `from_number` were sent. content: application/json: schema: type: object properties: message: type: string example: Provide either from_number_id or from_number, not both '500': description: Internal Server Error - Something went wrong on our end. content: application/json: schema: type: object properties: message: type: string example: An unexpected error occurred. Please try again later. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.