Initiate Individual Call (Number Pool)

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

POST /calling/v2/outbound/individual

Initiate Individual Call (Number Pool)

cURL

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "[phone]",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "number_pool_id": "pool-uuid-here",
  "from_number_id": "from-number-id",
  "from_number": "[phone]",
  "custom_args_values": {
    "company_name": "XYZ Corp",
    "appointment_date": "2025-01-20",
    "product_name": "Premium Service"
  },
  "smart_formatter": {
    "extract_first_name": true,
    "transliteration": true,
    "transliteration_language": {
      "source": "en",
      "target": "hi"
    }
  },
  "call_config": {
    "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:00",
      "timezone": "Asia/Kolkata"
    }
  },
  "voice_id": "voice-uuid-here",
  "version_id": "387bd8f1-5748-4006-b7fe-6a6455e9d45d",
  "call_category": "renewal_reminder",
  "parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
  "callback_url": "https://api.example.com/ringg/callback",
  "callback_args": {
    "headers": {},
    "params": {}
  }
}
'

import requests

url = "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual"

payload = {
    "name": "John Doe",
    "mobile_number": "[phone]",
    "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
    "number_pool_id": "pool-uuid-here",
    "from_number_id": "from-number-id",
    "from_number": "[phone]",
    "custom_args_values": {
        "company_name": "XYZ Corp",
        "appointment_date": "2025-01-20",
        "product_name": "Premium Service"
    },
    "smart_formatter": {
        "extract_first_name": True,
        "transliteration": True,
        "transliteration_language": {
            "source": "en",
            "target": "hi"
        }
    },
    "call_config": {
        "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:00",
            "timezone": "Asia/Kolkata"
        }
    },
    "voice_id": "voice-uuid-here",
    "version_id": "387bd8f1-5748-4006-b7fe-6a6455e9d45d",
    "call_category": "renewal_reminder",
    "parent_call_id": "550e8400-e29b-41d4-a716-446655440000",
    "callback_url": "https://api.example.com/ringg/callback",
    "callback_args": {
        "headers": {},
        "params": {}
    }
}
headers = {
    "X-API-KEY": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-KEY': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'John Doe',
    mobile_number: '[phone]',
    agent_id: '830f767a-397e-4b39-82ff-235cd344e2f9',
    number_pool_id: 'pool-uuid-here',
    from_number_id: 'from-number-id',
    from_number: '[phone]',
    custom_args_values: {
      company_name: 'XYZ Corp',
      appointment_date: '2025-01-20',
      product_name: 'Premium Service'
    },
    smart_formatter: {
      extract_first_name: true,
      transliteration: true,
      transliteration_language: {source: 'en', target: 'hi'}
    },
    call_config: {
      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:00', timezone: 'Asia/Kolkata'}
    },
    voice_id: 'voice-uuid-here',
    version_id: '387bd8f1-5748-4006-b7fe-6a6455e9d45d',
    call_category: 'renewal_reminder',
    parent_call_id: '550e8400-e29b-41d4-a716-446655440000',
    callback_url: 'https://api.example.com/ringg/callback',
    callback_args: {headers: {}, params: {}}
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'John Doe',
    'mobile_number' => '[phone]',
    'agent_id' => '830f767a-397e-4b39-82ff-235cd344e2f9',
    'number_pool_id' => 'pool-uuid-here',
    'from_number_id' => 'from-number-id',
    'from_number' => '[phone]',
    'custom_args_values' => [
        'company_name' => 'XYZ Corp',
        'appointment_date' => '2025-01-20',
        'product_name' => 'Premium Service'
    ],
    'smart_formatter' => [
        'extract_first_name' => true,
        'transliteration' => true,
        'transliteration_language' => [
                'source' => 'en',
                'target' => 'hi'
        ]
    ],
    'call_config' => [
        '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:00',
                'timezone' => 'Asia/Kolkata'
        ]
    ],
    'voice_id' => 'voice-uuid-here',
    'version_id' => '387bd8f1-5748-4006-b7fe-6a6455e9d45d',
    'call_category' => 'renewal_reminder',
    'parent_call_id' => '550e8400-e29b-41d4-a716-446655440000',
    'callback_url' => 'https://api.example.com/ringg/callback',
    'callback_args' => [
        'headers' => [
                
        ],
        'params' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-KEY: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual"

	payload := strings.NewReader("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"[phone]\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"from_number_id\": \"from-number-id\",\n  \"from_number\": \"[phone]\",\n  \"custom_args_values\": {\n    \"company_name\": \"XYZ Corp\",\n    \"appointment_date\": \"2025-01-20\",\n    \"product_name\": \"Premium Service\"\n  },\n  \"smart_formatter\": {\n    \"extract_first_name\": true,\n    \"transliteration\": true,\n    \"transliteration_language\": {\n      \"source\": \"en\",\n      \"target\": \"hi\"\n    }\n  },\n  \"call_config\": {\n    \"idle_timeout_warning\": 10,\n    \"idle_timeout_end\": 15,\n    \"max_call_length\": 300,\n    \"call_retry_config\": {\n      \"retry_count\": 3,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"00:00\",\n      \"call_end_time\": \"23:00\",\n      \"timezone\": \"Asia/Kolkata\"\n    }\n  },\n  \"voice_id\": \"voice-uuid-here\",\n  \"version_id\": \"387bd8f1-5748-4006-b7fe-6a6455e9d45d\",\n  \"call_category\": \"renewal_reminder\",\n  \"parent_call_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"callback_url\": \"https://api.example.com/ringg/callback\",\n  \"callback_args\": {\n    \"headers\": {},\n    \"params\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-KEY", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"[phone]\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"from_number_id\": \"from-number-id\",\n  \"from_number\": \"[phone]\",\n  \"custom_args_values\": {\n    \"company_name\": \"XYZ Corp\",\n    \"appointment_date\": \"2025-01-20\",\n    \"product_name\": \"Premium Service\"\n  },\n  \"smart_formatter\": {\n    \"extract_first_name\": true,\n    \"transliteration\": true,\n    \"transliteration_language\": {\n      \"source\": \"en\",\n      \"target\": \"hi\"\n    }\n  },\n  \"call_config\": {\n    \"idle_timeout_warning\": 10,\n    \"idle_timeout_end\": 15,\n    \"max_call_length\": 300,\n    \"call_retry_config\": {\n      \"retry_count\": 3,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"00:00\",\n      \"call_end_time\": \"23:00\",\n      \"timezone\": \"Asia/Kolkata\"\n    }\n  },\n  \"voice_id\": \"voice-uuid-here\",\n  \"version_id\": \"387bd8f1-5748-4006-b7fe-6a6455e9d45d\",\n  \"call_category\": \"renewal_reminder\",\n  \"parent_call_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"callback_url\": \"https://api.example.com/ringg/callback\",\n  \"callback_args\": {\n    \"headers\": {},\n    \"params\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/calling/v2/outbound/individual")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-KEY"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"[phone]\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"number_pool_id\": \"pool-uuid-here\",\n  \"from_number_id\": \"from-number-id\",\n  \"from_number\": \"[phone]\",\n  \"custom_args_values\": {\n    \"company_name\": \"XYZ Corp\",\n    \"appointment_date\": \"2025-01-20\",\n    \"product_name\": \"Premium Service\"\n  },\n  \"smart_formatter\": {\n    \"extract_first_name\": true,\n    \"transliteration\": true,\n    \"transliteration_language\": {\n      \"source\": \"en\",\n      \"target\": \"hi\"\n    }\n  },\n  \"call_config\": {\n    \"idle_timeout_warning\": 10,\n    \"idle_timeout_end\": 15,\n    \"max_call_length\": 300,\n    \"call_retry_config\": {\n      \"retry_count\": 3,\n      \"retry_busy\": 30,\n      \"retry_not_picked\": 30,\n      \"retry_failed\": 30\n    },\n    \"call_time\": {\n      \"call_start_time\": \"00:00\",\n      \"call_end_time\": \"23:00\",\n      \"timezone\": \"Asia/Kolkata\"\n    }\n  },\n  \"voice_id\": \"voice-uuid-here\",\n  \"version_id\": \"387bd8f1-5748-4006-b7fe-6a6455e9d45d\",\n  \"call_category\": \"renewal_reminder\",\n  \"parent_call_id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"callback_url\": \"https://api.example.com/ringg/callback\",\n  \"callback_args\": {\n    \"headers\": {},\n    \"params\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

200

{
  "status": "success",
  "data": {
    "call_id": "31106b7c-9d02-4723-8b07-5bb8d90240cb",
    "call_direction": "outbound",
    "call_status": "ongoing",
    "initiated_at": "2025-11-24T07:33:49.629642",
    "agent_id": "a31f36c4-c8ea-4c4b-9ad6-743dabacafbd",
    "custom_args_values": {
      "callee_name": "john",
      "order_id": "ORD-1042"
    }
  },
  "message": "Call initiated successfully"
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Provide at least one of: number_pool_id, from_number_id, from_number"
  }
}

