Dashboard API

Base URL: /api/dashboard

This document describes the Dashboard endpoints that power the admin and client home views. All endpoints are JSON over HTTPS.

Authentication & Authorization

• Auth: Bearer token (JWT) via Authorization: Bearer <token> header.
• Roles:
  • admin — can access / and /upcomingInstallments.
  • client — can access /client.
• Content-Type: application/json for all responses and request bodies.

---

GET /api/dashboard

Return high‑level KPIs for admins plus installment groups that currently have unpaid installments due. Requires the admin role.

Query Parameters

Name	Type	Required	Description
company	number	Yes	Company ID to scope results.
from	string (YYYY-MM-DD)	No	Inclusive start date to filter group creation date.
to	string (YYYY-MM-DD)	No	Inclusive end date to filter group creation date.

If from and to are provided they are interpreted in server timezone, expanded to the start/end of day.

Response: 200 OK

{
  "topAgents": [
    { "userId": 12, "userName": "Alex Kim", "groupsAssigned": 7 }
  ],
  "revenueShares": [
    {
      "projectId": 101,
      "projectName": "Harbor Views",
      "projectRevenue": 12500000,
      "revenuePercentage": 42.86
    }
  ],
  "filteredInstallmentGroups": [
    {
      "id": 33,
      "projectName": "Harbor Views",
      "address": "Dubai",
      "developerName": "MHP Dev Co",
      "unitNumber": "A-1204",
      "allowedUsers": [ { "userId": 5, "userName": "Sam" } ]
    }
  ]
}

Field Details

• topAgents[].groupsAssigned — count of distinct installment groups linked to the agent’s clients in the window.
• revenueShares[].projectRevenue — sum of installment amounts for the project.
• revenueShares[].revenuePercentage — per‑project share of total revenue in the window (0–100, 2 decimals).
• filteredInstallmentGroups — only groups that have at least one non‑fee installment that is unpaid and whose dueDate is on or before today.

Errors

• 400 — { "message": "Invalid company ID" }
• 500 — { "message": "Error retrieving dashboard data" }

---

GET /api/dashboard/upcomingInstallments

Paginated view of installment groups that currently have due unpaid installments, sorted by the nearest due date. Requires the admin role.

Query Parameters

Name	Type	Required	Default	Description
company	number	Yes	—	Company ID to scope results.
page	number	No	1	1‑based page index.
pageSize	number	No	5	Page size.

Response: 200 OK

{
  "filteredInstallmentGroups": [
    {
      "id": 33,
      "projectName": "Harbor Views",
      "address": "Dubai",
      "developerName": "MHP Dev Co",
      "unitNumber": "A-1204",
      "allowedUsers": [ { "userId": 5, "userName": "Sam" } ],
      "pendingAmount": 245000,
      "nextDueDate": "2025-02-02T00:00:00.000Z"
    }
  ],
  "hasMore": true,
  "totalInstallments": 27
}

Field Details

• pendingAmount — sum of amounts for all unpaid installments in the group whose dueDate is before today.
• nextDueDate — soonest due date (ISO‑8601) among the group’s unpaid non‑fee installments.
• hasMore — true if more pages exist beyond the returned slice.

Errors

• 400 — { "message": "Invalid company ID" }
• 500 — { "message": "Error retrieving dashboard data" }

---

GET /api/dashboard/client

Return the client’s personal dashboard summary, a progress snapshot for each of their installment groups, and small lists for upcoming installments and recent transactions. Requires the client role.

Query Parameters

None.

Response: 200 OK

{
  "summary": {
    "totalPayments": 880000,
    "totalExpenses": 0,
    "totalInstallments": 1200000,
    "totalInstallmentsPaid": 880000,
    "remainingInstallments": 320000
  },
  "installmentGroups": [
    {
      "groupId": 55,
      "groupName": "Sunset Residences — Tower B",
      "totalAmount": 1200000,
      "paidAmount": 880000,
      "remainingAmount": 320000,
      "progress": "73.33"
    }
  ],
  "upcomingInstallments": [
    {
      "id": 901,
      "groupName": "Sunset Residences — Tower B",
      "amount": 40000,
      "dueDate": "2025-03-01"
    }
  ],
  "recentTransactions": [
    {
      "id": 321,
      "amount": 40000,
      "paymentType": "income",
      "description": "Installment 8",
      "paymentDate": "2025-01-15T10:22:00.000Z",
      "serviceType": "installment"
    }
  ]
}

Field Details

• summary.totalPayments / totalExpenses — totals for the authenticated client (income vs. expense).
• installmentGroups — one row per group owned by the client; progress is a percentage string (0–100) with two decimals.
• upcomingInstallments — up to 5 future‑dated installments ordered by due date (inclusive of today and later).
• recentTransactions — up to 5 most recent client payments (newest first).

Errors

• 500 — { "message": "Error retrieving dashboard data" }

---

Conventions

• Dates & Times — Unless noted otherwise, timestamps are ISO‑8601 strings (UTC). Query parameters from/to expect YYYY-MM-DD.
• Currencies — All monetary fields are numeric AED amounts.
• Installment Filtering — Fee installments are excluded from dashboard overdue/due logic.

Pagination

• For /upcomingInstallments, use page and pageSize to navigate. A hasMore flag indicates another page is available.

Rate Limiting & Idempotency

• (If applicable in your deployment) Apply your gateway’s default limits. GET requests are safe to retry.

Examples

cURL — Admin overview

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  "https://<host>/api/dashboard?company=1&from=2025-01-01&to=2025-01-31"

cURL — Upcoming installments (page 2)

curl -H "Authorization: Bearer <ADMIN_TOKEN>" \
  "https://<host>/api/dashboard/upcomingInstallments?company=1&page=2&pageSize=10"

cURL — Client dashboard

curl -H "Authorization: Bearer <CLIENT_TOKEN>" \
  "https://<host>/api/dashboard/client"