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, invoices, payments, Direct Debit collections and outstanding debt 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 seven 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
• Payments - Report amounts actually received, by method, dealer and period
• Collections - Measure Direct Debit and card collection performance, including failures and retries
• Debt Ageing - Bucket outstanding invoice balances by how overdue they are

Customers, numbers and features can also produce growth and churn series, showing additions and losses over time. See Available KPIs for the full list.

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, invoices, payments, directDebitCollections, cardCollections, or arAgeing
• {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
groupBy	string	No	Comma-separated dimensions to group by, instead of a {kpi} type
interval	string	No	Period bucket: day, week, month, quarter, or year
measures	string	No	Named measure set to return (defaults to default)

Flexible Grouping and Intervals

Every KPI category can be grouped by any of its dimensions using the groupBy parameter, as an alternative to the named KPI types. Combine it with interval to bucket results by time period:

# Payment totals by quarter and payment method
curl -X GET "https://companyname.callstats.net/backend/kpi/payments/?groupBy=period,method&interval=quarter" \
  -H "Authorization: Bearer YOUR_KPI_KEY"

• groupBy accepts a comma-separated list of the category’s dimensions. Each category page lists its dimensions.
• interval controls the size of the period dimension’s buckets: day, week, month, quarter, or year. If you group by period without an interval, it defaults to month.
• interval also works with the named KPI types, so invoices/byMonth/?interval=quarter re-buckets the familiar monthly report by quarter.
• measures selects a named set of result columns where a category offers more than one (for example the invoices breakdown set).

Grouped period columns are named {prefix}period in JSON output (for example invoice_period), except in the legacy byMonth KPI types, which keep their original {prefix}month names.

Note

Currency columns only appear on platforms with the multi-currency module active. Measure sets that report charges or amounts automatically include a currency column so that totals are never mixed across currencies.

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
active	boolean	Only include entries with an active status	active=true
dropped	boolean	Only include entries with an inactive status	dropped=true
dealerCode	string	Filter by specific dealer	dealerCode=DEALER01
minDate	date	Entries dated on or after this date	minDate=2026-01-01
maxDate	date	Entries dated on or before this date	maxDate=2026-01-31
customerID	integer	Only include entries for one customer	customerID=1234
createdSince	date	Only include entries created since this date/time	createdSince=2026-01-01
updatedSince	date	Only include entries modified since this date/time	updatedSince=2026-01-01
idAfter	integer	Only include entries with an ID greater than this value	idAfter=1000

Each category page lists exactly which filters it supports. KPI requests also accept the API’s generic field filters (f[field]=value and f[field][operator]=value); see Filtering in the API Reference for the full syntax.

The limit, offset and orderBy list parameters do not apply to KPI results. Row ordering is fixed by the requested dimensions.

Filtering Example

curl -X GET "https://companyname.callstats.net/backend/kpi/customers/byDealer/?active=true" \
  -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
• Payment KPIs - Amounts received by method, dealer and period
• Collection KPIs - Direct Debit and card collection performance
• Debt Ageing KPIs - Outstanding balances by days overdue