# Aging Balances Report V1 — Developer Guide

> **Reference:** [GetAgingBalancesReport (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesreportv1)


## GET — Aging Balance Report

This endpoint returns an aging balance report for a location within your organization. Each response page contains a set of guarantor-level balance records, along with page-level aggregate totals across the standard aging buckets (current, 30, 60, 90+ days).

Charges are bucketed by the number of days elapsed since the transaction date at the time the request is made. The four buckets are: 0–30 days (current), 31–60 days, 61–90 days, and 90+ days.

> **Common use case:** Fetching all patient balances for an organization to backfill or sync financial data. Use the `page` filter to iterate through the full dataset.


### Required Filters

The following filters **must** be included on every request:

| Filter | Supported Operators | Description |
|  --- | --- | --- |
| `location.id` | `==` | The location to retrieve aging balance data for |


In addition to `location.id`, **one of the following must also be present**:

| Filter | Supported Operators | Description |
|  --- | --- | --- |
| `patient.id` | `->` | Fetch balances for specific guarantor patients. Up to 50 guarantor IDs per request. |
| `page` | `==` | Fetch a page of the location's full dataset. Use for paginating through all records in a location. |


### Optional Filters

Further narrow results with any of the following:

| Filter | Supported Operators | Description |
|  --- | --- | --- |
| `balance` | `==`, `!=`, `>`, `>=`, `<`, `<=` | Filter by total balance amount (`current + thirtyDays + sixtyDays + ninetyDays + unAppliedCredits`). Useful for excluding zero-balance guarantors. |
| `thirtyDays` | `==`, `!=`, `>`, `>=`, `<`, `<=` | Filter by dollar amount in the 31–60 days aging bucket. |
| `sixtyDays` | `==`, `!=`, `>`, `>=`, `<`, `<=` | Filter by dollar amount in the 61–90 days aging bucket. |
| `ninetyDays` | `==`, `!=`, `>`, `>=`, `<`, `<=` | Filter by dollar amount in the 90+ days aging bucket. |


> See the endpoint reference for the full up-to-date list of supported parameters.
[Get AgingBalances Report](https://papidocs.hs1api.com/publicapi/api-financial-management/agingbalances-(v1)/getagingbalancesreportv1)


### Important Notes

> **⚠️ Rate Limited:** This endpoint is rate limited. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) for details.


> **✅ Tip:** Use `balance>=1` to exclude guarantors with zero balances and reduce response size when only actionable balances are needed.


### Example Requests

Fetch by specific guarantor patient IDs:

```
GET /api/v1/agingbalances/report?filter=location.id==123,patient.id->[456,789]
```

Fetch page 1 of the full location dataset:

```
GET /api/v1/agingbalances/report?filter=location.id==123,page==1
```

Fetch page 2:

```
GET /api/v1/agingbalances/report?filter=location.id==123,page==2
```

With an optional balance filter to exclude zero-balance guarantors:

```
GET /api/v1/agingbalances/report?filter=location.id==123,page==1,balance>=1
```

## Paginating with `page`

When fetching all balance data for a location, use the `page` filter to iterate through the full dataset one page at a time.

### Step 1 — Fetch Page 1

Send your first request with `page==1`:

```
GET /api/v1/agingbalances/report?filter=location.id==123,page==1
```

The **first page response is the only page that includes `meta.pagination`**. This object provides:

- `meta.pagination.limit` — the number of **transactions searched** per page (not the count of records in `data`)
- `meta.pagination.total` — the total number of **transactions** across all pages (not the total number of guarantor records)


> **Why transactions, not records?** The limit and total values reflect the underlying transaction search window rather than the count of `patientReports` objects returned. This design prevents endpoint timeouts on large datasets. The number of records in `data` per page will vary.


### Step 2 — Determine Total Pages

Use the values from page 1's `meta.pagination` to calculate how many pages to fetch:

```
totalPages = ceil(meta.pagination.total / meta.pagination.limit)
```

### Step 3 — Fetch Remaining Pages

Increment the `page` value and repeat until you have fetched all pages. Pages after page 1 will **not** include a `meta` object in the response.

### Step 4 — Aggregate Totals Across Pages

To produce accurate organization-wide report numbers, **sum the numeric fields across all pages**:

- Sum `currentAmount`, `thirtyDaysAmount`, `sixtyDaysAmount`, `ninetyDaysAmount`, `total`, `unappliedCreditsAmount`, and `balance` from each page's top-level `data` object.


> **Important exception:** Do **not** sum `claimsPending` across pages. The `claimsPending` value on each record inside `patientReports` is a per-guarantor count of pending insurance claims at the time of the request. Adding it across pages would double-count claims. Read each guarantor's `claimsPending` value individually.


## Response Structure

A successful `200` response returns the following top-level structure:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | Page-level aggregate totals and per-guarantor records (see below) |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |
| `meta` | object | Pagination metadata — **only present on page 1** |


### `meta.pagination` Object (Page 1 only)

| Field | Type | Description |
|  --- | --- | --- |
| `limit` | integer | Number of transactions searched per page. Use with `total` to calculate the total page count. |
| `total` | integer | Total number of transactions across all pages. **Not** the total number of guarantor records. |


### `data` Object

The `data` object contains page-level aggregate totals summed across all guarantor records in `patientReports` on the current page. **These values must be summed across all pages to get organization-wide totals.**

| Field | Type | Description |
|  --- | --- | --- |
| `currentAmount` | number | Sum of all guarantor `current` (0–30 day) charge balances on this page |
| `currentPortion` | object | Page aggregate of 0–30 day balances split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `thirtyDaysAmount` | number | Sum of all guarantor 31–60 day charge balances on this page |
| `thirtyDaysPortion` | object | Page aggregate of 31–60 day balances split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `sixtyDaysAmount` | number | Sum of all guarantor 61–90 day charge balances on this page |
| `sixtyDaysPortion` | object | Page aggregate of 61–90 day balances split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `ninetyDaysAmount` | number | Sum of all guarantor 90+ day charge balances on this page |
| `ninetyDaysPortion` | object | Page aggregate of 90+ day balances split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `total` | number | Sum of all four aging bucket amounts: `currentAmount + thirtyDaysAmount + sixtyDaysAmount + ninetyDaysAmount` |
| `totalPortions` | object | Page aggregate of all bucket totals split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `unappliedCreditsAmount` | number | Sum of all unapplied credit amounts across guarantors on this page. Credits that exist on an account but have not yet been applied to a charge. |
| `balance` | number | `total + unappliedCreditsAmount` — the net outstanding balance for this page |
| `patientReports` | array | Array of guarantor balance records — see below. Present when patient data exists; may be empty. |


### Records in `patientReports`

Each record in the `patientReports` array represents the aging balance for a single **guarantor**. Charges belonging to all patients under the guarantor's responsibility are included and bucketed by the number of days since their transaction date.

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Guarantor patient ID |
| `firstName` | string | Guarantor first name |
| `lastName` | string | Guarantor last name |
| `current` | number | Total charge balance for transactions dated 0–30 days ago |
| `currentPortion` | object | 0–30 day balance split by responsible party: `guarantorPortion` (patient-responsible share), `insurancePortion` (estimated insurance share), `writeOff` (write-off adjustments) |
| `thirtyDays` | number | Total charge balance for transactions dated 31–60 days ago |
| `thirtyDaysPortion` | object | 31–60 day balance split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `sixtyDays` | number | Total charge balance for transactions dated 61–90 days ago |
| `sixtyDaysPortion` | object | 61–90 day balance split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `ninetyDays` | number | Total charge balance for transactions dated more than 90 days ago |
| `ninetyDaysPortion` | object | 90+ day balance split by responsible party: `guarantorPortion`, `insurancePortion`, `writeOff` |
| `balance` | number | `current + thirtyDays + sixtyDays + ninetyDays + unAppliedCredits` — total net balance for this guarantor |
| `guarantorPortionBalance` | number | Sum of `guarantorPortion` across all aging buckets plus `unAppliedCredits` — the total patient-responsible balance |
| `insurancePortionBalance` | number | Sum of `insurancePortion` across all aging buckets — the total estimated insurance-responsible balance |
| `writeOffBalance` | number | Sum of `writeOff` across all aging buckets — total write-off adjustments for this guarantor |
| `unAppliedCredits` | number | Total unapplied credit amount — payments or credits on the account that have not yet been applied to an outstanding charge |
| `claimsPending` | number | Count of pending insurance claims across all patients under this guarantor. **Do not sum across pages** — this is a point-in-time count per guarantor, not a dollar amount. |


## Errors & Warnings Reference

details
summary
strong
HTTP Status Code Errors
— click to expand
These apply to all Aging Balances V1 endpoints.

#### `400` — Bad Request

The request query parameters are invalid or cannot be processed. See the [Field-Level Validation Errors](#field-level-validation-errors) section below for specific causes.

#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Why** | No valid auth token was sent, the token is expired, or the token is malformed. |
| **Fix** | Provide a valid Bearer token in the `Authorization` header. |


#### `403` — Forbidden

|  |  |
|  --- | --- |
| **Message** | The request is understood, but it has been refused or access is not allowed. |
| **Why** | The authenticated token does not have the required scope. Read operations require `model:read`. |
| **Fix** | Request a token that includes the `model:read` scope. |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No aging balance data exists for the given filter criteria within your organization, or a referenced ID (e.g. `location.id`, `patient.id`) does not exist or belong to your organization. |
| **Fix** | Confirm all filter IDs are correct and belong to your organization. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Why** | The server took too long to respond, often due to a large dataset, complex filters, or high server load. |
| **Fix** | Retry the request. If the issue persists, reduce the number of `patient.id` values per request or contact support. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Why** | Your client has made too many requests in a short period of time. |
| **Fix** | Implement exponential backoff and retry logic. Reduce request frequency. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting). |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Why** | An unhandled server-side error occurred. |
| **Fix** | Retry the request. If the issue persists, contact support with the request details and timestamp. |


details
summary
strong
Field-Level Validation Errors
— click to collapse
These errors are returned in the `errors` array of the response body alongside a `400` status code.

### `location.id`

**Error:** `location.id` is required and must not be empty.

|  |  |
|  --- | --- |
| **Why** | The `location.id` filter is required on every request. It was omitted or left empty. |
| **Fix** | Include `location.id==<id>` in your `filter` query parameter, e.g. `filter=location.id==123,page==1`. |


### `patient.id` / `page`

**Error:** Either `patient.id` or `page` filter must be present.

|  |  |
|  --- | --- |
| **Why** | Neither a `patient.id` list nor a `page` number was provided alongside `location.id`. One of the two is required on every request. |
| **Fix** | Include either `patient.id->[id1,id2]` or `page==<number>` in your `filter` query parameter. |


### `patient.id`

**Error:** `patient.id` values must be guarantor patients. Maximum 50 IDs per request.

|  |  |
|  --- | --- |
| **Why** | One or more of the provided `patient.id` values are not guarantor-type patients, or more than 50 IDs were supplied. |
| **Fix** | Ensure all IDs belong to guarantor patients and limit the list to 50 or fewer per request. |