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"

Caution

Always use HTTPS when accessing the KPI module. HTTP requests will be rejected.

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

Parameter	Type	Required	Description
outputMode	string	No	Response format: json, csv, or html
key	string	Conditional	KPI key if not using Bearer authentication

Note

Automatic Output Format Detection: The KPI module automatically selects the output format based on how you authenticate:

• Bearer token in header → JSON output (for API clients)
• Key as URL parameter → HTML output (for browser viewing)
• Override with outputMode parameter as needed

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:

Customer Status	Count
Active	2650
Suspended	47

Note

Field Names: JSON responses use prefixed field names (e.g., customer_count), while HTML and CSV outputs use human-readable headers defined in the field configuration (e.g., “Count”).

Common Filters

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

Filter	Type	Description	Example
status	string	Filter by entity status	status=active
dealerCode	string	Filter by specific dealer	dealerCode=DEALER01
dateFrom	date	Start date for date ranges	dateFrom=2024-01-01
dateTo	date	End date for date ranges	dateTo=2024-01-31
idAfter	integer	Pagination: IDs greater than this value	idAfter=1000
limit	integer	Maximum results to return	limit=100

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:

Status Code	Description
200	Success - Request processed successfully
400	Bad Request - Invalid parameters or request format
401	Unauthorised - Missing or invalid KPI key
403	Forbidden - Valid key but insufficient permissions
404	Not Found - Invalid object or KPI type
500	Server Error - Internal processing error

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