Get Patient Balances

GET

api

patient-payments

balances

cURL

curl --request GET \
  --url https://forecaster.cairhealth.com/api/patient-payments/balances

const options = {method: 'GET'};

fetch('https://forecaster.cairhealth.com/api/patient-payments/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://forecaster.cairhealth.com/api/patient-payments/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://forecaster.cairhealth.com/api/patient-payments/balances"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://forecaster.cairhealth.com/api/patient-payments/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "patientId": "<string>",
    "patientFhirId": "<string>",
    "currentBalance": 123,
    "lastPayment": {
      "paymentAmount": 123,
      "paymentDate": "2023-11-07T05:31:56Z",
      "paymentMethod": "<string>",
      "paymentTraceId": "<string>"
    },
    "unallocatedCreditTotal": 123,
    "unallocatedCredits": [
      {}
    ],
    "manualCharges": [
      {}
    ],
    "claims": [
      {}
    ]
  }
}

Overview

Returns patient balances aligned with the Patient Balances chart: outstanding is max(0, PATIENT_AR) per claim (Insurance Balance Forward lifecycles excluded), paid is ledger PATIENT_AR credits (PATIENT_PAYMENT / OPENING_BALANCE / PATIENT_CREDIT_ALLOCATION), and unallocated credits are the state-based PATIENT_CASH total. Also returns:

currentBalance — same formula as the chart Payment Summary: max(0, Σ claim outstanding + Σ manual remaining − unallocated credits)
lastPayment — newest payment from the Transactions ledger (listPatientPaymentTransactionsFromLedger): amount, date, method, trace id
Manual charges with ledger remainingBalance (and gross patientBalance)

Look up the patient with your external patientId. Resolution uses the org integration patients.patientIdentifierSystem when set; otherwise Cair’s default https://fhir.cairhealth.com/fhir/identifier/customer-patient-id (cairProfessional and similar).

Authentication

JWT Bearer token from /api/token.

Query Parameters

string

required

External patient id (integration patientIdentifierSystem, or customer-patient-id by default).

Example

curl "https://forecaster.cairhealth.com/api/patient-payments/balances?patientId=EXT-PAT-123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Response

{
  "success": true,
  "data": {
    "patientId": "EXT-PAT-123",
    "patientFhirId": "PatientId123",
    "currentBalance": 75.0,
    "lastPayment": {
      "paymentAmount": 100.0,
      "paymentDate": "2024-01-10T00:00:00.000Z",
      "paymentMethod": "Credit Card",
      "paymentTraceId": "pi_prev"
    },
    "unallocatedCreditTotal": 25.0,
    "unallocatedCredits": [
      {
        "id": "ledger-event-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"
      }
    ],
    "manualCharges": [
      {
        "id": "manual-charge-uuid",
        "description": "Lab fee",
        "date": "2024-01-05T00:00:00.000Z",
        "patientBalance": 50.0,
        "remainingBalance": 25.0,
        "allocatedPaid": 25.0,
        "charge": 50.0,
        "payment": null
      }
    ],
    "claims": [
      {
        "claimId": "claim-uuid",
        "claimFhirId": "fhir-claim-id",
        "claimLifecycleId": "lifecycle-uuid",
        "isSelfPay": false,
        "patientResponsibilityTotal": 100.0,
        "prDeductible": 0,
        "prCopay": 0,
        "prCoinsurance": 0,
        "prOther": 75.0,
        "patientWriteOffTotal": 0,
        "patientPaidAmount": 25.0,
        "netOutstandingBalance": 75.0,
        "paymentDetails": {
          "paymentAmount": 25.0,
          "paymentDate": "2024-01-15T00:00:00.000Z",
          "paymentMethod": "Credit Card",
          "paymentTraceId": "pi_123",
          "postedByEmail": "patient-payment-webhook"
        }
      }
    ]
  }
}

currentBalance matches the patient chart Outstanding Balance. lastPayment is the most recent Transactions-tab payment (true payment amount + date), or null when none exist. patientPaidAmount and per-claim paymentDetails.paymentAmount are lifecycle total paid (not the last payment alone). Prefer top-level lastPayment for “last payment $ on date”. netOutstandingBalance is remaining PATIENT_AR. Unallocated credit ids are ledger event ids.

Query Parameters

patientId

string

required

External patient id (org patients.patientIdentifierSystem, or customer-patient-id by default)

Response

Balances fetched successfully

success

boolean

data

object

Show child attributes

cURL

curl --request GET \
  --url https://forecaster.cairhealth.com/api/patient-payments/balances

const options = {method: 'GET'};

fetch('https://forecaster.cairhealth.com/api/patient-payments/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://forecaster.cairhealth.com/api/patient-payments/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://forecaster.cairhealth.com/api/patient-payments/balances"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://forecaster.cairhealth.com/api/patient-payments/balances")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "patientId": "<string>",
    "patientFhirId": "<string>",
    "currentBalance": 123,
    "lastPayment": {
      "paymentAmount": 123,
      "paymentDate": "2023-11-07T05:31:56Z",
      "paymentMethod": "<string>",
      "paymentTraceId": "<string>"
    },
    "unallocatedCreditTotal": 123,
    "unallocatedCredits": [
      {}
    ],
    "manualCharges": [
      {}
    ],
    "claims": [
      {}
    ]
  }
}

Overview

API Authentication

Eligibility

Enrollments/Providers

Claims

EDI Transactions (Stedi-Compatible)

Claim AI Actions

Patient Chart Analysis

Patient Payments

Patients

Webhooks

AI Phone Calls

Overview

Authentication

Query Parameters

Example

Response

Query Parameters

Response

​Overview

​Authentication

​Query Parameters

​Example

​Response

Query Parameters

Response

Overview

Authentication

Query Parameters

Example

Response