The Uncoded Query Build Standard

1. What this standard covers

The bank lines in a client’s books that cannot be coded without asking the client, and the round trip that clears them: the question, the answer, a suggested coding, a person’s approval, and the write. It is the same job for a bookkeeping practice with a hundred client files and for a business that does its own books and has to ask the owner.

An uncoded line is one of two things, and the ledgers treat them differently. Either someone has already reconciled it to a suspense or “uncategorised” account to park it, so there is a transaction in the ledger whose coding can be changed. Or it is still sitting in the bank feed, not reconciled at all, so there is nothing to change yet. The build asks about both. It writes the coding only for the first kind. The second kind gets its question, its suggestion and its approval, and then a person reconciles it, because reconciling is a person’s job under this standard.

What is out of scope. Money in that pays invoices is the Remittance Split standard. Comparing two systems that should agree is the Two Records standard. A receipt or bill that arrives by email and belongs against a record is the Document Filing standard. This standard starts where those cannot help: a line only the client can explain. Tax advice is out of scope entirely, to the client and to the approver.

What cannot meet it, and what can. All three cloud ledgers can meet it for lines parked on a suspense or uncategorised account: each lets an app read those transactions and change their coding through its API. None of the three lets an ordinary app reconcile a bank feed line, and Xero and QuickBooks Online do not hand an app the feed lines still waiting to be reconciled at all, so a practice that leaves unknown lines in the feed gets the question lists but keeps the reconciling. MYOB Business does list its feed lines through the API, with an “Uncoded” status, so the questions can come straight from the feed there. A desktop ledger with no cloud API cannot meet the standard, because there is nothing a build can write to. Section 8 has the detail for each.

Is there a ready-made version? Not yet. The build connects straight to each client’s ledger through the ledger’s own sign-in, and no product of ours makes that write. A free Google Sheet version runs the lists, reminders, suggestions and approvals and leaves the ledger entry to a person. The automated write is yours to build, or a scoped build with us.

2. Chasing the same client about the same bank lines every month?

Think of it as one envelope per client per month, not a drip of emails. On the day you set, the build reads each client’s ledger for the lines still uncoded and sends that client one list with all of them in it. A line coded by hand since last month is not on it. A line that lands after the list has gone waits for next month’s envelope rather than starting a second one.

Every line is one plain question, built the same way: the amount, who it went to or came from exactly as the bank printed it, the date, and “what was it for?”

• $412.50 to BUNNINGS 5678 MORAYFIELD on 3 Oct: what was it for?
• $1,200.00 from J SMITH on 5 Oct: what was it for?

The list carries a link where the client answers each line on its own, in a few words, on a phone if they like. It goes by email, and by an SMS link to the same page where the client has a mobile on file. What the client never sees: an account code, a tax code, the word suspense, or anything about what is deductible or claimable. The client is asked what happened. What that means for tax is your call, not the message’s.

Reminders follow your schedule: every so many days, up to a number you set, and only for the lines still unanswered. A line the client has answered leaves every reminder, and it stays out of next month’s list too, even while its coding waits for approval and the ledger still shows it as uncoded. After the last reminder, the client’s open lines go to a person on your team. Whether to ring the client is theirs to decide, and the build places no call. Office Voice, which places governed calls for other standards, dials only on a lawful reason such as an invoice the person owes or a callback they asked for, and a question about a bank line is none of them. So the call stays with your team.

3. From “tiles for the Smith St job” to an account and tax code

The client’s answer is kept word for word, with who answered and when, before anything is done with it. Then the build suggests a coding: an account and a tax code, both from that client’s own chart of accounts and nothing else.

The client’s own history comes first. If this client has coded the same payee before, that coding is the suggestion, with the date it was last used, and the answer is shown beside it so the approver can see whether this time is different. Where there is no history, the answer is matched to the client’s own accounts by name, and the tax code is the one that client’s chart already sets on that account. The suggestion carries its reason in plain words: the answer, and the history it came from. It never carries advice.

When the answer fits no account in the chart (“bought some crypto” in a file with no account for it), nothing is suggested. The line goes to a person with the answer. The build never creates an account, never borrows one from another client of the practice whose chart happens to have it, and never makes up a tax code. Those closed reasons for handing a line to a person are:

