Appearance
User - Dashboard
Base URL:
https://your-domain.com
Staff endpoints for the dashboard counters: subscribers, accounting and users. They need no module permission (only api_access for non-admin users) and always count the caller's own ISP and branch.
The numbers follow the web dashboard:
- Admin, Super admin and admin staff see the whole ISP and branch.
- Resellers, sub-resellers and retailers see their own figures (subscribers of their tree, their own sales and profit, the users below them).
- Reseller / sub-reseller / retailer staff (
profile_type6 / 7 / 8) see exactly their parent's numbers.
The answers are cached per user: subscriber stats for 1 minute, accounting and user stats for 3 minutes. A change shows up after that time.
Subscriber Stats
Retrieve the subscriber counters: totals by status and connection type, online / offline, expired and expiring soon. Every count comes with its share of total as a percentage string (the matching ...PCT key).
| Property | Value |
|---|---|
| Endpoint | Subscriber Stats |
| Method | GET |
| URL | /api/v1/dashboard/subscriber-stats |
| Authentication | Bearer Token |
Request Headers:
| Header | Value | Required |
|---|---|---|
Accept | application/json | Yes |
Authorization | Bearer your-auth-token | Yes |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
isp_id | integer | No | Your ISP ID. The counters always use your own ISP; another value is refused with 403 |
branch_id | integer | No | Your branch ID. The counters always use your own branch; another value is refused with 403 |
Request Body: None
Success Response (200 OK):
json
{
"status": "success",
"data": {
"total": 1250,
"totalPCT": "100.00%",
"new": 18,
"newPCT": "1.44%",
"register": 40,
"registerPCT": "3.20%",
"active": 1105,
"activePCT": "88.40%",
"disable": 85,
"disablePCT": "6.80%",
"terminate": 20,
"terminatePCT": "1.60%",
"pppoe": 1190,
"pppoePCT": "95.20%",
"hotspot": 60,
"hotspotPCT": "4.80%",
"online": 940,
"onlinePCT": "75.20%",
"expiredOnline": 12,
"expiredOnlinePCT": "0.96%",
"offline": 310,
"offlinePCT": "24.80%",
"totalExpired": 97,
"totalExpiredPCT": "7.76%",
"expiring1Day": 14,
"expiring1DayPCT": "1.12%",
"expiring3Days": 39,
"expiring3DaysPCT": "3.12%",
"expiring1Week": 88,
"expiring1WeekPCT": "7.04%",
"expiring2Weeks": 170,
"expiring2WeeksPCT": "13.60%",
"expiring4Weeks": 355,
"expiring4WeeksPCT": "28.40%"
}
}The answer always has these 34 keys, also when you have no subscribers: then every count is 0 and every percentage "0.00%".
| Key | Counts |
|---|---|
total | All subscribers you may see (totalPCT is "100.00%", or "0.00%" when total is 0) |
new | Active subscribers created in the last 7 days |
register | Subscribers in status Registered (profile_status 1) |
active | Subscribers in status Active (profile_status 2) |
disable | Subscribers in status Disabled (profile_status 3) |
terminate | Subscribers in status Terminated (profile_status 4) |
pppoe | PPPoE subscribers (connection_type 1) |
hotspot | Hotspot subscribers (connection_type 2) |
online | Subscribers online now |
expiredOnline | Expired subscribers that are still online |
offline | total minus online (never below 0) |
totalExpired | Subscribers whose expiration has passed |
expiring1Day | Subscribers whose RADIUS expiration falls in the next 24 hours |
expiring3Days | Subscribers whose RADIUS expiration falls in the next 3 days |
expiring1Week | Subscribers expiring within 1 week |
expiring2Weeks | Subscribers expiring within 2 weeks |
expiring4Weeks | Subscribers expiring within 4 weeks |
Each key above has a matching <key>PCT (for example activePCT): the count as a share of total, a string with two decimals and a % sign. The expiring windows overlap: a subscriber expiring tomorrow is counted in expiring1Day and in every longer window.
Error Response (400 Bad Request):
Returned when the token's user has no ISP or branch of its own.
json
{
"status": "error",
"message": "Invalid user configuration"
}Error Response (500 Server Error):
json
{
"status": "error",
"message": "Failed to fetch subscriber statistics"
}No exception text, file or line is returned; the details are written to the server log.
Code Examples:
bash
curl -X GET "https://your-domain.com/api/v1/dashboard/subscriber-stats?isp_id=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer your-auth-token"php
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://your-domain.com']);
$response = $client->request('GET', '/api/v1/dashboard/subscriber-stats', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer your-auth-token',
],
'query' => [
'isp_id' => 1,
],
]);
$data = json_decode($response->getBody(), true);
print_r($data);javascript
const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';
const params = new URLSearchParams({
isp_id: 1,
});
const response = await fetch(`${BASE_URL}/api/v1/dashboard/subscriber-stats?${params}`, {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${TOKEN}`,
},
});
const data = await response.json();
console.log(data);python
import requests
BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"
response = requests.get(
f"{BASE_URL}/api/v1/dashboard/subscriber-stats",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {TOKEN}",
},
params={
"isp_id": 1,
},
)
data = response.json()
print(data)go
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
const baseURL = "https://your-domain.com"
const token = "your-auth-token"
func main() {
endpoint := baseURL + "/api/v1/dashboard/subscriber-stats"
q := url.Values{}
q.Set("isp_id", "1")
endpoint += "?" + q.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))
}rust
use reqwest::Client;
const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let response = client
.get(format!("{BASE_URL}/api/v1/dashboard/subscriber-stats"))
.header("Accept", "application/json")
.bearer_auth(TOKEN)
.query(&[
("isp_id", "1"),
])
.send()
.await?;
let data: serde_json::Value = response.json().await?;
println!("{data:#}");
Ok(())
}Accounting Stats
Retrieve the sales, profit, dues and payment counters for the current week, current month, last month, current year and all time.
| Property | Value |
|---|---|
| Endpoint | Accounting Stats |
| Method | GET |
| URL | /api/v1/dashboard/accounting-stats |
| Authentication | Bearer Token |
Request Headers:
| Header | Value | Required |
|---|---|---|
Accept | application/json | Yes |
Authorization | Bearer your-auth-token | Yes |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
isp_id | integer | No | Your ISP ID. The counters always use your own ISP; another value is refused with 403 |
branch_id | integer | No | Your branch ID. The counters always use your own branch; another value is refused with 403 |
Request Body: None
Success Response (200 OK):
json
{
"status": "success",
"data": {
"currentWeekSales": "84,500.00",
"currentMonthSales": "612,300.00",
"lastMonthSales": "598,750.00",
"currentYearSales": "5,904,120.00",
"totalSales": "11,250,880.00",
"currentWeekProfits": "12,675.00",
"currentMonthProfits": "91,845.00",
"lastMonthProfits": "89,812.50",
"currentYearProfits": "885,618.00",
"totalProfits": "1,687,632.00",
"currentWeekDues": "6,200.00",
"currentMonthDues": "41,300.00",
"lastMonthDues": "18,950.00",
"currentYearDues": "152,400.00",
"totalDues": "203,700.00",
"subscriberCurrentWeekPayments": "79,300.00",
"subscriberCurrentMonthPayments": "571,000.00",
"subscriberLastMonthPayments": "579,800.00",
"subscriberCurrentYearPayments": "5,751,720.00",
"subscriberTotalPayments": "11,047,180.00",
"resellerCurrentWeekPayments": "40,000.00",
"resellerCurrentMonthPayments": "250,000.00",
"resellerLastMonthPayments": "230,000.00",
"resellerCurrentYearPayments": "2,310,000.00",
"resellerTotalPayments": "4,560,000.00",
"subresellerCurrentWeekPayments": "10,000.00",
"subresellerCurrentMonthPayments": "65,000.00",
"subresellerLastMonthPayments": "60,000.00",
"subresellerCurrentYearPayments": "610,000.00",
"subresellerTotalPayments": "1,180,000.00",
"retailerCurrentWeekPayments": "3,000.00",
"retailerCurrentMonthPayments": "18,000.00",
"retailerLastMonthPayments": "17,500.00",
"retailerCurrentYearPayments": "171,000.00",
"retailerTotalPayments": "322,500.00"
}
}Every value is a formatted amount string with a thousands separator and two decimals ("0.00" when there is nothing). Each group has five periods: currentWeek, currentMonth, lastMonth, currentYear and total.
| Group | What it adds up |
|---|---|
...Sales | Invoiced amounts of generated, paid, partly paid and due invoices, less migration credits |
...Profits | Profit ledger rows (reversals reduce it), with commission earned / owed on commission ISPs |
...Dues | The unpaid remainder of partly paid and due invoices |
subscriber...Payments | Subscriber payments |
reseller...Payments, subreseller...Payments, retailer...Payments | Balance payments to resellers, sub-resellers and retailers |
For a reseller-family user the sales, dues and subscriber payments are those of its own subscribers (subscriber_salesperson_id is the user) and the profit is its own.
Error Response (500 Server Error):
json
{
"status": "error",
"message": "Failed to fetch accounting statistics"
}No exception text, file or line is returned.
Code Examples:
bash
curl -X GET "https://your-domain.com/api/v1/dashboard/accounting-stats?isp_id=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer your-auth-token"php
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://your-domain.com']);
$response = $client->request('GET', '/api/v1/dashboard/accounting-stats', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer your-auth-token',
],
'query' => [
'isp_id' => 1,
],
]);
$data = json_decode($response->getBody(), true);
print_r($data);javascript
const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';
const params = new URLSearchParams({
isp_id: 1,
});
const response = await fetch(`${BASE_URL}/api/v1/dashboard/accounting-stats?${params}`, {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${TOKEN}`,
},
});
const data = await response.json();
console.log(data);python
import requests
BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"
response = requests.get(
f"{BASE_URL}/api/v1/dashboard/accounting-stats",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {TOKEN}",
},
params={
"isp_id": 1,
},
)
data = response.json()
print(data)go
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
const baseURL = "https://your-domain.com"
const token = "your-auth-token"
func main() {
endpoint := baseURL + "/api/v1/dashboard/accounting-stats"
q := url.Values{}
q.Set("isp_id", "1")
endpoint += "?" + q.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))
}rust
use reqwest::Client;
const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let response = client
.get(format!("{BASE_URL}/api/v1/dashboard/accounting-stats"))
.header("Accept", "application/json")
.bearer_auth(TOKEN)
.query(&[
("isp_id", "1"),
])
.send()
.await?;
let data: serde_json::Value = response.json().await?;
println!("{data:#}");
Ok(())
}User Stats
Retrieve the user counters: totals by status and by profile type, with percentages.
| Property | Value |
|---|---|
| Endpoint | User Stats |
| Method | GET |
| URL | /api/v1/dashboard/user-stats |
| Authentication | Bearer Token |
Request Headers:
| Header | Value | Required |
|---|---|---|
Accept | application/json | Yes |
Authorization | Bearer your-auth-token | Yes |
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
isp_id | integer | No | Your ISP ID. The counters always use your own ISP; another value is refused with 403 |
branch_id | integer | No | Your branch ID. The counters always use your own branch; another value is refused with 403 |
Request Body: None
Success Response (200 OK):
json
{
"status": "success",
"data": {
"totalUser": 48,
"activeUser": 45,
"disableUser": 3,
"totalAdmin": 1,
"totalStaff": 7,
"totalReseller": 12,
"totalSubreseller": 16,
"totalRetailer": 12,
"activeUserPct": "93.75%",
"disableUserPct": "6.25%",
"adminUserPct": "2.08%",
"staffUserPct": "14.58%",
"resellerUserPct": "25.00%",
"subresellerUserPct": "33.33%",
"retailerUserPct": "25.00%"
}
}The same 15 keys are always returned; with no users every count is 0 and every percentage "0.00%".
| Key | Counts |
|---|---|
totalUser | All users counted |
activeUser / disableUser | Users with status 1 / 0 |
totalAdmin | Admins (profile_type 1) |
totalStaff | Admin staff (profile_type 2) |
totalReseller, totalSubreseller, totalRetailer | Profile types 3, 4 and 5 |
...Pct | Each count as a share of totalUser |
Which users are counted: the admin side counts every user of the ISP and branch. A reseller counts the sub-resellers it created and the retailers of those sub-resellers; a sub-reseller counts its retailers; a retailer counts the users it created. Reseller staff get their parent's numbers.
Error Response (500 Server Error):
json
{
"status": "error",
"message": "Failed to fetch user statistics"
}No exception text, file or line is returned.
Code Examples:
bash
curl -X GET "https://your-domain.com/api/v1/dashboard/user-stats?isp_id=1" \
-H "Accept: application/json" \
-H "Authorization: Bearer your-auth-token"php
<?php
require 'vendor/autoload.php';
use GuzzleHttp\Client;
$client = new Client(['base_uri' => 'https://your-domain.com']);
$response = $client->request('GET', '/api/v1/dashboard/user-stats', [
'headers' => [
'Accept' => 'application/json',
'Authorization' => 'Bearer your-auth-token',
],
'query' => [
'isp_id' => 1,
],
]);
$data = json_decode($response->getBody(), true);
print_r($data);javascript
const BASE_URL = 'https://your-domain.com';
const TOKEN = 'your-auth-token';
const params = new URLSearchParams({
isp_id: 1,
});
const response = await fetch(`${BASE_URL}/api/v1/dashboard/user-stats?${params}`, {
method: 'GET',
headers: {
Accept: 'application/json',
Authorization: `Bearer ${TOKEN}`,
},
});
const data = await response.json();
console.log(data);python
import requests
BASE_URL = "https://your-domain.com"
TOKEN = "your-auth-token"
response = requests.get(
f"{BASE_URL}/api/v1/dashboard/user-stats",
headers={
"Accept": "application/json",
"Authorization": f"Bearer {TOKEN}",
},
params={
"isp_id": 1,
},
)
data = response.json()
print(data)go
package main
import (
"fmt"
"io"
"net/http"
"net/url"
)
const baseURL = "https://your-domain.com"
const token = "your-auth-token"
func main() {
endpoint := baseURL + "/api/v1/dashboard/user-stats"
q := url.Values{}
q.Set("isp_id", "1")
endpoint += "?" + q.Encode()
req, _ := http.NewRequest("GET", endpoint, nil)
req.Header.Set("Accept", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(resp.StatusCode, string(body))
}rust
use reqwest::Client;
const BASE_URL: &str = "https://your-domain.com";
const TOKEN: &str = "your-auth-token";
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
let client = Client::new();
let response = client
.get(format!("{BASE_URL}/api/v1/dashboard/user-stats"))
.header("Accept", "application/json")
.bearer_auth(TOKEN)
.query(&[
("isp_id", "1"),
])
.send()
.await?;
let data: serde_json::Value = response.json().await?;
println!("{data:#}");
Ok(())
}