---
title: "Initiate Individual Call (Number Pool)"
method: POST
path: "/calling/v2/outbound/individual"
tags: ["calling"]
---

# Initiate Individual Call (Number Pool)

`POST /calling/v2/outbound/individual`

Starts one outbound call to a recipient using a managed number pool or an explicit caller number.

## Headers

- `X-API-KEY` string, required

## Request body

- object — At least one of number_pool_id, from_number_id, or from_number is required. **from_number_id and from_number cannot both be set.**
  - `name` string, required — The name of the person to call.
  - `mobile_number` string, required — The phone number to call (must include country code).
  - `agent_id` string, required — UUID of the agent that will handle the call.
  - `number_pool_id` string, nullable — Managed number pool ID for automatic caller-number resolution (rotation, spam skipping, auto-purchase). **Provide exactly one of number_pool_id, from_number_id, or from_number.**
  - `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[]
  - `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 replaced in the agent's prompt using @{{variable_name}} syntax.
  - `smart_formatter` object — (Optional) Smart formatting for callee name — supports first name extraction and 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 using a local dictionary. Automatically applies extract_first_name.
    - `transliteration_language` object
      - `source` string
      - `target` string
  - `call_config` object — (Optional) Override default call configuration.
    - `idle_timeout_warning` integer
    - `idle_timeout_end` integer
    - `max_call_length` integer
    - `call_retry_config` object
      - `retry_count` integer
      - `retry_busy` integer
      - `retry_not_picked` integer
      - `retry_failed` integer
    - `call_time` object
      - `call_start_time` string
      - `call_end_time` string
      - `timezone` string
  - `voice_id` string, nullable — Optional AgentVoice ID for this call. Overrides the agent version's default voice.
  - `version_id` string, nullable — Optional agent version ID. Defaults to the active version.
  - `call_category` string, nullable — Optional category for internal reporting or workflow grouping.
  - `parent_call_id` string, nullable — Optional parent call ID for follow-up or chained-call flows.
  - `callback_url` string, nullable — Optional webhook URL for call events.
  - `callback_args` object — Optional headers and query params Ringg should include when calling callback_url.
    - `headers` object
    - `params` object

## 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'
    - `initiated_at` string, date-time
    - `agent_id` string
    - `custom_args_values` object
  - `message` string

## Other responses

- `400` — Bad Request - Invalid parameters or request format.
- `401` — Unauthorized - Invalid or missing API key.
- `500` — Internal Server Error.

---

[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)