Get Started with Ledger Data

🚧

Please note that all ledger data below should only be accessed via the v20240412 version. Ledger data requires additional setup so please reach out to [email protected] before building on these endpoints.

Introduction

This guide walks you through how to use NexHealth's Ledger API to collect patient payments. It explains how to:

1. Find the amount owed
2. Collect information to create an itemized invoice
3. Insert payment transactions in the patient’s EHR ledger.

Step 1: Find the Amount Owed

Overview

The NexHealth API does not provide a direct method to retrieve an individual patient’s balance. However, you can:

• Retrieve the balance owed by a guarantor (fiscally responsible party).
• Calculate a patient’s balance by summing charges, payments, and adjustments.

Retrieve Guarantor Balance

Please note that a guarantor may be associated with multiple patients. Guarantor balance will reflect the total balance for all those patients.

Identify the Guarantor

• Use the view patient endpoint to find the guarantor_id associated with the patient. If the patient is their own guarantor, the patient_id and guarantor_id will be the same.
• Optionally, include the guarantor parameter to retrieve the guarantor’s contact details.

View Accounts Receivable

• Use the view guarantor accounts receivable endpoint and pass in the guarantor_id.
• The guarantor_portion field on the response represents the amount the practices believes a guarantor owes (the delta between guarantor_portion and total_balance is either covered by insurance or written off)

Calculate Patient Balance

• Sum Charges: Use the view charges endpoint to retrieve the list of charges for the patient.
• Calculate the patient amount. If you’re billing before insurance has paid:

patient_amount = charge.fee - charge.payment_estimate_total - charge.write_off_estimate_total

• If you’re billing after insurance has paid:

patient_amount = charge.fee - charge.write_off_total

• Sum Payments: Use the view payments endpoint and sum thepayment_amount.amountvalues.
• Sum Adjustments: Use the view adjustments endpoint and sum the adjustment_amount.amount values.
• Validate Calculations: Sum charges, payments, and adjustments to calculate the total balance.
  Compare this value to the guarantor_portion from the accounts receivable record. Discrepancies may indicate missing ledger items or data inconsistencies.

Step 2: Retrieve Charge Details for Itemized Invoices

To create itemized invoices or group charges by attributes such as patient, provider, or date:

Fetch Charge Details:

• For each charge from Step 1, use the view charge action to retrieve additional details such as patient name, provider, procedure information, and claim details.
• Get detailed procedure information.
  • If a charge is associated with a completed procedure, you can view the procedure by adding the query parameter include[]=procedures to the /charges query.
  • However, not all EHRs enforce or even allow this mapping. For more details per integration, please see the Supported Health Record Systems section on the charges documentation.

Step 3: Insert Payments in the EHR Ledger

Once a payment is collected, it must be recorded in the practice’s EHR ledger.

Steps to Record Payments

• Retrieve Payment Types
  • Use the view payment types action to fetch available payment types in the target EHR.
    Select the appropriate payment_type_id for your transaction.
• Create a Payment Transaction
  • Use the create payment transaction endpoint to record the payment. Include all available details in the payment_transaction object.
  • To associate payments with providers or charges, use the provider_splits and charge_splits fields. See the corresponding section in this document to learn how.
  • One payment transaction may result in multiple payment records in the target health record system. Therefore a NexHealth payment transaction may have a one to many relationship with the corresponding patient payment ledger line items in the target database. For this reason, NexHealth allows API users to pass in a transaction_id.
  • The payment_transactions.transaction_id entered will be stored as the resulting payments.transaction_id and may be used to match payments with the payment transaction that generated them.
  • If you want to subscribe to updates, use the create webhook subscription endpoint. Subscribing to the payment_transaction_insertion event will ensure you are notified when payment records are created in the target health record system. Please note that payment creation is asynchronous.