Portfolio overview

Base URL: $BUSINESS_API

The object

root_account_idstring · required

The caller's tenant, at the root of the portfolio.

periodobject · required

Reporting month.

Show child attributes
labelstring · optional
startstring (date-time) · optional
endstring (date-time) · optional
currencystring · required

Currency shared by every account in the portfolio.

accountsarray of object · required

The root account first, then each readable descendant account.

Show child attributes
account_idstring · required
account_numberstring · optional

Number of the referenced account. Omitted when unknown.

account_holder_namestring · optional

Display name of the account holder. Omitted when unknown.

overviewobject · required

Domain totals and series are returned only when the caller has the corresponding domain read scope. Receivables require invoices:read or collections:read; collection_rate requires both invoices:read and payments:read. Portfolio overviews apply these checks separately to each account.

Show child attributes
periodobject · optional
currencystring · optional
billed_centsinteger (int64) · optional
collected_centsinteger (int64) · optional
volume_m3number · optional
readings_countinteger · optional
collection_ratenumber · optional

Percentage of the period's billed amount collected through payments applied to invoices billed in that period, capped at 100. Payments against earlier invoices are in arrears_collected_cents and do not raise this rate.

collected_current_period_centsinteger (int64) · optional

Part of collected_cents applied to invoices billed in the period

arrears_collected_centsinteger (int64) · optional

Part of collected_cents applied to invoices billed in earlier periods, or to no invoice

collections_by_hourobject · optional

Collections for the utility's local today and yesterday, independent of the requested period

Show child attributes
timezonestring · optional
todayobject · optional
yesterdayobject · optional
read_ratenumber · optional
open_workobject · optional
Show child attributes
incidentsinteger · optional
ticketsinteger · optional
work_ordersinteger · optional
receivables_by_ageingarray of object · optional
Show child attributes
balance_centsinteger · optional
bucketstring · optional
invoicesinteger · optional
seriesobject · optional
Show child attributes
billed_centsarray of SeriesPoint · optional
collected_centsarray of SeriesPoint · optional
volume_m3array of SeriesPoint · optional
readingsarray of SeriesPoint · optional
billed_centsinteger (int64) · required

Sum of billed_cents across the accounts.

collected_centsinteger (int64) · required

Sum of collected_cents across the accounts.

volume_m3number · required

Sum of volume_m3 across the accounts.

readings_countinteger · required

Sum of readings_count across the accounts.

seriesobject · required

Daily series summed across the accounts, oldest first.

Show child attributes
billed_centsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
collected_centsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
volume_m3array of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
readingsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
The object
{
  "root_account_id": "roo_202ZxesHbMupdaSf3oITN8C1tiu",
  "period": {
    "label": "2026-10",
    "start": "2026-11-19T09:30:00Z",
    "end": "2026-11-19T09:30:00Z"
  },
  "currency": "MZN",
  "accounts": [
    {
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "overview": {
        "period": {},
        "currency": "MZN",
        "billed_cents": 1,
        "collected_cents": 1,
        "volume_m3": 13.42,
        "readings_count": 1342,
        "collection_rate": 1,
        "collected_current_period_cents": 1,
        "arrears_collected_cents": 1,
        "collections_by_hour": {
          "timezone": "Africa/Maputo",
          "today": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          },
          "yesterday": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          }
        },
        "read_rate": 1,
        "open_work": {
          "incidents": 1,
          "tickets": 1,
          "work_orders": 1
        },
        "receivables_by_ageing": [
          {
            "balance_cents": 125000,
            "bucket": "bucket",
            "invoices": 1
          }
        ],
        "series": {
          "billed_cents": [
            {}
          ],
          "collected_cents": [
            {}
          ],
          "volume_m3": [
            {}
          ],
          "readings": [
            {}
          ]
        }
      }
    }
  ],
  "billed_cents": 1,
  "collected_cents": 1,
  "volume_m3": 13.42,
  "readings_count": 1342,
  "series": {
    "billed_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "collected_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "volume_m3": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "readings": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ]
  }
}

Get portfolio overview

Logs

GET /portfolio-overview

Overview totals across the caller's account and its sub-accounts

Builds the business overview for one month for the caller's own account and for every descendant account in its organization tree where the caller holds business:overview:read directly or through an inherited membership; owning the parent alone does not open the children. Each account is returned with its own overview, and billed, collected, volume and reading totals and daily series are summed across them. As in the single-account overview, each data group of each account is shown only when the caller holds that domain's read scope on that account (invoices:read, payments:read, collections:read, business:readings:read, business:consumptions:read, operations:read, support:read). Requires business:overview:read on the caller's tenant. A period that is not YYYY-MM returns 400, and accounts that report in different currencies return 409.

