Balance & Billing
Monitor your account balance, track transaction history, and configure low balance alerts to ensure uninterrupted service for your communication platform.
Key Features
- Multi-currency support (USD, EUR, INR, etc.)
- Real-time balance monitoring
- Comprehensive transaction history with filtering
- Configurable low balance alerts with email notifications
- Automated billing for calls and phone number subscriptions
List Balances
/api/v1/account/{accountId}/balanceList all currency balances for the account.
▶HTTP Headers
About This Endpoint
Retrieve a comprehensive overview of all currency balances associated with your account in a single API call. This endpoint returns an array of balance objects, each representing a different currency (USD, EUR, INR, etc.) with detailed breakdowns of total balance, reserved funds locked for active calls, and available balance for new transactions. Perfect for multi-currency operations or building financial dashboards that need to display all account balances simultaneously without making multiple per-currency API requests.
Response Structure
- Returns array of balances, one object per currency with active balance
- Each balance includes total, reserved, and available amounts in cents
- Formatted strings provided for display with proper currency symbols
Common Use Cases
- Building multi-currency financial dashboards showing all account balances
- Checking all currency balances in one call instead of multiple per-currency requests
- Monitoring global account financial health across different currencies
Response Example
{
"balances": [
{
"currency": "USD",
"balance_cents": 500000,
"reserved_cents": 12500,
"available_cents": 487500,
"formatted": {
"balance": "$5,000.00",
"reserved": "$125.00",
"available": "$4,875.00"
}
},
{
"currency": "EUR",
"balance_cents": 250000,
"reserved_cents": 0,
"available_cents": 250000,
"formatted": {
"balance": "€2,500.00",
"reserved": "€0.00",
"available": "€2,500.00"
}
}
]
}Get Balance
/api/v1/account/{accountId}/balance/{currency}Get balance for a specific currency (e.g., USD, EUR, INR).
▶HTTP Headers
About This Endpoint
Retrieve real-time balance information for a specific currency by including the currency code in the URL path (e.g., USD, EUR, INR). The response includes total balance, reserved funds currently locked for active calls, and available balance for new transactions. Amounts are returned in both raw cents and human-readable formatted strings with proper currency symbols. Use this endpoint when you need balance details for a specific currency rather than all currencies at once, enabling more targeted financial validation and monitoring.
Balance Components
- balance_cents: Total account balance for this currency including available and reserved funds
- reserved_cents: Funds temporarily locked for active calls, released upon call completion
- available_cents: Immediately available balance for new purchases or transactions
Common Use Cases
- Checking specific currency balance before purchases or billable operations
- Displaying currency-specific balance in currency-scoped dashboard widgets
- Validating sufficient funds for currency-specific transactions before processing
Response Example
{
"currency": "USD",
"balance_cents": 500000,
"reserved_cents": 12500,
"available_cents": 487500,
"formatted": {
"balance": "$5,000.00",
"reserved": "$125.00",
"available": "$4,875.00"
}
}List Transactions
/api/v1/account/{accountId}/transactions?limit=50&offset=0Retrieve paginated transaction history with filtering options.
▶HTTP Headers
About This Endpoint
Access complete transaction history for your account with pagination and filtering capabilities to track all balance movements. Each transaction entry includes type (credit or debit), amount, descriptive reason, and timestamp, enabling comprehensive financial auditing and reconciliation. Query parameters allow filtering by date range, transaction type, or amount thresholds. The paginated response includes total transaction count, facilitating navigation through extensive transaction histories spanning months or years of account activity.
Transaction Types Tracked
- Credits: Account top-ups, refunds, promotional credits, number release refunds
- Debits: Call charges, phone number purchases, monthly recurring fees, penalties
- Metadata: Each transaction includes reference IDs linking to calls, numbers, or payments
Common Use Cases
- Building billing dashboards showing recent account activity and spending patterns
- Generating financial reports for accounting, auditing, or expense reconciliation
- Investigating specific charges or discrepancies by filtering transaction history
Response Example
{
"transactions": [
{
"id": "txn_abc123",
"type": "debit",
"amount_cents": 250,
"description": "Call charges",
"created_at": "2025-10-12T09:45:00.000Z"
}
],
"total": 1254
}