# Agingbalances (V1)

Agingbalances endpoints

## Returns AgingBalanceV1 for patient.

 - [GET /v1/agingbalances](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesv1.md)

## Returns AgingBalanceV1 for patient.
This endpoint requires either patient.id or page filters be present in the request, see "filter" details below for more info on how to use them properly.

 - [GET /v1/agingbalances/report](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesreportv1.md): Returns AgingBalanceReportV1: rolled-up bucket totals for the location (or for the requested guarantor patients),
plus patientReports with one AgingReceivableV1 per guarantor row.

Filter requirement: Provide either filter=patient.id->[...] (with location.id) or filter=page==n (with
location.id) for the paginated location report—not both. See the filter parameter for operators and notes on
meta.pagination.

Note: If responseFields is supplied, it is validated against an internal allowlist but the report JSON is not
filtered by those names (the payload shape is always the full AgingBalanceReportV1).

Rate limiting: Documented on this operation (not on AgingBalanceReportV1 / AgingReceivableV1 schemas). Subject to
standard Public API rate limits; on HTTP 429 use Retry-After and Rate-Limiting-Remaining as documented for the API.
Overview: https://portal.hs1api.com/guide

MCP (first successful call): use a real location.id from GET /v1/locations, e.g.
filter=location.id==12345678901234,page==1 (paginated location report). location.id alone is not sufficient.

MCP (when page==1 fails): A 400 validation response whose message is "No more data was found" has
been observed when the paginated location report has no guarantor rows to return (for example an empty or
sparse dataset). That is distinct from “invalid filter syntax.” In those cases, call again with
filter=location.id==…,patient.id->[guarantorPatientId,…] (guarantor patient IDs, up to 50) instead of relying on
page alone, or confirm the organization has aging balances for that location.