> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Quick Start Guide
> Make your first Ringg AI outbound call from your backend and understand the minimum production flow.
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:
```bash theme={null}
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.
```bash cURL theme={null}
curl --request GET "$RINGG_BASE_URL/workspace" \
--header "X-API-KEY: $RINGG_API_KEY"
```
```javascript Node.js theme={null}
const BASE_URL = "https://prod-api.ringg.ai/ca/api/v0";
async function ringg(path, options = {}) {
const response = await fetch(`${BASE_URL}${path}`, {
...options,
headers: {
"X-API-KEY": process.env.RINGG_API_KEY,
"Content-Type": "application/json",
...(options.headers || {}),
},
});
if (!response.ok) {
throw new Error(`Ringg API error: ${response.status} ${await response.text()}`);
}
return response.json();
}
const workspace = await ringg("/workspace");
console.log(workspace.workspace_info.id);
```
## Step 3: Choose an assistant
Use `GET /agent/all` and select the assistant that should run the call.
```bash theme={null}
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.
```bash theme={null}
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.
```bash cURL theme={null}
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
}
}
}'
```
```javascript Node.js theme={null}
const call = await ringg("/calling/outbound/individual", {
method: "POST",
body: JSON.stringify({
name: "John Doe",
mobile_number: "+919876543210",
agent_id: process.env.RINGG_AGENT_ID,
from_number_id: process.env.RINGG_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,
},
},
}),
});
console.log(call);
```
## 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.
```json theme={null}
{
"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
Learn how API keys are created, sent, rotated, and protected.
Review every supported request field for outbound calls.
Subscribe to real-time call and analysis events.