Reference: GetAgingBalances (V1) Endpoint Documentation
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 endpoint instead.
| 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. |
| 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. |
⚠️ Rate Limited: This endpoint is rate limited. See the rate limiting guide for details.
Fetch balance for a specific patient (patient scope):
GET /api/v1/agingbalances?patientId=12000006542062&ownership=PATIENTFetch balance for a guarantor (includes all dependents, payment plan fields):
GET /api/v1/agingbalances?patientId=12000006542062&ownership=GUARANTORA 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 |
Each field represents the aging balance for the requested patient or guarantor. All monetary values are in dollars, rounded to two decimal places.
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 |
| 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. |
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. |
| 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. |
HTTP Status Code Errors — click to expand
These apply to all Aging Balances V1 endpoints.
The request query parameters are invalid or cannot be processed. See the Field-Level Validation Errors section below for specific causes.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
Field-Level Validation Errors — click to collapse
These errors are returned in the errors array of the response body alongside a 400 status code.
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. |
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. |