> ## 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 (Number Pool) > Starts one outbound call to a recipient using a managed number pool or an explicit caller number. Start one outbound call with a configured assistant, using a managed number pool for caller-number resolution. The pool handles rotation, spam skipping, and auto-purchase automatically — so you don't have to manage `from_number` lists yourself. ## 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`. | ## Caller number source Provide **exactly one** of the following: | Field | When to use | | ---------------- | ------------------------------------------------------------------------- | | `number_pool_id` | Recommended. Resolve the caller number automatically from a managed pool. | | `from_number_id` | Use a specific workspace number ID as caller ID. | | `from_number` | Use an explicit caller phone number (with country code). | **`from_number_id` and `from_number` cannot both be set.** At least one number source is required. ## Minimal request ```json theme={null} { "name": "John Doe", "mobile_number": "+919876543210", "agent_id": "your-agent-id", "number_pool_id": "your-number-pool-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. ## 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, no number source provided, or both `from_number_id` and `from_number` set. | | Call remains queued | Calling window, scheduled time, workspace credits, pool availability, or provider health. | | Assistant says wrong data | Prompt placeholders do not match `custom_args_values` keys. | ## OpenAPI ````yaml post /calling/v2/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/v2/outbound/individual: post: tags: - calling summary: Initiate Individual Call (Number Pool) description: >- Starts one outbound call to a recipient using a managed number pool or an explicit caller number. operationId: initiateIndividualCallV2 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). example: '+1234567890' agent_id: type: string description: UUID of the agent that will handle the call. example: 830f767a-397e-4b39-82ff-235cd344e2f9 number_pool_id: type: string nullable: true description: >- 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.** example: pool-uuid-here 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 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 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: type: object description: >- (Optional) Smart formatting for callee name — supports first name extraction and 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 using a local dictionary. Automatically applies extract_first_name. default: false example: true transliteration_language: type: object properties: source: type: string default: en example: en target: type: string default: hi example: 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 default: 5 example: 10 idle_timeout_end: type: integer default: 10 example: 15 max_call_length: type: integer default: 240 example: 300 call_retry_config: type: object properties: retry_count: type: integer example: 3 retry_busy: type: integer default: 30 example: 30 retry_not_picked: type: integer default: 30 example: 30 retry_failed: type: integer default: 30 example: 30 call_time: type: object properties: call_start_time: type: string default: '00:00' example: '00:00' call_end_time: type: string default: '23:00' example: '23:00' timezone: type: string default: Asia/Kolkata example: Asia/Kolkata voice_id: type: string nullable: true description: >- Optional AgentVoice ID for this call. Overrides the agent version's default voice. example: voice-uuid-here version_id: type: string nullable: true description: Optional agent version ID. Defaults to the active version. example: 387bd8f1-5748-4006-b7fe-6a6455e9d45d call_category: type: string nullable: true description: >- Optional category for internal reporting or workflow grouping. example: renewal_reminder parent_call_id: type: string nullable: true description: Optional parent call ID for follow-up or chained-call flows. example: 550e8400-e29b-41d4-a716-446655440000 callback_url: type: string nullable: true description: Optional webhook URL for call events. 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 description: >- 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.** 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 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 example: callee_name: john order_id: ORD-1042 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: >- Provide at least one of: number_pool_id, from_number_id, from_number '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. 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. ````