Sign in

v1

latestOpenAPI 3.0.02026-07-2633090.6 KB
calling

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

Headers

X-API-KEYstring required
Example:7251cb4b-3373-43a4-844c-b27a1d45e0c9

(Required) Your Ringg AI API key.

Request body

namestring required

The name of the person to call.

mobile_numberstring required

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

agent_idstring required

UUID of the agent that will handle the call.

number_pool_idstring nullable

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.

custom_args_valuesobject

Custom variables replaced in the agent's prompt using @{{variable_name}} syntax.

voice_idstring nullable

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

version_idstring nullable

Optional agent version ID. Defaults to the active version.

call_categorystring nullable

Optional category for internal reporting or workflow grouping.

parent_call_idstring nullable

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

callback_urlstring nullable

Optional webhook URL for call events.

Example request

{
  "name": "John Doe",
  "mobile_number": "+1234567890",
  "agent_id": "830f767a-397e-4b39-82ff-235cd344e2f9",
  "number_pool_id": "pool-uuid-here",
  "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"
}

Response

Successful Response: Details about the initiated call.

statusstring
messagestring

Example response

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