> ## 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 and let Ringg pick the caller number from a number pool, or pass a caller number yourself; optionally override the voice. # Initiate Individual Call (Number Pool) export const RelatedTopics = ({items}) =>
Related topics
{items.map(([title, href]) => {title} )}
; The [number pool](/documentation/inventory/phone-numbers/number-pools) rotates numbers and skips ones flagged as spam. ## Caller number Send at least one of these. With `number_pool_id`, Ringg picks the number from the pool and ignores the other two. Without a pool, outbound numbers set on the agent version are used before `from_number_id` or `from_number`. | Field | When to use it | | - | - | | `number_pool_id` | Ringg picks the number from the pool. Copy the ID with **Copy pool ID** on the **Number pools** page. | | `from_number_id` | A specific workspace number, from [List workspace numbers](/api-reference/inventory/numbers/get-workspace-numbers). | | `from_number` | A specific number written out with country code. | ```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" } } ``` `name`, `mobile_number`, `agent_id`, `custom_args_values`, `smart_formatter`, `call_config`, `version_id`, `purpose`, `call_validity_hours` and `call_deadline` work as on [Initiate individual call](/api-reference/calling/individual-calls/initiate-individual-call). The response's `data.call_id` identifies the call everywhere else. ## Troubleshooting As for [Initiate individual call](/api-reference/calling/individual-calls/initiate-individual-call#troubleshooting), plus: | Symptom | Check | | - | - | | `422` | No caller number source, or both `from_number_id` and `from_number`. | | `400` | The pool does not exist (`Number pool not found`) or has no usable number (`Number pool has no available numbers`). | ## OpenAPI ````yaml post /calling/v2/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/v2/outbound/individual: post: tags: - calling summary: Initiate Individual Call (Number Pool) description: >- Starts one outbound call to a recipient using a number pool or an explicit caller number. Send at least one of `number_pool_id`, `from_number_id` or `from_number`. With a pool, Ringg picks the caller number from it and ignores the other two. operationId: initiateIndividualCallV2 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). example: '+1234567890' agent_id: type: string description: UUID of the agent that will handle the call. example: 00000000-0000-4000-8000-0000000000a1 number_pool_id: type: string nullable: true description: >- Number pool ID. Ringg picks the caller number from the pool, rotating numbers and skipping ones flagged as spam. When it is sent, `from_number_id` and `from_number` are ignored. example: 00000000-0000-4000-8000-0000000000b1 from_number_id: oneOf: - type: string - type: array items: type: string description: >- Workspace number ID, or array of workspace number IDs. Used when no `number_pool_id` is sent. Send either `from_number_id` or `from_number`, not both (422). 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. Used when no `number_pool_id` is sent. Send either `from_number` or `from_number_id`, not both (422). 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 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' 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: 00000000-0000-4000-8000-0000000000d1 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 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' description: >- Send at least one of `number_pool_id`, `from_number_id` or `from_number`. `from_number_id` and `from_number` cannot both be set. When `number_pool_id` is sent, the pool wins. 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 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 example: callee_name: Priya order_id: ORD-1042 message: type: string example: Call initiated successfully '400': description: >- Bad Request - For example, the pool does not exist or has no usable number, or a Ringg test number was used as the caller number. content: application/json: schema: type: object properties: message: type: string example: Number pool has no available numbers '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 - No caller number source, both `from_number_id` and `from_number`, an empty `number_pool_id`, or a field with the wrong type. content: application/json: schema: type: object properties: message: type: string example: >- Provide at least one of: number_pool_id, from_number_id, from_number '500': description: Internal Server Error. 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.