Initiate Individual Call (Number Pool)

POST

calling

outbound

individual

Initiate Individual Call (Number Pool)

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": "+1234567890",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "number_pool_id": "pool-uuid-here",
  "from_number_id": "from-number-id",
  "from_number": "+1987654321",
  "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": {}
  }
}
'

{
  "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"
}

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

{
  "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.

{
  "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:

"+1234567890"

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

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

Successful Response: Details about the initiated call.

status

string

Example:

"success"

data

object

Show child attributes

message

string

Example:

"Call initiated successfully"

Upload Campaign Contact ListUploads a contact list for a campaign. Accepts a CSV file and campaign configuration as form data.

Initiate Individual Call (Number Pool)

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": "+1234567890",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "number_pool_id": "pool-uuid-here",
  "from_number_id": "from-number-id",
  "from_number": "+1987654321",
  "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": {}
  }
}
'

{
  "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"
}

​Required inputs

​Caller number source

​Minimal request

​Custom variables

​Smart formatter

​Result handling

​Common failure checks

Headers

Body

Response

Required inputs

Caller number source

Minimal request

Custom variables

Smart formatter

Result handling

Common failure checks