{
  "error": {
    "code": "401 Unauthorized",
    "message": "Invalid credentials"
  }
}

{
  "error": {
    "code": "500 Internal Server Error",
    "message": "An unexpected error occurred on the server."
  }
}

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 [phone].
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

{
  "name": "John Doe",
  "mobile_number": "[phone]",
  "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.

{
  "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.
• Reconcile rows from 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.

Headers

X-API-KEY · string · required

(Required) Your Ringg AI API key.

Example:

"7251cb4b-3373-43a4-844c-b27a1d45e0c9"

Body

application/json

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.

Example:

"John Doe"

mobile_number · string · required

The phone number to call (must include country code).

Example:

"[phone]"

agent_id · string · required

UUID of the agent that will handle the call.

Example:

"830f767a-397e-4b39-82ff-235cd344e2f9"

number_pool_id · string | null

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 · string string[]

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 · string string[]

Caller phone number, or array of caller phone numbers, with country code. Provide either from_number or from_number_id, not both.

Example:

"[phone]"

custom_args_values · object

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 · object

(Optional) Smart formatting for callee name — supports first name extraction and transliteration.

Show child attributes

Example:

{
  "extract_first_name": true,
  "transliteration": true,
  "transliteration_language": { "source": "en", "target": "hi" }
}

call_config · object

(Optional) Override default call configuration.

Show child attributes

voice_id · string | null

Optional AgentVoice ID for this call. Overrides the agent version's default voice.

Example:

"voice-uuid-here"

version_id · string | null

Optional agent version ID. Defaults to the active version.

Example:

"387bd8f1-5748-4006-b7fe-6a6455e9d45d"

call_category · string | null

Optional category for internal reporting or workflow grouping.

Example:

"renewal_reminder"

parent_call_id · string | null

Optional parent call ID for follow-up or chained-call flows.

Example:

"550e8400-e29b-41d4-a716-446655440000"

callback_url · string | null

Optional webhook URL for call events.

Example:

"https://api.example.com/ringg/callback"

callback_args · object

Optional headers and query params Ringg should include when calling callback_url.

Show child attributes

Response

200

application/json

Successful Response: Details about the initiated call.

status · string

Example:

"success"

data · object

Show child attributes

message · string

Example:

"Call initiated successfully"