Introduction

This guide describes the general methodology needed to build an efficient patient invocing system using the Patient AR API. Compared to previous, more generalized API solutions, this API is purpose-built for patient invoicing, trimming excess information, providing higher throughput, and delivering data as close to real-time as possible.

Before diving into integration, there are a couple of key concepts to understand and keep in mind.

Patient AR Inventory

The Patient AR Inventory represents a roster of all claims that have ever resulted in a patient balance, and crucially their current invoiceable status. Anytime that an event might affect the patient balance of a claim, such as a write-off or payer readjudication, it’s corresponding entry in the Patient AR Inventory is updated with a new timestamp.

Patient Balance and A/R

While patient financial transactions can occur throughout the claim lifecycle, Candid only considers patient balance to be active once all upstream adjudication has been completed. At that moment, the patient balance at that point is considered patient A/R, and the aging of that balance begins.

Patient A/R Lifecycle and Invoicing

Not all patient balance is immediately invoiceable. This can be due to both business-specific rules and Candid’s own A/R automation. Invoicing should only occur during a specific portion of the patient A/R lifecycle, which is denoted via the AR Status field on the Patient AR Inventory. At present, the only AR Status that is considered invoiceable is INVOICEABLE.

Overview of AR Statuses

• INVOICEABLE: All upstream adjudication by payers has completed, and Candid has completed its own A/R automation. All remaining claim balance is considered invoiceable. Note that in some cases, particularly around refunds, a claim may be in this state with a zero or credit balance.
• NON-INVOICEABLE: Patient balance is indeterminate, whether due to pending ajdudication, or because upstream automations are still in progress by Candid. Claims in this state should not be invoiced, any open invoices should be held or closed.

Integration Guide

Overview

The general integration pattern is to poll the Inventory API for records that have changed since the last request, and idempotently sync the AR status and itemization with your system. We refer to this style of polling as a delta-sync, since it only retrieves records that have changed since the last request, providing an efficient way to keep your system in sync with Candid’s Patient AR Inventory.

Inventory Delta-Sync Tips

1. Page Token: The Inventory API uses a page token rather than offset to support paginated requests. On the first request, you should not pass a page token, but on subsequent requests, you should pass the page token from the previous request to retrieve the next page of results. Between requests, you must store page token in persistent storage, such as a database or cache, to ensure that you can resume from the last point in case of an interruption.
2. Reseting the page token: If you ever need to playback from a specific timestamp, you can reset the page token to null and pass a since parameter with the desired timestamp. This will retrieve all records that have changed since that timestamp, allowing you to reprocess your inventory from that point.
3. Latency: Data stored in the Inventory API is updated in real-time, but in order to provide a consistent ordering of the data, there is a small delay before the data is available for retrieval. We monitor this delay to ensure that it is minimal, not to exceed a 30m SLA.
4. Keeping up to date: In order to maintain the best patient experience, we recommend maintaining a polling cadence that ensures you’re no later than 24 hours behind the latest data. This will ensure that you are able to invoice patients in a timely manner and communicate any changes to their balance as soon as possible.

Itemization

We recognize that billing patients goes far beyond then just sending a balance due, which is why we provide the Invoice Itemization API to support detailed patient billing. The itemization provides a breakdown of the patient balance, including the original amount billed to insurance, any adjustments made, and the current balance due. This allows you to provide patients with a clear understanding of their balance and the services they are being billed for. This data is always derived from the latest patient balance, so you can be confident that the itemization is always up-to-date.

• From a performance perspective, we recommend only retrieving itemization for claims that are currently invoiceable, as this will reduce the number of requests made to the Itemization API and improve overall delta-sync throughput.

Idempotency

Both the contents of the Inventory and Itemization APIs always reflect the full and current state of the claim, and so it is the caller’s responsibility to ensure that they are idempotent in their processing. For example, if you receive an Inventory update for an invoiceable claim for which you already have opened an invoice, you must use the Itemization API to determine whether the itemization has changed since the last time you processed it. If it has, you should update your invoice with the new itemization data. If it hasn’t, you can skip processing that claim.

Guarantor Billing

Candid’s financial system only models all patient responsibility under a single financial account identified by the patient, even if payment will ultimately be made by a separate guarantor. If you bill to guarantors, you should use the Encounter API to determine the guarantor for each claim and use that information to correctly route the invoice to the appropriate party. Any payments made by the guarantor should still be posted to Candid under the patient identifier.

Custom Billing Logic

Until a claim reaches an AR Status of INVOICEABLE, automation and determination of billable amounts should be assumed to be under the sole control of the Candid system. Thus, we recommend against implementing any custom logic that would either affect the billable status or balance of a claim until it reaches that status. Once a claim is invoiceable, you are free to implement any custom logic you wish to determine how and when to bill the patient.

Candid is actively investing in platform improvements to support more complex billing scenarios. Before implementing custom logic, is is always best to reach out to your Candid representative to see if there are any existing solutions that can meet your needs and avoid unnecessary complexity in your integration.