Insurance Cash Reconciliation Agent Blueprint
Every morning, the cash team at a specialty insurer faces the same pile: money landed in the bank overnight, and someone has to work out which policies it pays. The wire amounts rarely match the bills. One transfer covers dozens of policies, explained only by an advice written as prose. An insured has paid late, or short, or twice. Some of the money matches nothing anyone can see.
The errors in that pile are quiet ones: cash applied to the wrong policy looks exactly like cash applied to the right one. So this open blueprint, the Insurance Cash Reconciliation Agent, takes the working-out as its job. The matching arithmetic is checked in code. A model is used only where judgment is needed: reading the unstructured paper, proposing where unexplained money belongs. And nothing posts itself: a named controller approves every posting, and a day counts as reconciled only when every cent of it is accounted for.
One honesty note before the machinery: Northgate Specialty Insurance, the carrier in the repository, is fictional, and every broker, policy, bank line and person in it is synthetic. The rates and thresholds are samples; it is a reference prototype. The architecture and the code are the deliverable, and both are public.
Why the cash never equals the bill
Most premium arrives through brokers, and brokers remit net: they deduct their contracted commission and send the rest. A wire for less than the billed premium is usually not a short payment. It is the correct payment, and recognising it means knowing the contract behind it, and which of its rates was in force the day the cash arrived. Rates change mid-book; the change reprices nothing backwards.
That history also exposes a particular failure shape. When a broker deducts at a rate that is clean and plausible but not the contracted one, the wire settles nothing exactly, and the pattern in the numbers says why. The blueprint raises it as its own exception and drafts the query note for the broker: what was expected, what arrived, the difference. Drafted, never sent: sending is a person's act.
Reading is the model's job. Matching is not.
An exact reference with an exact amount settles first in the fixed order of attempts. Then the netting-adjusted figure, premium minus the commission the contract allows. A reference whose amount differs is never force-fitted to the bill: the cash applies to what it genuinely covers, and the difference becomes a partial or overpaid exception with an aging clock. Duplicates are caught before any of it runs.
The model's work sits inside that order, in three places. It reads remittance advices, the emails and documents that explain a lump sum, and turns them into per-policy allocations, each required to cite the words in the document it came from. It proposes an allocation for a lump sum nobody explained, restricted to the paying broker's own open items, summing to the wire. And it drafts those broker query notes. Every reading is validated before it is worth anything: advice lines that do not sum to the wire are refused, allocations to cancelled policies are flagged rather than posted, and an unreadable document is held whole while the day carries on.
Installments get worked one by one, oldest first; a reference naming a specific installment settles that one first, and the record shows the choice. A free-text hint pointing elsewhere is information, not instruction: the cash applies oldest-first, and the difference is flagged.
Suspense is a place, not a bin
Cash that survives every attempt unexplained goes to suspense, carrying a reason code and the date it arrived. Auditors ask about this pile first, so it is treated as work in progress, never as a bin. Each item sits in an aging view, oldest first, owned by a named member of the team. Information often lands after the cash does, and a re-match pass works the open items against the books as they now stand; recoveries still arrive as proposals, in a pack, at the gate.
The hardest items have no payer to work from at all. For those, a resolution scan reads the whole book and builds candidates under a strict discipline: a candidate exists only when the arithmetic is exact, or when the wire's text names the policy, quoted verbatim. A model may rank them, and may add one only by quoting that text. Policies the evidence names but the cash cannot settle come back flagged, considered and unchoosable. The item stays open while all this stands proposed, because a hypothesis is not a claim on the cash. A controller picks one candidate, or none.
Two partial wires from the same payer can also settle one bill, when they price out exactly, each at the rate of its own day, so a pair can straddle a rate change. A pair that lands a cent short proves nothing, and neither does an exact sum across two different payers.
Some cash is never identified. After a governed age it can be proposed for a governed end: written off to income, or moved to an unclaimed-property review list, because it may be owed to someone the desk could not find. Either way it takes two approvers, and the assembler can be neither. Review-list money stays visible, with its full chain beside it.
A day counts only when it foots
The day's report is the control everything answers to: the bank total, split into what was applied, what sits in suspense, and what has not been worked yet. If they do not add up, to the cent, the report says so in words and refuses to call the day reconciled. On a book with more than one currency, the identity holds per currency first. Cash is never converted to hunt for a match, so a wire that arrives in the wrong currency waits in suspense in its own denomination, with its reason named. Conversions recorded for reporting use the rate in force on the day the cash arrived, and keep all three figures: the cash, the rate, the converted amount.
Money flows back out too. A policy cancelled mid-term earns a return premium, computed pro-rata in code and owed back to the insured, or to the broker who collected it. Cash that arrives later for that policy meets the amount owed before it meets anything else. Payments can also be taken back by the bank; a return un-applies the cash by replaying the original arithmetic exactly, and a foreign-currency return reverses at the rate recorded when the cash first arrived, even if the rate has since moved. Approved packs are never rewritten; they gain a flag, and the return stands as its own entry.
Month end gets the same control at a larger scale: the close pack rolls suspense from opening to closing, currency by currency, and foots or says that it has not. Each broker's own monthly statement is checked against the books line by line, and every disagreement is classified: agreed, commission differs, amount differs, missing on the books, missing on the statement. The model's proposals are graded too, by what the gate actually did with them, and each broker's paperwork is scored on the record.
What the checks prove, and what they don't
The blueprint is tested against planted cases built into its synthetic months: the pair of wires one cent short, the wire in the wrong currency quoting a bill's exact amount in the other one, the broker who applied next quarter's commission rate a month early. Passing those cases means the code still behaves as designed on the traps the builders thought of. That is a regression gate, not evidence about your book or your brokers.
The habit that gives the gate its value is unglamorous: when the desk meets a new failure shape, the case goes in first, and the behaviour changes second.
Honest limits
Everything in the repository is synthetic: Northgate, its brokers and its second currency are inventions, chosen to exercise the shapes a real desk meets. Rates, thresholds and waiting periods are samples; a deployment replaces them with the carrier's own contracts and policies first.
The built-in fallback reader handles only advices written in a tidy, predictable shape, and real remittance paper is rarely tidy. Reading free-form documents well is the connected model's work, and live verification against a real model is still pending; the blueprint would rather say that than grade its own homework. The boundary at the far end is deliberate too: the system never moves money and never writes to a general ledger. Its output is an approved posting file, an audit record, and reports that foot. A person still uploads the file.
Work with us
If your cash team starts its mornings with a pile of wires that do not match the bills, and a suspense balance nobody wants to explain to an auditor, start with Trida AI's intake: a few questions about your book and your brokers, then a conversation with the founders and engineers who would build it with you.
:
Get the Code on GitHub: https://github.com/tridaai/blueprint-insurance-cash-reconciliation