Parameters

periodstring · query · optional

Month to report as YYYY-MM, in UTC; defaults to the current month.

Returns

200 Portfolio overview

Show attributes
root_account_idstring · required

The caller's tenant, at the root of the portfolio.

periodobject · required

Reporting month.

Show child attributes
labelstring · optional
startstring (date-time) · optional
endstring (date-time) · optional
currencystring · required

Currency shared by every account in the portfolio.

accountsarray of object · required

The root account first, then each readable descendant account.

Show child attributes
account_idstring · required
account_numberstring · optional

Number of the referenced account. Omitted when unknown.

account_holder_namestring · optional

Display name of the account holder. Omitted when unknown.

overviewobject · required

Domain totals and series are returned only when the caller has the corresponding domain read scope. Receivables require invoices:read or collections:read; collection_rate requires both invoices:read and payments:read. Portfolio overviews apply these checks separately to each account.

Show child attributes
periodobject · optional
currencystring · optional
billed_centsinteger (int64) · optional
collected_centsinteger (int64) · optional
volume_m3number · optional
readings_countinteger · optional
collection_ratenumber · optional

Percentage of the period's billed amount collected through payments applied to invoices billed in that period, capped at 100. Payments against earlier invoices are in arrears_collected_cents and do not raise this rate.

collected_current_period_centsinteger (int64) · optional

Part of collected_cents applied to invoices billed in the period

arrears_collected_centsinteger (int64) · optional

Part of collected_cents applied to invoices billed in earlier periods, or to no invoice

collections_by_hourobject · optional

Collections for the utility's local today and yesterday, independent of the requested period

Show child attributes
timezonestring · optional
todayobject · optional
yesterdayobject · optional
read_ratenumber · optional
open_workobject · optional
Show child attributes
incidentsinteger · optional
ticketsinteger · optional
work_ordersinteger · optional
receivables_by_ageingarray of object · optional
Show child attributes
balance_centsinteger · optional
bucketstring · optional
invoicesinteger · optional
seriesobject · optional
Show child attributes
billed_centsarray of SeriesPoint · optional
collected_centsarray of SeriesPoint · optional
volume_m3array of SeriesPoint · optional
readingsarray of SeriesPoint · optional
billed_centsinteger (int64) · required

Sum of billed_cents across the accounts.

collected_centsinteger (int64) · required

Sum of collected_cents across the accounts.

volume_m3number · required

Sum of volume_m3 across the accounts.

readings_countinteger · required

Sum of readings_count across the accounts.

seriesobject · required

Daily series summed across the accounts, oldest first.

Show child attributes
billed_centsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
collected_centsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
volume_m3array of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional
readingsarray of SeriesPoint · optional
Show child attributes
datestring (date) · optional
valuenumber · optional

Errors 400 · 401 · 403 · 404 · 409

Permissions business:overview:read · Roles: admin, analyst, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/portfolio-overview" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "root_account_id": "roo_202ZxesHbMupdaSf3oITN8C1tiu",
  "period": {
    "label": "2026-10",
    "start": "2026-11-19T09:30:00Z",
    "end": "2026-11-19T09:30:00Z"
  },
  "currency": "MZN",
  "accounts": [
    {
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "overview": {
        "period": {},
        "currency": "MZN",
        "billed_cents": 1,
        "collected_cents": 1,
        "volume_m3": 13.42,
        "readings_count": 1342,
        "collection_rate": 1,
        "collected_current_period_cents": 1,
        "arrears_collected_cents": 1,
        "collections_by_hour": {
          "timezone": "Africa/Maputo",
          "today": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          },
          "yesterday": {
            "date": "2026-11-19",
            "total_cents": 125000,
            "hours": []
          }
        },
        "read_rate": 1,
        "open_work": {
          "incidents": 1,
          "tickets": 1,
          "work_orders": 1
        },
        "receivables_by_ageing": [
          {
            "balance_cents": 125000,
            "bucket": "bucket",
            "invoices": 1
          }
        ],
        "series": {
          "billed_cents": [
            {}
          ],
          "collected_cents": [
            {}
          ],
          "volume_m3": [
            {}
          ],
          "readings": [
            {}
          ]
        }
      }
    }
  ],
  "billed_cents": 1,
  "collected_cents": 1,
  "volume_m3": 13.42,
  "readings_count": 1342,
  "series": {
    "billed_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "collected_cents": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "volume_m3": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ],
    "readings": [
      {
        "date": "2026-11-19",
        "value": 13.42
      }
    ]
  }
}