Documentation
AnselIQ documentation
AnselIQ ingests processor, bank and internal ledger files, matches their records with rules you define, and explains whatever doesn't tie out. This page introduces the ideas the rest of the documentation builds on.
The guides
How AnselIQ models money
AnselIQ records everything it ingests on a double-entry ledger. Instead of comparing two spreadsheets row by row, it posts both sides of a reconciliation into one shared account and then pairs off the entries that cancel each other out. Whatever is left over is the difference you need to explain.
Ledgers
A ledger groups the accounts for one flow of money, such as card settlement or payouts to merchants. Each ledger has its own accounts, its own reconciliations and a daily reporting cutoff hour.
Accounts
Every account in a ledger has one of three types:
- Primary
- One side of the reconciliation, usually the system you treat as the source of truth: your payment processor or internal ledger.
- Secondary
- The other side, usually what you check against: a bank account or a card network.
- Recon
- The account where the two sides meet, like a clearing or suspense account. Its balance is everything that hasn't yet been matched off, and its matching rule says how entries from the two sides pair up.
Movements
A movement is one ledger entry: an amount moved from one account to another. Each row AnselIQ reads from a file becomes one movement, and the row's fields (references, dates, account numbers) are stored on it as properties, which the matching rules compare.
File feeds and movement specs
A file feed says where files come from (an S3 folder) and how to read them (CSV, BAI2, JSON lines or fixed width). A movement spec connects a feed to a ledger: it links a Recon account to a Primary or Secondary account, so that every row from the feed posts a movement between those two accounts. One feed can serve several movement specs, for example a BAI2 file that covers several bank accounts, with a routing filter deciding which rows belong to which.
Reconciliation rules
A Recon account's reconciliation rule says which movements belong together: which movement spec is each side, whether they pair one-to-one or one-to-many, and which fields have to agree. When movements match, AnselIQ groups them into a reconciliation and records exactly which values they matched on.
A worked example
A marketplace receives card payouts from its payment processor, which arrive in its bank account a day or two later. It wants to know that every payout landed, and to explain any that didn't land in full.
-
Two file feeds: the processor's daily payout report (CSV with
payout_id,amount,payout_date) and the bank's BAI2 statement. - A ledger, Card payouts, with three accounts: Processor (Primary), Bank (Secondary) and Payout clearing (Recon).
- Two movement specs: processor payouts post between Processor and Payout clearing; bank deposits post between Bank and Payout clearing. The two sides land in the clearing account with opposite signs.
-
A one-to-one rule on the clearing account: the processor's
payout_idequals the bank'sbank_reference_number.
When both files have been ingested, reconciliation pairs each payout with its deposit. A pair whose amounts net to zero is Final. A pair that matched on the reference but is $31.20 short, because the bank deducted a fee, is Mismatched, and AnselIQ raises an exception for it showing the two totals, the difference and the matched reference. A payout with no deposit yet stays unreconciled on the clearing account until its deposit arrives.
Reconciliation statuses
| Status | What it means |
|---|---|
| Final | The movements net to zero. Nothing left to do. |
| In progress | A one-to-many group that doesn't balance yet but may still be completed: more of the "many" side can arrive in a later file. It becomes Mismatched once it's older than the rule's aging limit. |
| Mismatched | Matched on the rule's fields, but the amounts don't net to zero and nothing more is expected. Always has an open AmountMismatch exception. Resolved by writing off the difference, unmatching, or (one-to-many only) a late movement that closes the gap. |
| Voided | Unmatched. Its movements went back to the unreconciled pool to be matched again. |
| Reversed | A system record pairing a movement with the correcting entry that reversed it. Both stay out of matching for good, and it can't be changed. |
Explaining a balance
Every Recon account's balance breaks down exactly into three parts:
Cash balance = Unreconciled + In progress + Mismatched
Final reconciliations always net to zero, so whatever is on the account is either waiting for a match, waiting for the rest of a group, or matched but wrong. The ledger's Overview tab shows each figure, and each one opens the movements or reconciliations behind it.
Exceptions
An exception is a problem someone has to look at. AnselIQ raises some automatically and people can raise others on a movement. Each has a status (New, Investigating, Escalated, Resolved), an optional assignee and a discussion thread.
| Category | Raised on | Raised by | Closes |
|---|---|---|---|
| AmountMismatch | Reconciliation | AnselIQ, when a reconciliation becomes Mismatched | Automatically, when it's written off, unmatched or balanced |
| FileMissing | File feed | AnselIQ, when a feed's expected file is overdue | Automatically, when the file arrives |
| UnroutedRecord | File feed | AnselIQ, when file rows match no movement spec | By a person, once a spec covers them |
| ExcessiveParseErrors | File feed | AnselIQ, when ingestion stops because too many rows couldn't be read | By a person |
| MissingCounterpart, Duplicate, TimingDifference, DataQuality | Movement | A person | By a person |
The ones AnselIQ closes automatically can't be resolved by hand: marking an AmountMismatch resolved would leave the difference on the books with no one looking at it. Fix the underlying problem instead, and the exception closes itself.
Corrections, never edits
Nothing that reaches the ledger is edited or deleted. A write-off posts an adjustment movement. Reversing a write-off posts a correcting entry. A file ingested with the wrong configuration is reversed movement by movement, voiding whatever it was matched into. The originals stay in place, so the ledger always shows what happened, when, and why, and the Events page lists every ingestion, match, write-off and exception change.
Glossary
- Account
- A balance within a ledger: Primary, Secondary or Recon.
- Aging limit
- How many days an in-progress one-to-many group may wait for the rest of its movements before it's marked Mismatched.
- Exception
- A problem raised for someone to resolve, with a status, assignee and thread.
- File feed
- Where a family of files arrives (an S3 folder) and how to parse it.
- File inventory
- Every file AnselIQ has found on a feed, with its processing status.
- Ledger
- A group of accounts for one flow of money.
- Manual match
- A reconciliation a person formed by selecting movements by hand.
- Match suggestion
- A match proposed by AnselIQ's AI for movements the rule left unmatched, for a person to accept or reject.
- Movement
- One ledger entry: an amount moved between two accounts, with the properties of the file row it came from.
- Movement spec
- The link between a Recon account and another account that a file feed's rows post to.
- Reconciliation
- A group of movements matched together, with a status and a record of why they matched.
- Reconciliation rule
- How a Recon account's movements are matched: the two sides, the relationship, and the fields that must agree. Called a recon spec in the API.
- Routing filter
- On a movement spec, a field and value that pick out the rows of a shared feed that belong to it.
- Write-off
- Closing a mismatched reconciliation's difference with an adjustment movement and a reason.