> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Patient Balances

> Fetch patient responsibility balances (PR buckets, paid, outstanding) and unallocated credits for a patient.

## Overview

Returns patient responsibility balances for a patient using the same PR bucket model as the patient balances UI (PR-1 deductible, PR-3 copay, PR-2 coinsurance, other PR), minus write-offs and paid amounts. Also returns unallocated patient credits.

## Authentication

JWT Bearer token from `/api/token`.

## Query Parameters

<ParamField query="patientFhirId" type="string" required>
  FHIR Patient id.
</ParamField>

## Example

```bash theme={null}
curl "https://forecaster.cairhealth.com/api/patient-payments/balances?patientFhirId=PatientId123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "patientFhirId": "PatientId123",
    "unallocatedCreditTotal": 25.0,
    "unallocatedCredits": [
      {
        "id": "credit-uuid",
        "paymentAmount": 25.0,
        "paymentDate": "2024-01-15T00:00:00.000Z",
        "paymentMethod": "Credit Card",
        "paymentTraceId": "pi_123",
        "notes": null,
        "createdAt": "2024-01-15T12:00:00.000Z"
      }
    ],
    "claims": [
      {
        "claimId": "claim-uuid",
        "claimFhirId": "fhir-claim-id",
        "claimLifecycleId": "lifecycle-uuid",
        "patientResponsibilityTotal": 100.0,
        "prDeductible": 40.0,
        "prCopay": 20.0,
        "prCoinsurance": 30.0,
        "prOther": 10.0,
        "patientWriteOffTotal": 0,
        "patientPaidAmount": 25.0,
        "netOutstandingBalance": 75.0,
        "paymentDetails": {
          "paymentAmount": 25.0,
          "paymentDate": "2024-01-10T00:00:00.000Z",
          "paymentMethod": "Credit Card",
          "paymentTraceId": "pi_abc",
          "postedByEmail": "patient-payment-webhook"
        }
      }
    ]
  }
}
```


## OpenAPI

````yaml GET /api/patient-payments/balances
openapi: 3.1.0
info:
  title: Cair Health APIs
  description: APIs for the Cair Health platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://forecaster.cairhealth.com
security:
  - bearerAuth: []
paths:
  /api/patient-payments/balances:
    get:
      description: >-
        Fetch patient responsibility balances (PR buckets, paid, outstanding)
        and unallocated credits for a patient.
      parameters:
        - name: patientFhirId
          in: query
          required: true
          schema:
            type: string
          description: FHIR Patient id
      responses:
        '200':
          description: Balances fetched successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: object
                    properties:
                      patientFhirId:
                        type: string
                      unallocatedCreditTotal:
                        type: number
                      unallocatedCredits:
                        type: array
                        items:
                          type: object
                      claims:
                        type: array
                        items:
                          type: object
        '400':
          description: Missing patientFhirId
        '401':
          description: Unauthorized
        '404':
          description: Organization not found
        '500':
          description: Server error
      security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````