4. The records it keeps, in the shape your developer needs

Seven objects, keyed on the ledger's own line id. The QuestionList is unique on client and cycle; the Write is unique on its key, which is the line and the approval.

Client
  - client_id, name, email, mobile (optional)
  - ledger (xero | myob_business | quickbooks_online)
  - suspense_account                # where this file parks unknown lines

UncodedLine                       # read from the ledger each run, never typed
  - line_id                         # the ledger's transaction or statement line id
  - client_id, date, amount, payee  # payee exactly as the bank printed it
  - source (suspense | statement)   # statement lines are reconciled by a person
  - status (asked | answered | proposed | approved |
            written | handed_off)

QuestionList                      # unique on (client_id, cycle): one a month
  - client_id, cycle (2026-11)
  - lines [{ line_id, question }]
  - answer_link, channel (email | sms)
  - sent_at, reminders_sent, last_message_at

Answer
  - line_id, client_id
  - text                            # word for word
  - answered_by, answered_at

Proposal                          # a suggestion, never a write
  - line_id, account, tax_code      # both from this client's chart
  - why                             # the answer and the history; no advice

Approval
  - approval_id, line_id
  - account, tax_code               # what the person approved
  - approved_by, approved_at        # a person, never the build

Write                             # unique on write_key
  - write_key                       # line_id + approval_id, sent to the ledger
  - line_id, result (written | readback_mismatch |
                     write_failed | reconcile_by_person)
  - ledger_account, ledger_tax_code # read back after the write
  - written_at

A Write with no Approval behind it, a second QuestionList for the same client and cycle, or a Proposal whose account is not in the client's chart is the defect this standard exists to make unrepresentable.

5. The checks, in order

The order is the claim. The ledger is read before anyone is asked, the client is asked before anything is suggested, the suggestion comes from the client’s own chart, and nothing is written until a person approves it.

1. Only lines the ledger still shows as uncoded are asked about. The lines come from the client's ledger at the time of the run: transactions parked on a suspense or uncategorised account, and bank lines not yet reconciled. A line coded by hand since the last run is not asked about.
2. One question list per client per cycle, with every open line in it. Each client gets one list a cycle, grouping all of that client's uncoded lines. A second run in the same cycle sends no second list, and a line that lands mid-cycle waits for the next list rather than starting another one.
3. Each line is one plain question with a place to answer it. A line is put to the client as the amount, who it went to or came from as the statement printed it, and the date, then "what was it for?" Every list carries a link where each line can be answered on its own.
4. No tax advice and no bookkeeping words reach the client. Nothing sent to a client says whether something is deductible or claimable, names a tax code or an account code, or mentions suspense or reconciling. The client is asked what a payment was for; what that means for tax is the practice's call.
5. A line already answered is never asked about again. Once the client has answered a line, it leaves every reminder, and next cycle's list does not carry it even while the coding waits for approval and the ledger still shows it as uncoded.
6. Reminders on the schedule the practice set, then a person. Reminders go only for unanswered lines, no sooner than the interval the practice set and no more than the number it set. After the last one goes unanswered, the client's open lines go to a person, who decides whether to ring. The build places no call.
7. The client's answer is kept word for word, with who and when. Each answer is recorded against its line exactly as the client typed it, with who answered and when, before anything is proposed from it.
8. The proposed coding comes from the client's own chart, and their own history first. Every proposal is an account and a tax code from this client's chart. Where this client has coded the same payee before, that coding is proposed; otherwise the answer is matched to the client's own accounts. The chart is read in the run before any proposal.
9. No account or tax code the client's chart lacks is ever proposed or written. When an answer fits no account in the client's chart, the line goes to a person as no_account_fits with the answer, and nothing is proposed. The build never creates an account, never borrows one from another client and never makes up a tax code.
10. Nothing is written until a named person approves that exact coding. A proposal is not a write. The build writes a coding only when a person has approved it, by name, for that line, and it writes exactly the account and tax code they approved.
11. The build never reconciles a bank line; a person does. The build changes the coding of a transaction already in the ledger: by editing it, or by a journal off the suspense account where the ledger will not take the edit. A bank line the ledger has not reconciled gets its question, its proposal and its approval, and then goes to a person with the approved coding to reconcile. The build never matches, creates a transaction for, or reconciles a bank line.
12. An approved coding is written once, however often the build runs. Every write carries one key for that line and that approval, so a retry after a timeout cannot write twice. A later run reads the ledger first and writes nothing for a line that already holds its approved coding.
13. Every write is read back, and a mismatch goes to a person. After a write, the build reads the line back from the ledger and records what the ledger now holds against the approval. If it differs from what was approved, the line goes to a person as readback_mismatch and is not written again.
14. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
15. The pass test passes. On a real client file, an approved coding is written into the ledger exactly once and reads back as approved, and a proposed coding nobody approved is never written.

