Skip to main content
This guide takes you from API key to the first outbound call. The same IDs and patterns are used for campaigns, webhooks, and analytics.
Run these requests from your backend. X-API-KEY is a workspace secret and should not be exposed in client-side code.

​
Prerequisites

  • An active Ringg AI workspace
  • A workspace API key
  • An assistant configured for outbound calls
  • At least one phone number provisioned in the workspace
  • A server environment that can make HTTPS requests

​
Step 1: Set the base URL

All examples use the production API base URL: 
export RINGG_BASE_URL="https://prod-api.ringg.ai/ca/api/v0"
export RINGG_API_KEY="your-api-key"

​
Step 2: Verify authentication

Start with GET /workspace. This confirms that the key is valid and that your backend can reach Ringg. 
curl --request GET "$RINGG_BASE_URL/workspace" \
  --header "X-API-KEY: $RINGG_API_KEY"

​
Step 3: Choose an assistant

Use GET /agent/all and select the assistant that should run the call. 
curl --request GET "$RINGG_BASE_URL/agent/all" \
  --header "X-API-KEY: $RINGG_API_KEY"
Save the selected agent_id. If you do not have an assistant yet, create one in the dashboard first, then come back to the API flow.

​
Step 4: Choose a caller number

Use GET /workspace/numbers and save the caller number ID you want Ringg to use. 
curl --request GET "$RINGG_BASE_URL/workspace/numbers" \
  --header "X-API-KEY: $RINGG_API_KEY"
Save the selected from_number_id. The individual-call API requires exactly one caller-number option: from_number_id or from_number. Use from_number_id when possible because it is stable across number formatting changes.

​
Step 5: Make the call

Call POST /calling/outbound/individual with the recipient, assistant, caller number, and any variables your assistant prompt uses. 
export AGENT_ID="your-agent-id"
export FROM_NUMBER_ID="your-from-number-id"

curl --request POST "$RINGG_BASE_URL/calling/outbound/individual" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "John Doe",
    "mobile_number": "+919876543210",
    "agent_id": "'"$AGENT_ID"'",
    "from_number_id": "'"$FROM_NUMBER_ID"'",
    "custom_args_values": {
      "callee_name": "John",
      "account_id": "ACC-42"
    },
    "call_config": {
      "call_time": {
        "call_start_time": "09:00",
        "call_end_time": "18:00",
        "timezone": "Asia/Kolkata"
      },
      "call_retry_config": {
        "retry_count": 1,
        "retry_busy": 30,
        "retry_not_picked": 30,
        "retry_failed": 30
      }
    }
  }'

​
Step 6: Store the response

A successful request returns a call object. Store the unique call ID in your application so you can join webhook events, history records, and support logs. 
{
  "Call Status": "success",
  "data": {
    "Unique Call ID": "dd6c63db-66c7-42ae-9a82-e4988bef428e",
    "Call Direction": "outbound",
    "Call Status": "registered",
    "From Number": "+918035737034",
    "To Number": "+919876543210",
    "Agent ID": "cdcf1b39-173a-4492-8396-c493123ea443",
    "System generated message": "Call initiated successfully"
  }
}

​
Step 7: Receive results

For production integrations, subscribe the assistant to webhook events so your application receives call state, recording, transcript, and analysis updates without polling. Recommended event:
  • all_processing_completed: one final event after transcript, recording, platform analysis, and custom analysis are available
You can also use GET /calling/history for dashboards, reconciliation, and manual debugging.

​
Production checklist

  • Keep X-API-KEY in a server secret manager.
  • Store agent_id, from_number_id, and returned call_id.
  • Send recipient numbers in E.164 format with country code.
  • Match custom_args_values keys to prompt placeholders like @{{callee_name}}.
  • Configure calling windows and retries in call_config for your market.
  • Make webhook handlers idempotent and respond with 2xx quickly.

​
Next steps

Authentication

Learn how API keys are created, sent, rotated, and protected.

Initiate individual call

Review every supported request field for outbound calls.

Webhook setup

Subscribe to real-time call and analysis events.