Skip to main content
Use this tutorial when you already have a Ringg workspace and want to prove the end-to-end phone call flow from your backend.
Keep X-API-KEY on your server. Do not expose it in browser or mobile source code.

​
Prerequisites

  • A Ringg AI workspace and API key
  • An outbound assistant
  • A provisioned workspace number
  • A recipient phone number in E.164 format, for example +919876543210

​
Step 1: Verify your workspace

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/workspace" \
  --header "X-API-KEY: $RINGG_API_KEY"
If this returns 401, fix the key before continuing.

​
Step 2: Get an assistant ID

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/agent/all" \
  --header "X-API-KEY: $RINGG_API_KEY"
Choose the assistant that should conduct the conversation and save its agent_id.

​
Step 3: Get a caller number ID

curl --request GET "https://prod-api.ringg.ai/ca/api/v0/workspace/numbers" \
  --header "X-API-KEY: $RINGG_API_KEY"
Choose a number available in your workspace and save its from_number_id.

​
Step 4: Initiate the outbound call

curl --request POST "https://prod-api.ringg.ai/ca/api/v0/calling/outbound/individual" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "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_args_values should include every variable your assistant prompt references, such as @{{callee_name}} or @{{order_id}}.

​
Step 5: Store the call ID

A successful response includes a unique call ID. Store it in your system. 
{
  "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 6: Check the result

For manual verification, use call history: 
curl --request GET "https://prod-api.ringg.ai/ca/api/v0/calling/history?limit=20&offset=0" \
  --header "X-API-KEY: $RINGG_API_KEY"
For production, configure webhooks and subscribe to all_processing_completed so your backend receives the final transcript, recording, and analysis data automatically.

​
Status reference

StatusMeaning
registeredCall is queued and waiting to be processed
ongoingCall is in progress
retryRingg will retry based on retry configuration
completedRecipient answered and the call reached a terminal completed state
failedRetries were exhausted or the provider failed the call
errorUnexpected terminal error
cancelledCall was cancelled before completion

​
Next steps

Configure webhooks

Receive call events instead of polling call history.

Start bulk calls

Move from one call to campaign calling.