6. Nothing in the books until someone signs off, and then only once

A suggestion is not a write. Each one lands in front of the approver (a bookkeeper or the practice’s senior) with the client’s answer beside it. They approve it as it is, or change the account or tax code and approve that. The build writes exactly what they approved, under their name, and nothing for a line nobody approved.

Once means once per approval. Every write carries one key made from the line and the approval, and the ledger is asked to treat a second write with the same key as the first. That matters on the day the connection drops after the ledger saved the change but before it said so: the build retries with the same key and gets the first answer back, rather than writing again. A later run reads the ledger first, and a line that already holds its approved coding is left alone.

Every write is read back. The build asks the ledger what the line holds now and records that against the approval. If it differs (a locked period, a tax code the ledger rewrote, an edit the ledger would not take) the line goes to a person as a mismatch and is not written again.

And the build never reconciles. It changes the coding of a transaction already in the ledger, by editing it or, where the ledger will not take the edit, by a journal that moves it off the suspense account. A bank line still waiting in the feed goes to a person with its approved coding, and they reconcile it. The build has no way to match, create or reconcile a bank line.

7. What stays with a person

• ✓Approving every coding, and changing one before approving it.
• ✓Reconciling a bank line still in the feed, with the coding that was approved for it.
• ✓Every line whose answer fits no account in the client's chart, and deciding whether that client needs a new account.
• ✓Following up a client who has not answered after the last reminder, by phone or otherwise. The build places no call.
• ✓Every tax question the answers raise, and anything said to the client about tax.
• ✓Every line the ledger did not hold as approved when it was read back.

8. Xero, MYOB or QuickBooks: what each lets a build do

Think of the ledger access as a pencil with no rubber: it can write a coding a person approved, and nothing else. The build reads three things (the uncoded lines, the client’s chart and tax codes, and how the client coded before) and writes one. Connect each client file through the ledger’s own app sign-in, never with a staff login, and to stop it, disconnect the app in the ledger’s settings.

Before you build, prove the write on each ledger’s demo or sandbox company with a line parked on suspense: that the edit (or the journal) is accepted, that the tax code reads back as written, and what happens to a line in a locked period. The answers differ by ledger and change over time, which is why the read back is a check rather than an assumption.

1. Your developer builds against the stub until the checks in section 5 pass.
2. Connect the build to a demo company and run the pass test below.
3. Connect one real client file, and check the build calls nothing beyond the three reads and the one write.
4. Let the first month of approvals be read back by a person before anyone stops checking.

Why not give a bot the practice’s login? A login can do everything a person can: reconcile the line, create an account, code a line nobody approved. Those are the things this standard keeps with a person.

Where the workflow lives is your choice, held to the same checks:

• A Google Sheet. The lines pasted in or exported, one list per client sent by email, answers recorded against each line, suggestions from the client’s chart and an approve column, with the ledger entry made by a person.
• Microsoft 365. SharePoint lists for the lines, lists, answers and approvals, approvals in Teams, and one keyed write per approval. The Microsoft 365 plan lays out the lists and flows.
• A long-lived bot. A routine that runs on your list day, sends the lists, takes the answers, and posts suggestions to the approver in Teams, Slack or email.

How to run any standard each of these ways is in run a standard anywhere.

9. What your developer builds, and the step that needs care

One step not to hand-roll: the write itself, into a client ledger you do not own, only for a coding a named person approved, under one key per approval, and read back. The lists, reminders, answers, suggestions and hand-offs a coding agent builds against the stub.

provider:
  stub:       local.mock_client_ledgers
  production: none                       # scoped build, not a product

