Skip to content

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_type 6 / 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).

PropertyValue
EndpointSubscriber Stats
MethodGET
URL/api/v1/dashboard/subscriber-stats
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Query Parameters:

ParameterTypeRequiredDescription
isp_idintegerNoYour ISP ID. The counters always use your own ISP; another value is refused with 403
branch_idintegerNoYour 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%".

KeyCounts
totalAll subscribers you may see (totalPCT is "100.00%", or "0.00%" when total is 0)
newActive subscribers created in the last 7 days
registerSubscribers in status Registered (profile_status 1)
activeSubscribers in status Active (profile_status 2)
disableSubscribers in status Disabled (profile_status 3)
terminateSubscribers in status Terminated (profile_status 4)
pppoePPPoE subscribers (connection_type 1)
hotspotHotspot subscribers (connection_type 2)
onlineSubscribers online now
expiredOnlineExpired subscribers that are still online
offlinetotal minus online (never below 0)
totalExpiredSubscribers whose expiration has passed
expiring1DaySubscribers whose RADIUS expiration falls in the next 24 hours
expiring3DaysSubscribers whose RADIUS expiration falls in the next 3 days
expiring1WeekSubscribers expiring within 1 week
expiring2WeeksSubscribers expiring within 2 weeks
expiring4WeeksSubscribers 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.

PropertyValue
EndpointAccounting Stats
MethodGET
URL/api/v1/dashboard/accounting-stats
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Query Parameters:

ParameterTypeRequiredDescription
isp_idintegerNoYour ISP ID. The counters always use your own ISP; another value is refused with 403
branch_idintegerNoYour 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.

GroupWhat it adds up
...SalesInvoiced amounts of generated, paid, partly paid and due invoices, less migration credits
...ProfitsProfit ledger rows (reversals reduce it), with commission earned / owed on commission ISPs
...DuesThe unpaid remainder of partly paid and due invoices
subscriber...PaymentsSubscriber payments
reseller...Payments, subreseller...Payments, retailer...PaymentsBalance 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.

PropertyValue
EndpointUser Stats
MethodGET
URL/api/v1/dashboard/user-stats
AuthenticationBearer Token

Request Headers:

HeaderValueRequired
Acceptapplication/jsonYes
AuthorizationBearer your-auth-tokenYes

Query Parameters:

ParameterTypeRequiredDescription
isp_idintegerNoYour ISP ID. The counters always use your own ISP; another value is refused with 403
branch_idintegerNoYour 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%".

KeyCounts
totalUserAll users counted
activeUser / disableUserUsers with status 1 / 0
totalAdminAdmins (profile_type 1)
totalStaffAdmin staff (profile_type 2)
totalReseller, totalSubreseller, totalRetailerProfile types 3, 4 and 5
...PctEach 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(())
}

www.onezeroart.com