---
title: "Initiate Individual Call"
method: POST
path: "/calling/outbound/individual"
tags: ["calling"]
---

# Initiate Individual Call

`POST /calling/outbound/individual`

Starts one outbound call to a recipient. **Exactly one caller-number option is required: from_number_id or from_number.**

## Headers

- `X-API-KEY` string, required

## Request body

- union
  - object
    - `name` string, required — The name of the person to call
    - `mobile_number` string, required — The phone number to call (must include country code, e.g., +91 for India)
    - `agent_id` string, required — UUID of the agent that will handle the call
    - `from_number` union — Caller phone number, or array of caller phone numbers, with country code. **Provide either from_number or from_number_id, not both.**
      - string
      - string[]
    - `custom_args_values` object — Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax
      - `company_name` string — Company name for context
      - `appointment_date` string — Appointment date
      - `product_name` string — Product name for sales calls
    - `smart_formatter` object — (Optional) Smart formatting for callee name — supports first name extraction and dictionary-based transliteration
      - `extract_first_name` boolean — Extract the first actual name from the full name, skipping common prefixes (Mr, Mrs, Dr, etc.)
      - `transliteration` boolean — Transliterate the extracted name to the target language using a local dictionary. When enabled, extract_first_name is automatically applied.
      - `transliteration_language` object — Language configuration for transliteration
        - `source` string — Source language code (default: en)
        - `target` string — Target language code (default: hi)
    - `call_config` object — (Optional) Override default call configuration
      - `idle_timeout_warning` integer — Seconds before idle warning (default: 5)
      - `idle_timeout_end` integer — Seconds before call termination (default: 10)
      - `max_call_length` integer — Maximum call duration in seconds (default: 240)
      - `call_retry_config` object — Retry configuration for failed calls
        - `retry_count` integer — Number of retry attempts
        - `retry_busy` integer — Minutes to wait if busy (default: 30)
        - `retry_not_picked` integer — Minutes to wait if not picked (default: 30)
        - `retry_failed` integer — Minutes to wait if failed (default: 30)
      - `call_time` object — Time window configuration for calls
        - `call_start_time` string — When calls can start (default: 00:00)
        - `call_end_time` string — When calls must end (default: 23:00)
        - `timezone` string — Timezone for call times (default: Asia/Kolkata)
    - `from_number_id` union, 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.**
      - string
      - string[]
    - `callback_url` string — Optional webhook URL for call events for this request.
    - `callback_args` object — Optional headers and query params Ringg should include when calling callback_url.
      - `headers` object
      - `params` object
    - `version_id` string — Optional assistant version ID. Defaults to the active version.
    - `call_category` string — Optional category for internal reporting or workflow grouping.
    - `parent_call_id` string — Optional parent call ID for follow-up or chained-call flows.
  - object
    - `name` string, required — The name of the person to call
    - `mobile_number` string, required — The phone number to call (must include country code, e.g., +91 for India)
    - `agent_id` string, required — UUID of the agent that will handle the call
    - `from_number` union, required — Caller phone number, or array of caller phone numbers, with country code. **Provide either from_number or from_number_id, not both.**
      - string
      - string[]
    - `custom_args_values` object — Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax
      - `company_name` string — Company name for context
      - `appointment_date` string — Appointment date
      - `product_name` string — Product name for sales calls
    - `smart_formatter` object — (Optional) Smart formatting for callee name — supports first name extraction and dictionary-based transliteration
      - `extract_first_name` boolean — Extract the first actual name from the full name, skipping common prefixes (Mr, Mrs, Dr, etc.)
      - `transliteration` boolean — Transliterate the extracted name to the target language using a local dictionary. When enabled, extract_first_name is automatically applied.
      - `transliteration_language` object — Language configuration for transliteration
        - `source` string — Source language code (default: en)
        - `target` string — Target language code (default: hi)
    - `call_config` object — (Optional) Override default call configuration
      - `idle_timeout_warning` integer — Seconds before idle warning (default: 5)
      - `idle_timeout_end` integer — Seconds before call termination (default: 10)
      - `max_call_length` integer — Maximum call duration in seconds (default: 240)
      - `call_retry_config` object — Retry configuration for failed calls
        - `retry_count` integer — Number of retry attempts
        - `retry_busy` integer — Minutes to wait if busy (default: 30)
        - `retry_not_picked` integer — Minutes to wait if not picked (default: 30)
        - `retry_failed` integer — Minutes to wait if failed (default: 30)
      - `call_time` object — Time window configuration for calls
        - `call_start_time` string — When calls can start (default: 00:00)
        - `call_end_time` string — When calls must end (default: 23:00)
        - `timezone` string — Timezone for call times (default: Asia/Kolkata)
    - `from_number_id` union — Workspace number ID, or array of workspace number IDs, to use as caller ID. **Provide either from_number_id or from_number, not both.**
      - string
      - string[]
    - `callback_url` string — Optional webhook URL for call events for this request.
    - `callback_args` object — Optional headers and query params Ringg should include when calling callback_url.
      - `headers` object
      - `params` object
    - `version_id` string — Optional assistant version ID. Defaults to the active version.
    - `call_category` string — Optional category for internal reporting or workflow grouping.
    - `parent_call_id` string — Optional parent call ID for follow-up or chained-call flows.

## Response `200`

Successful Response: Details about the initiated call.

- object
  - `status` string
  - `data` object
    - `call_id` string
    - `call_direction` string
    - `call_status` 'registered' | 'ongoing' | 'retry' | 'error' | 'completed' | 'failed' | 'cancelled' | 'forwarded' — The current status of the call
    - `initiated_at` string, date-time
    - `agent_id` string
    - `custom_args_values` object — Custom variables passed in the request
  - `message` string

## Other responses

- `400` — Bad Request - Invalid parameters or request format.
- `401` — Unauthorized - Invalid or missing API key.
- `500` — Internal Server Error - Something went wrong on our end.

---

[API](https://skmtc.dev/ringg/apis/ringg-ai-api-documentation.md) · [All operations](https://skmtc.dev/ringg/apis/ringg-ai-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ringg/ringg-ai-api-documentation/revisions/00b614a7714c/schema)