KPI Module

The SAFE Billing Platform KPI (Key Performance Indicators) module provides real-time business intelligence data about your billing operations. Access comprehensive metrics about customers, numbers, features, and invoices through a simple REST API.

How to Use KPIs

The KPI module is designed to integrate seamlessly with your existing business intelligence tools and workflows:

Common Use Cases

Dashboard Integration

• Fetch JSON data to populate real-time dashboards (Grafana, PowerBI, Tableau)
• Set up automated polling to keep metrics current
• Combine multiple KPIs to create comprehensive business views

Automated Reporting

• Schedule daily/weekly CSV exports for spreadsheet analysis
• Track performance trends over time with automated scripts
• Generate alerts when metrics exceed thresholds

Quick Browser Checks

• Use HTML output to quickly view KPIs in your browser
• Share read-only KPI links with team members
• Bookmark specific KPI views for regular monitoring

Example Implementations

Daily Revenue Report Script

#!/bin/bash
# Download yesterday's invoice breakdown as CSV
curl -X GET "https://companyname.callstats.net/backend/kpi/invoices/breakdown/?outputMode=csv" \
  -H "Authorization: Bearer YOUR_KPI_KEY" \
  > "revenue_$(date +%Y%m%d).csv"

Dashboard JSON Feed

// Fetch customer metrics every 5 minutes for dashboard
setInterval(async () => {
  const response = await fetch('https://companyname.callstats.net/backend/kpi/customers/', {
    headers: { 'Authorization': 'Bearer YOUR_KPI_KEY' }
  });
  const data = await response.json();
  updateDashboard(data);
}, 300000);

Browser Bookmark

https://companyname.callstats.net/backend/kpi/invoices/byMonth/?key=YOUR_KPI_KEY

Save this URL to quickly check monthly billing trends in your browser.

Overview

The KPI module offers aggregated data and insights across four main categories:

• Customers - Monitor customer counts, status distributions, and dealer performance
• Numbers - Track telephone number allocations, types, and utilisation
• Features - Analyse feature adoption, revenue generation, and charge summaries
• Invoices - Review billing performance, revenue trends, and payment status

Authentication

All KPI endpoints require authentication using a valid KPI access key. You can authenticate using either method:

Bearer Token (Recommended)

curl -X GET https://companyname.callstats.net/backend/kpi/customers/ \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Query Parameter

curl -X GET "https://companyname.callstats.net/backend/kpi/customers/?key=YOUR_KPI_KEY"

Base URL

The KPI module is accessed through your platform’s domain:

https://companyname.callstats.net/backend/kpi/

Replace companyname with your actual platform subdomain.

Request Format

KPI endpoints use a RESTful URL structure:

/backend/kpi/{object}/
/backend/kpi/{object}/{kpi}/

Where:

• {object} is the KPI category: customers, numbers, features, or invoices
• {kpi} is the specific KPI type (optional, defaults to summary)

URL Parameters

Example Requests

Summary KPI

curl -X GET "https://companyname.callstats.net/backend/kpi/customers/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Specific KPI

curl -X GET "https://companyname.callstats.net/backend/kpi/customers/byStatus/" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Response Formats

JSON Format

JSON responses return an array of objects with field names prefixed by the KPI type:

[
  {
    "customer_count": 2847
  }
]

For multi-row results:

[
  {
    "customer_status": "Active",
    "customer_count": 2650
  },
  {
    "customer_status": "Suspended",
    "customer_count": 47
  }
]

CSV Format

CSV output includes headers and is suitable for spreadsheet import:

Customer Status,Count
Active,2650
Suspended,47

HTML Format

HTML output displays results in a formatted table, ideal for browser viewing:

Common Filters

Many KPIs support filtering to refine results. Common filters include:

Filtering Example

curl -X GET "https://companyname.callstats.net/backend/kpi/customers/byDealer/?status=active" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

Error Handling

The KPI module returns standard HTTP status codes:

Error Response Format

JSON Format

{
  "errors": {
    "error": "Invalid KPI type",
    "error_code": 400001,
    "hint": "Valid KPI types for customers are: null, byStatus, byDealer"
  }
}

HTML Format

Error: Invalid KPI type
Error Code: 400001
Hint: Valid KPI types for customers are: null, byStatus, byDealer

Rate Limiting

KPI endpoints are subject to rate limiting to ensure platform stability. Monitor response headers for current limits and adjust request frequency accordingly.

Data Freshness

KPI data is updated in real-time as changes occur in the platform:

• Customer/Number/Feature KPIs: Real-time updates
• Invoice KPIs: Updated as invoices are generated, sent, or paid
• Financial summaries: Calculated on-demand for accuracy

Best Practices

1. Cache responses appropriately - KPI data changes less frequently than transactional data
2. Use specific KPIs - Request only the data you need rather than parsing general summaries
3. Implement retry logic - Handle rate limits and temporary errors gracefully
4. Monitor rate limit headers - Adjust request frequency based on remaining allowance
5. Use filters - Reduce data transfer and processing by filtering at the source

Next Steps

Explore the detailed documentation for each KPI category:

• Customer KPIs - Customer metrics and dealer performance
• Number KPIs - Telephone number allocation and usage
• Feature KPIs - Feature adoption and revenue analysis
• Invoice KPIs - Billing performance and revenue tracking