Initiate Individual Call

POST

calling

outbound

individual

Initiate Individual Call

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "from_number_id": "from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  },
  "callback_url": "https://api.example.com/ringg/callback"
}
'

import requests

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

payload = {
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
    "from_number_id": "from-number-id",
    "custom_args_values": {
        "callee_name": "John",
        "order_id": "ORD-1042"
    },
    "callback_url": "https://api.example.com/ringg/callback"
}
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: '+919876543210',
    agent_id: '830f767a-397e-4b39-82ff-235cd344e2f9',
    from_number_id: 'from-number-id',
    custom_args_values: {callee_name: 'John', order_id: 'ORD-1042'},
    callback_url: 'https://api.example.com/ringg/callback'
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/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/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' => '+919876543210',
    'agent_id' => '830f767a-397e-4b39-82ff-235cd344e2f9',
    'from_number_id' => 'from-number-id',
    'custom_args_values' => [
        'callee_name' => 'John',
        'order_id' => 'ORD-1042'
    ],
    'callback_url' => 'https://api.example.com/ringg/callback'
  ]),
  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/outbound/individual"

	payload := strings.NewReader("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\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/outbound/individual")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/calling/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\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\n}"

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

{
  "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": "abhishek",
      "mobile_number": "+912332423423",
      "transfer_to": "+917404243687"
    }
  },
  "message": "Call initiated successfully"
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Missing required field"
  }
}

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

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

Deprecated. This endpoint requires you to pass and manage caller numbers yourself via from_number_id or from_number. New integrations should use Initiate Individual Call (Pool), which can resolve numbers automatically from a managed pool (rotation, spam skipping, and auto-purchase).

Start one outbound call with a configured assistant. Use this endpoint for transactional calls, test calls before campaigns, and product workflows where one user action should trigger one phone call.

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`.
`from_number_id` or `from_number`	Caller ID to use. Exactly one is required. Use `from_number_id` when possible because it is stable across number formatting changes.

Provide either from_number_id or from_number, not both. Phone numbers passed as from_number must include country code.

Minimal request

{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "your-agent-id",
  "from_number_id": "your-from-number-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.

Scheduled calls

Add call_config.call_time.scheduled_at when the call should be queued for a specific date and time.

{
  "call_config": {
    "call_time": {
      "call_start_time": "09:00",
      "call_end_time": "18:00",
      "timezone": "Asia/Kolkata",
      "scheduled_at": "2026-10-18T10:30:00"
    }
  }
}

call_start_time and call_end_time still act as the allowed calling window in the specified timezone.

Retry configuration

Use retry settings when a recipient is busy, does not answer, or the provider fails the call.

{
  "call_config": {
    "call_retry_config": {
      "retry_count": 1,
      "retry_busy": 30,
      "retry_not_picked": 30,
      "retry_failed": 30
    }
  }
}

The retry delay values are in minutes.

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, both `from_number_id` and `from_number` provided, or invalid phone number.
Call remains queued	Calling window, scheduled time, workspace credits, 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

Option 1
Option 2

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, e.g., +91 for India)

Example:

"+1234567890"

agent_id

string

required

UUID of the agent that will handle the call

Example:

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

from_number_id

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.

Example:

"from-number-id"

from_number

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

object

Custom variables that will be replaced in the agent's prompt using @{{variable_name}} syntax

Show child attributes

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 dictionary-based 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

Example:

{
  "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:59",
    "timezone": "Asia/Kolkata"
  }
}

callback_url

string

Optional webhook URL for call events for this request.

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

version_id

string

Optional assistant version ID. Defaults to the active version.

Example:

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

call_category

string

Optional category for internal reporting or workflow grouping.

Example:

"renewal_reminder"

parent_call_id

string

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

Example:

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

Response

Successful Response: Details about the initiated call.

status

string

Example:

"success"

data

object

Show child attributes

message

string

Example:

"Call initiated successfully"

Initiate Individual Call (Number Pool)Starts one outbound call to a recipient using a managed number pool or an explicit caller number.

Initiate Individual Call

curl --request POST \
  --url https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <x-api-key>' \
  --data '
{
  "name": "John Doe",
  "mobile_number": "+919876543210",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "from_number_id": "from-number-id",
  "custom_args_values": {
    "callee_name": "John",
    "order_id": "ORD-1042"
  },
  "callback_url": "https://api.example.com/ringg/callback"
}
'

import requests

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

payload = {
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
    "from_number_id": "from-number-id",
    "custom_args_values": {
        "callee_name": "John",
        "order_id": "ORD-1042"
    },
    "callback_url": "https://api.example.com/ringg/callback"
}
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: '+919876543210',
    agent_id: '830f767a-397e-4b39-82ff-235cd344e2f9',
    from_number_id: 'from-number-id',
    custom_args_values: {callee_name: 'John', order_id: 'ORD-1042'},
    callback_url: 'https://api.example.com/ringg/callback'
  })
};

fetch('https://prod-api.ringg.ai/ca/api/v0/calling/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/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' => '+919876543210',
    'agent_id' => '830f767a-397e-4b39-82ff-235cd344e2f9',
    'from_number_id' => 'from-number-id',
    'custom_args_values' => [
        'callee_name' => 'John',
        'order_id' => 'ORD-1042'
    ],
    'callback_url' => 'https://api.example.com/ringg/callback'
  ]),
  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/outbound/individual"

	payload := strings.NewReader("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\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/outbound/individual")
  .header("X-API-KEY", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"John Doe\",\n  \"mobile_number\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://prod-api.ringg.ai/ca/api/v0/calling/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\": \"+919876543210\",\n  \"agent_id\": \"830f767a-397e-4b39-82ff-235cd344e2f9\",\n  \"from_number_id\": \"from-number-id\",\n  \"custom_args_values\": {\n    \"callee_name\": \"John\",\n    \"order_id\": \"ORD-1042\"\n  },\n  \"callback_url\": \"https://api.example.com/ringg/callback\"\n}"

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

{
  "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": "abhishek",
      "mobile_number": "+912332423423",
      "transfer_to": "+917404243687"
    }
  },
  "message": "Call initiated successfully"
}

{
  "error": {
    "code": "invalid_parameter",
    "message": "Missing required field"
  }
}

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

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

Get Started

API Reference

Webhooks Setup

Telephony Integration

Initiate Individual Call

Required inputs

Minimal request

Custom variables

Scheduled calls

Retry configuration

Smart formatter

Result handling

Common failure checks

Headers

Body

Response

​Required inputs

​Minimal request

​Custom variables

​Scheduled calls

​Retry configuration

​Smart formatter

​Result handling

​Common failure checks

Headers

Body

Response

Required inputs

Minimal request

Custom variables

Scheduled calls

Retry configuration

Smart formatter

Result handling

Common failure checks