Skip to main content
GET
List family balances and ledgers

Authorizations

Authorization
string
header
required

Access token issued by POST /sessions and associated with a valid server-side session.

Query Parameters

company_id
string<uuid>
required

Company UUID. Must equal the authenticated session company when that session has a company assigned; the equality check is skipped for sessions without one.

school_id
string<uuid>

School UUID. Omit to use the operation's documented company/session scope.

school_ids
string<uuid>[]

Optional school UUID filter. When school_id is also supplied, both filters apply. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

family_ids
string<uuid>[]

Optional family UUIDs; balance row view only. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

family_name
string

Case-insensitive family-name substring filter; balance rows and aggregates.

balance_min
number

Inclusive minimum balance; balance rows and aggregates.

balance_max
number

Inclusive maximum balance; balance rows and aggregates.

fields
enum<string>[]

Select response properties. Unknown names return 400. Default: family_id, family_name, balance, transaction_date. Balance row view only. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:
family_id,
school_id,
family_name,
family_student_count,
transaction_id,
transaction_date,
amount,
balance,
receipt_number,
kind
sort_by
string

Rows: balance, family_name or transaction_date with _asc/_desc. Aggregates: group or a supported metric with _asc/_desc. Unsupported keys use the backend default. Defaults: balance_desc for rows, count_desc for aggregates.

view
enum<string>

Read per-family transaction ledgers; takes precedence over grouping.

Available options:
transactions
last_n_days
integer
default:30

Transactions only: defaults to 30 and clamps to 0 through 365.

group_by
enum<string>

Select an aggregate representation; metrics must also be supplied.

Available options:
school_id,
family_id,
family_name
metrics
enum<string>[]

Metrics to calculate; required with group_by and invalid without it. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed.

Available options:
count,
sum_balance,
avg_balance,
min_balance,
max_balance,
sum_positive_balance,
sum_negative_balance,
count_zero_balance
limit
integer
default:50

Aggregate result limit. Defaults to 50 and clamps values above 200 to 200. Zero and negative values use the default.

page
integer
default:1

One-based page number. Balance rows clamp at 200; view=transactions instead clamps at 500.

Required range: x >= 1
per_page
integer
default:100

Items per page; values greater than 200 are clamped to 200. Balance rows clamp at 200; view=transactions instead clamps at 500.

Required range: x >= 1

Response

Successful response.

A sparse row containing only the selected fields. Default fields: family_id, family_name, balance, transaction_date.

family_id
string

Family id.

school_id
string

School id.

family_name
string
family_student_count
integer
transaction_id
string

Transaction id.

transaction_date
string<date>
amount
number
balance
number
receipt_number
string
kind
string