# Aging Balances V1 — Developer Guide

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


## GET — Patient Aging Balance

This endpoint returns the aging balance for a single patient or guarantor. It is suited for real-time lookups — for example, displaying a patient's current balance during a visit or responding to a customer support inquiry.

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.

> **Looking to fetch balances for all patients in a location?** Use the [Aging Balances Report V1](/publicapi/endpoints/agingbalancesreport-v1) endpoint instead.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `patientId` | query | Yes | integer | The ID of the patient to retrieve a balance for |
| `ownership` | query | No | string | Scope of the balance calculation. Enum: `GUARANTOR` or `PATIENT`. Defaults to `PATIENT`. |


#### `ownership` Values

| Value | Description |
|  --- | --- |
| `PATIENT` | Returns the aging balance scoped to the individual patient only — their own charges and credits |
| `GUARANTOR` | Returns the aging balance scoped to the guarantor — includes charges and credits for all patients the guarantor is financially responsible for. Also includes `pleasePayAmount` and `closeablePaymentPlanState`. |


### 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.


### Example Requests

Fetch balance for a specific patient (patient scope):

```
GET /api/v1/agingbalances?patientId=12000006542062&ownership=PATIENT
```

Fetch balance for a guarantor (includes all dependents, payment plan fields):

```
GET /api/v1/agingbalances?patientId=12000006542062&ownership=GUARANTOR
```

## Response Structure

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

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object | The aging balance object (see below) |
| `warnings` | array | Non-fatal warnings (operation still succeeded) |
| `errors` | array | Field-level or structural errors |


### `data` Object

Each field represents the aging balance for the requested patient or guarantor. All monetary values are in dollars, rounded to two decimal places.

#### Aging Buckets

Charges are distributed into aging buckets based on the number of days since the transaction date.

| Field | Type | Description |
|  --- | --- | --- |
| `current` | number | Total charge balance for transactions dated 0–30 days ago |
| `currentInsurancePortion` | number | Estimated insurance-responsible share of the 0–30 day charges |
| `currentPatientPortion` | number | Patient-responsible share of the 0–30 day charges (`current - currentInsurancePortion - currentWriteOff`) |
| `currentWriteOff` | number | Write-off adjustments applied to 0–30 day charges |
| `thirtyDays` | number | Total charge balance for transactions dated 31–60 days ago |
| `thirtyDaysInsurancePortion` | number | Estimated insurance-responsible share of the 31–60 day charges |
| `thirtyDaysPatientPortion` | number | Patient-responsible share of the 31–60 day charges |
| `thirtyDaysWriteOff` | number | Write-off adjustments applied to 31–60 day charges |
| `sixtyDays` | number | Total charge balance for transactions dated 61–90 days ago |
| `sixtyDaysInsurancePortion` | number | Estimated insurance-responsible share of the 61–90 day charges |
| `sixtyDaysPatientPortion` | number | Patient-responsible share of the 61–90 day charges |
| `sixtyDaysWriteOff` | number | Write-off adjustments applied to 61–90 day charges |
| `ninetyDays` | number | Total charge balance for transactions dated more than 90 days ago |
| `ninetyDaysInsurancePortion` | number | Estimated insurance-responsible share of the 90+ day charges |
| `ninetyDaysPatientPortion` | number | Patient-responsible share of the 90+ day charges |
| `ninetyDaysWriteOff` | number | Write-off adjustments applied to 90+ day charges |


#### Totals

| Field | Type | Description |
|  --- | --- | --- |
| `balance` | number | Net outstanding balance: `(current + thirtyDays + sixtyDays + ninetyDays) + suspendedCredits` |
| `insurancePortion` | number | Total estimated insurance-responsible balance across all aging buckets |
| `patientPortion` | number | Total patient-responsible balance: `balance - insurancePortion - writeOffAdjustments` |
| `writeOffAdjustments` | number | Total write-off adjustments across all aging buckets |
| `suspendedCredits` | number | Unapplied credits on the account — payments or credits that have not yet been applied to an outstanding charge. These reduce the net `balance`. |


#### Payment Plan Fields

These fields are only populated when `ownership=GUARANTOR` and an active payment plan exists for the guarantor.

| Field | Type | Description |
|  --- | --- | --- |
| `pleasePayAmount` | number | The next scheduled payment amount due under the guarantor's active payment plan. `0` if no active payment plan exists. |
| `closeablePaymentPlanState` | boolean | `true` if the guarantor has an active payment plan and conditions are met to close it (e.g. the last payment has been received). `false` otherwise. |


#### Coverage

| Field | Type | Description |
|  --- | --- | --- |
| `hasCoverageGap` | boolean | `true` if a gap in insurance coverage was detected while calculating insurance portions for this patient. Indicates some charges may have no insurance coverage applied. |


## 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 patient exists for the given `patientId` within your organization, or the ID is invalid. |
| **Fix** | Confirm the `patientId` is correct and belongs 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 high server load. |
| **Fix** | Retry the request. If the issue persists, contact support with the request details and timestamp. |


#### `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.

### `patientId`

**Error:** Invalid patient ID.

|  |  |
|  --- | --- |
| **Why** | The `patientId` query parameter was omitted, is `0`, or is not a valid integer. |
| **Fix** | Provide a valid integer `patientId` greater than `0`, e.g. `?patientId=12000006542062`. |


### `ownership`

**Error:** Invalid value for `ownership`.

|  |  |
|  --- | --- |
| **Why** | The `ownership` value provided is not a recognized enum. |
| **Fix** | Use one of the following valid values: `GUARANTOR`, `PATIENT`. |