Balance API

Check your account’s resource balances programmatically. Use this API to integrate balance monitoring into your own dashboards, alerting systems, and automation workflows.

Base URL

https://voxvaani.com/api/v1

Authentication

All requests require an API key in the header: x-api-key: YOUR_API_KEY or Authorization: Bearer YOUR_API_KEY

Required scope: balance:read

Get All Balances

Retrieve all resource balances and account information for the authenticated API key.

Endpoint: GET /balance

Response

{
  "success": true,
  "user": {
    "name": "Demo Client",
    "email": "[email protected]",
    "role": "user",
    "balance": 12000,
    "whatsappBalance": 25000,
    "emailBalance": 50000,
    "voiceMins": 0,
    "createdAt": "2026-06-10T19:24:05.579Z"
  }
}

Response Fields

Example

curl:

curl -X GET "https://voxvaani.com/api/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"

Python:

import requests
 
response = requests.get(
    "https://voxvaani.com/api/v1/balance",
    headers={"x-api-key": "YOUR_API_KEY"}
)
data = response.json()
print(f"WhatsApp Balance: {data['user']['whatsappBalance']}")
print(f"Voice Minutes: {data['user']['voiceMins']}")

JavaScript:

const response = await fetch("https://voxvaani.com/api/v1/balance", {
  headers: { "x-api-key": "YOUR_API_KEY" }
});
const data = await response.json();
console.log(`WhatsApp Balance: ${data.user.whatsappBalance}`);
console.log(`Voice Minutes: ${data.user.voiceMins}`);

Parameters

Monitoring & Alerting Recommendations

Set Up Balance Monitoring

Use the Balance API to build automated monitoring that prevents campaign interruptions:

1. Poll frequency: Check balances every 5-15 minutes during business hours; every 30 minutes outside business hours. Higher frequency during active campaigns.
2. Threshold alerts: Set alerts at graduated thresholds:
   • Warning (30%): Send email notification to the team
   • Critical (10%): Send urgent notification (push, Slack, SMS)
   • Depleted (0%): Trigger incident response workflow
3. Trend tracking: Store balance history to forecast when resources will run out based on consumption rate

Example Monitoring Script (Python)

import requests
import time
import smtplib
 
API_URL = "https://voxvaani.com/api/v1/balance"
API_KEY = "your-api-key"
THRESHOLD_PERCENT = 10  # Alert at 10%
 
plan_allocations = {
    "whatsappBalance": 5000,
    "emailBalance": 10000,
    "voiceMins": 1000
}
 
while True:
    resp = requests.get(API_URL, headers={"x-api-key": API_KEY})
    data = resp.json()["user"]
    
    for resource, plan_limit in plan_allocations.items():
        current = data.get(resource, 0)
        pct = (current / plan_limit) * 100
        if pct <= THRESHOLD_PERCENT:
            print(f"ALERT: {resource} at {pct:.1f}% ({current} remaining)")
            # Send email, Slack message, or push notification here
    
    time.sleep(300)  # Check every 5 minutes

Low Balance Webhooks

For real-time low balance alerts without polling, register a webhook for balance events. Webhooks push notifications to your HTTPS endpoint when a balance crosses a threshold, eliminating the need for continuous polling.

Contact support or your administrator to configure balance webhook thresholds. Available events include:

• balance.low — Balance dropped below warning threshold
• balance.critical — Balance dropped below critical threshold
• balance.depleted — Balance reached zero

Tips

• Check balances before sending bulk messages or campaigns — a single API call can prevent thousands of failed sends
• Set up monitoring to alert on low balances — don’t rely on manual checks
• Use the balance API for automated resource management — integrate with your CI/CD pipeline to halt deployments if resources are insufficient
• For real-time balance data during active campaigns, use the Balance API instead of the Wallet page (which may be cached)
• The balance:read scope covers monitoring, but scope enforcement is not applied uniformly across all endpoints yet — read Authentication before handing a monitoring key to a third party

Related Articles

• Authentication
• WhatsApp API
• Email API
• Billing Overview