the stub                             # local.mock_client_ledgers
  - two client files, each with its own chart and tax codes
  - lines parked on suspense, and one bank line not reconciled
  - a ledger that keeps an idempotency key and can lose an answer
  - no reconcile, no new account, no call

the hard step: the write, in production
  - no hosted product writes a coding. The build connects
    straight to each client's ledger through its own sign-in,
    yours to build or a scoped build with us
  - Xero: edit the transaction where the API takes it, else a
    manual journal off suspense; send an Idempotency-Key
  - MYOB Business: update Spend or Receive Money with the
    RowVersion it was read with
  - QuickBooks Online: sparse update with a requestid
  - read the line back after every write

stays local                          # yours, and the standard
  - the lists, reminders, answers and suggestions
  - every approval, which is a person's

cannot meet the standard
  - a desktop ledger with no cloud API
  - a write path that cannot be read back

A vendor selling client query automation is usually selling the email. Ask them three things: what stops their build writing a coding nobody approved, what happens when the connection drops after the ledger saved the change, and whether it ever tells your client what is deductible.

10. A checklist to hold any build or supplier to

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. Only lines the ledger still shows as uncoded are asked about. The lines come from the client's ledger at the time of the run: transactions parked on a suspense or uncategorised account, and bank lines not yet reconciled. A line coded by hand since the last run is not asked about.
• ✓2. One question list per client per cycle, with every open line in it. Each client gets one list a cycle, grouping all of that client's uncoded lines. A second run in the same cycle sends no second list, and a line that lands mid-cycle waits for the next list rather than starting another one.
• ✓3. Each line is one plain question with a place to answer it. A line is put to the client as the amount, who it went to or came from as the statement printed it, and the date, then "what was it for?" Every list carries a link where each line can be answered on its own.
• ✓4. No tax advice and no bookkeeping words reach the client. Nothing sent to a client says whether something is deductible or claimable, names a tax code or an account code, or mentions suspense or reconciling. The client is asked what a payment was for; what that means for tax is the practice's call.
• ✓5. A line already answered is never asked about again. Once the client has answered a line, it leaves every reminder, and next cycle's list does not carry it even while the coding waits for approval and the ledger still shows it as uncoded.
• ✓6. Reminders on the schedule the practice set, then a person. Reminders go only for unanswered lines, no sooner than the interval the practice set and no more than the number it set. After the last one goes unanswered, the client's open lines go to a person, who decides whether to ring. The build places no call.
• ✓7. The client's answer is kept word for word, with who and when. Each answer is recorded against its line exactly as the client typed it, with who answered and when, before anything is proposed from it.
• ✓8. The proposed coding comes from the client's own chart, and their own history first. Every proposal is an account and a tax code from this client's chart. Where this client has coded the same payee before, that coding is proposed; otherwise the answer is matched to the client's own accounts. The chart is read in the run before any proposal.
• ✓9. No account or tax code the client's chart lacks is ever proposed or written. When an answer fits no account in the client's chart, the line goes to a person as no_account_fits with the answer, and nothing is proposed. The build never creates an account, never borrows one from another client and never makes up a tax code.
• ✓10. Nothing is written until a named person approves that exact coding. A proposal is not a write. The build writes a coding only when a person has approved it, by name, for that line, and it writes exactly the account and tax code they approved.
• ✓11. The build never reconciles a bank line; a person does. The build changes the coding of a transaction already in the ledger: by editing it, or by a journal off the suspense account where the ledger will not take the edit. A bank line the ledger has not reconciled gets its question, its proposal and its approval, and then goes to a person with the approved coding to reconcile. The build never matches, creates a transaction for, or reconciles a bank line.
• ✓12. An approved coding is written once, however often the build runs. Every write carries one key for that line and that approval, so a retry after a timeout cannot write twice. A later run reads the ledger first and writes nothing for a line that already holds its approved coding.
• ✓13. Every write is read back, and a mismatch goes to a person. After a write, the build reads the line back from the ledger and records what the ledger now holds against the approval. If it differs from what was approved, the line goes to a person as readback_mismatch and is not written again.
• ✓14. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓15. The pass test passes. On a real client file, an approved coding is written into the ledger exactly once and reads back as approved, and a proposed coding nobody approved is never written.

Facts that can change, and when we checked them