The book file

The format of a HomeBooks book file, version 1

Your books are yours. An owner of a book can download the whole book at any time, under Settings, Book file: every setting and every record ever entered, in one file that a person can read and a program can read. The same file restores the book, here or on any other HomeBooks. This page describes the file so that you, or anyone you hand it to, can use it without us.

What is in the file

The download is a ZIP file named for the book and the day, ending .homebooks.zip. It holds:

book.json: everything, described below. A restore reads only this.
README.txt: what the file is, and how many rows each section holds.
Five CSV copies for a spreadsheet, with names in place of ids: accounts.csv, journal.csv, contacts.csv, invoices.csv, payments.csv.

book.json

One JSON document in UTF-8: a header, then sections. The header's fields come before sections.

Field	What it holds
`format`	Always `HomeBooks book file`.
`format_version`	1. See Versions below.
`migration`	The version of the HomeBooks database the file was made from. The sections and fields of a file are those of that version.
`made_at`	When the file was made (UTC).
`made_by`	The id, in People, of the person who made it; null for a file HomeBooks made by itself.
`book`	The book's `id` and `name`.
`quickbooks_records`	false when the person left out the records and reports as QuickBooks sent them (the sections QuickBooks records and QuickBooks reports).
`left_out`	The secrets that are not in the file, each as `section.field`.
`counts`	How many rows each section holds, by the section's name.
`sections`	A list. Each section has a `name`, a `title` in plain words, and `rows`: a list of objects, one per record, each on a line of its own.

Values

Every row carries every field of its section; a field with no value is null.
An amount, and any other number with decimals, is text, exactly as stored: "1234.50". It is never a JSON number, so nothing is rounded on the way.
A whole number is a JSON number; true and false are true and false.
A date is "2026-03-15". A time is ISO 8601 in UTC: "2026-03-15T14:05:09.123456+00:00".
An id is a UUID as text. A row of one section names a row of another by its id.
A list is a JSON list. A field marked JSON holds a JSON value as it was stored; what a bank or QuickBooks sent is kept as they sent it.

What is not in the file

No password, no sign-in detail, and no key or token of a connection to a bank or to QuickBooks. The file still says that each connection existed and what it was connected to; the fields left out are listed in left_out and marked below. A person's own settings (their password, two-factor, email sending) belong to the person, not to a book, and are not in a book's file.

Restoring a file

In HomeBooks, an owner restores a file under Settings, Book file; the platform administrator can restore one for a person who has no book. A restore always makes a new book and replaces nothing. Before anything is saved the file is checked: each section holds the rows the header counts, every entry balances, every row a row names is in the file, and every value fits the books' own rules. A file that fails a check is refused whole, with the reason.

In the new book every record has a new id. The person who restores it is its owner and its only member. The members, the invitations and the connections the file lists are shown for the owner to invite and connect again; the sections marked "listed, not restored" below are not carried. The people the records name are kept as names: nobody gets access by being named in a file.

Versions

format_version changes only when what this page calls the file changes: the header, the shape of a section, or how a value is written. It does not change when HomeBooks gains a table or a field: a newer file then simply has a section or a field more, and migration says which version of the database it came from.

Every file ever made stays restorable. An older file is loaded as the version it was made at and brought forward by the same steps that brought HomeBooks itself forward; there is no converter to fall out of date. A file made by a newer HomeBooks than the one restoring it is refused.

The CSV copies

Comma-separated, UTF-8, with a heading row. Amounts and dates are written as in book.json. A text that begins with =, +, - or @ is written with an apostrophe before it, so that a spreadsheet does not run it as a formula; book.json holds it as it is.

File	Columns
`accounts.csv`	Number, Name, Type, Kind, Sub-account of, Default use, Schedule C line, Active
`journal.csv`	Entry, Date, Status, Reference, Payee, Memo, Line, Account number, Account, Debit, Credit, Use, Tag, Line memo, Line contact, Source, Reverses entry, Entered by, Entered at
`contacts.csv`	Name, Customer, Vendor, Job of, Active, Billing address, Shipping address, Terms days, Tax exempt, Phones, Emails
`invoices.csv`	Kind, Number, Customer, Date, Due date, Status, Line, Description, Quantity, Unit price, Amount, Taxable, Subtotal, Tax, Total, Memo
`payments.csv`	Date, Customer, Amount, Method, Reference, Deposit account, Memo, Applied to

Sections

In the order they stand in the file. This is the current version; an older file may lack a section or a field listed here.

Book

book. The book itself: one row. Every other section holds rows of this book.

Field	Type	What it holds
`book_id`	id	The id of the book. Every row of every other section carries it.
`name`	text
`fiscal_year_start_month`	whole number	The month the fiscal year starts in, 1 (January) to 12. Year-end closes and reports read it.
`locked_through`	date, or null	The locked period: no entry may be dated on or before this date. Empty when nothing is locked.
`time_zone`	text	The time zone of the book as an IANA name (America/Chicago). Today in the book is read in it.
`created_at`	time
`practice_of`	id, or null	On a practice copy, the book (Book) it was copied from. Empty on an ordinary book.
`book_type`	text	home, business (shown as Small business) or both. It decides only what the screens show and how a new book starts.
`book_type_chosen`	true or false	Whether a person has picked the book type. False on a new book until its setup or its QuickBooks connection asks.
`backup_schedule`	text	How often a backup copy of the book is made by schedule: daily, weekly or off.

Chart of accounts

account. One row per account. Entry lines, budgets, rules and documents point here.

Field	Type	What it holds
`id`	id
`book_id`	id
`type`	text	asset, liability, equity, income or expense.
`parent_id`	id, or null	The account (Chart of accounts) this one is a sub-account of. Empty for a top-level account.
`number`	text, or null	The account number as shown on the chart (No.). Free text, optional, unique in the book.
`name`	text
`active`	true or false
`created_at`	time
`kind`	text, or null	Optional. Asset: bank, cash, fixed_asset, accumulated_depreciation. Liability: credit_card, line_of_credit, loan. Equity: opening_balance_equity. Income: other_income. Expense: cost_of_goods_sold, other_expense.
`schedule_c`	text, or null	The line of IRS Schedule C (Form 1040) the account is reported on, such as 8 or 27b. Empty when it has none.
`default_use`	text, or null	personal or business: the use a line on this income or expense account takes when none is given. Empty: the nearest parent that has one, else personal.

Number counters

book_counter. One row per number sequence of the book. Entries and sales documents take their numbers from these.

Field	Type	What it holds
`book_id`	id
`name`	text	Which sequence: txn (entries), invoice, receipt (sales receipts) or credit_memo.
`last_value`	whole number	The last number given out in that sequence.

Members

book_member. One row per person who may open the book, with their role. Listed, not restored.

Field	Type	What it holds
`book_id`	id
`user_id`	id	The person who is a member.
`role`	text	owner, editor, viewer or accountant.
`created_at`	time

People

book_person. One row per person the records of the book name: who entered, changed or sent what. A file lists everyone named; no password or sign-in detail is in it.

Field	Type	What it holds
`book_id`	id
`id`	id	What the other sections name the person by, in fields such as created_by, user_id and sent_by.
`display_name`	text
`email`	text

Bank connections

feed_connection. One row per connection of the book to a bank-data provider. A disconnected connection keeps its row. Its accounts are in Bank feed accounts. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`provider`	text	simplefin or plaid.
`name`	text	The name shown for the connection: the name of the bank for Plaid, of the provider for SimpleFIN.
`secret_enc`	text	A secret: not in the file.
`connected_by`	id
`connected_at`	time
`disconnected_by`	id, or null
`disconnected_at`	time, or null	When an owner disconnected it. Empty while the connection is open.
`last_fetch_at`	time, or null	When the provider was last asked.
`last_ok_at`	time, or null	When the provider last answered without a failure.
`scheduled_at`	time, or null	When the scheduled (daily) fetch last ran for this connection.
`error_status`	whole number, or null	The status code of the last failure, in the style of an HTTP status (0: no answer). Empty after a fetch that worked.
`error`	text, or null	The message of the last failure, for the screen of the owner. Empty after a fetch that worked.
`problems`	list of text	A list of the messages the provider itself sent with its last answer.
`listed`	list of text	A list of the provider account ids (external_id in Bank feed accounts) its last answer listed.
`requests_day`	date, or null	The day the requests count is for.
`requests`	whole number	How many requests were made to the provider on requests_day, counted against its daily limit.
`external_id`	text, or null	The Plaid item id of the connection. Empty for SimpleFIN.
`institution_id`	text, or null	The Plaid id of the bank.
`environment`	text, or null	The Plaid environment the connection was made in: sandbox or production.
`cursor_enc`	text	A secret: not in the file.
`sign_in`	text, or null	Why the bank wants a new sign-in, as a Plaid code. Empty when none is needed.
`sign_in_until`	text, or null	What clears that request: sync (the next sync that works) or window (the person signing in again through Plaid).
`ends_at`	time, or null	The date Plaid announced the bank sign-in will end.
`consent_expires`	time, or null	When the consent given at the bank to share data ends, as Plaid reports it.
`new_accounts`	true or false	True when Plaid reported new accounts at the bank that can be added.
`last_webhook_at`	time, or null	When Plaid last sent a notice (webhook) about this connection.
`webhook`	text, or null	The address Plaid posts its notices to.

Plaid keys

feed_plaid_keys. The Plaid keys of the book itself: at most one row. The secret is left out of the file. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`client_id`	text	The Plaid client id of the Plaid team the household has.
`secret_enc`	text	A secret: not in the file.
`environment`	text	sandbox or production.
`plan`	text	trial or paid: the Plaid plan the owner says the team is on.
`saved_by`	id
`saved_at`	time

Invitations

invitation. One row per invitation to join the book, sent to an email address. The secret token of the invitation is left out of the file. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`book_name`	text	The name of the book when the invitation was made.
`email`	text	The address the invitation was sent to. Only that person can accept it.
`role`	text	The role the person joins with: owner, editor, viewer or accountant.
`token_hash`	text	A secret: not in the file.
`invited_by`	id
`created_at`	time
`expires_at`	time
`accepted_at`	time, or null	When it was accepted. Empty while it is open.
`cancelled_at`	time, or null	When it was cancelled. A cancelled invitation cannot be accepted.

QuickBooks connection

qbo_connection. The connection of the book to a QuickBooks Online company: at most one row. The tokens are left out of the file. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`realm_id`	text	The id Intuit gives the connected QuickBooks company.
`environment`	text	The Intuit environment: sandbox or production.
`company_name`	text, or null	The name of the company as QuickBooks gives it.
`refresh_token_enc`	text	A secret: not in the file.
`refresh_expires_at`	time, or null	When the stored refresh token expires. Empty once disconnected.
`access_token_enc`	text	A secret: not in the file.
`access_expires_at`	time, or null	When the stored access token expires. Empty once disconnected.
`minorversion`	text	The minor version of the Intuit API the connection asks for.
`connected_at`	time
`api_calls`	whole number	How many metered calls to Intuit this connection has made in all.
`state`	text	shadow (the book follows QuickBooks and nothing is entered here) or cut_over (HomeBooks is the books and nothing more comes from QuickBooks).
`cut_over_at`	time, or null	When the book was cut over. Set exactly when state is cut_over.
`cut_over_by`	id, or null	The person who cut the book over.
`calls_month`	date, or null	The first day of the calendar month (UTC) that calls_in_month counts.
`calls_in_month`	whole number	How many metered calls to Intuit were made in that month.
`disconnected_at`	time, or null	When an owner disconnected QuickBooks. The row stays so the book keeps its state and history.
`disconnected_by`	id, or null
`revoke_refused`	text, or null	The answer Intuit gave when it did not confirm that the token was revoked at disconnect. Empty otherwise.
`cut_over_months`	whole number, or null	How many month-ends were compared with QuickBooks at the cut over. Frozen then.
`cut_over_months_out`	whole number, or null	How many of those month-ends were out of balance at the cut over.
`cut_over_locked_through`	date, or null	The locked period the cut over set from the QuickBooks closing date.
`cut_over_locked_before`	date, or null	The locked period that stood before the cut over set its own.

QuickBooks pulls

qbo_pull_attempt. One row per attempt to pull data from QuickBooks and build the ledger from it: when it ran, how it ended and whether the books tie out.

Field	Type	What it holds
`id`	id
`book_id`	id
`kind`	text	full (everything) or changes (what QuickBooks reports as changed since the last pull).
`reason`	text, or null	Why a full pull ran, in words, such as requested or first full pull. Empty for a changes pull.
`full_needed`	true or false	True when the full pull ran because something required it, not because it was asked for or due by the calendar.
`started_at`	time	When the attempt began, before its first call to Intuit.
`stored_at`	time, or null	When the attempt first stored anything from QuickBooks. Empty when it stored nothing.
`finished_at`	time, or null	When the attempt ended. Empty while outcome is running.
`outcome`	text	running, no_answer (QuickBooks gave no answer before anything was stored), not_trusted (the changes could not be relied on), failed or built.
`failure`	text, or null	What ended a failed attempt: a HomeBooks message or the kind of fault, never the text of the fault.
`lists_failed`	JSON	JSON object: each QuickBooks list the attempt asked for and did not get, with why.
`reports_failed`	JSON	JSON list: each report the attempt asked for and did not get, as report, end_date and why.
`calls`	whole number	How many metered calls to Intuit the attempt made.
`tie`	JSON, or null	JSON list: for each month-end compared with QuickBooks (as_of), how many accounts differ (differences). Set only when outcome is built.
`result`	JSON, or null	JSON: the result of the run as the QuickBooks page shows it, kept on the attempt that ended the run.
`building_at`	time, or null	When the attempt began writing the ledger. Empty when it never came to build.

QuickBooks records

qbo_record. One row per record pulled from QuickBooks, kept exactly as QuickBooks returned it. A later pull replaces a record in place.

Field	Type	What it holds
`id`	id
`book_id`	id
`entity`	text	The QuickBooks record type: Account, Customer, Vendor, Item, Invoice, Payment, Purchase, Deposit, JournalEntry and so on.
`qbo_id`	text	The QuickBooks id of the record, unique within its type.
`sync_token`	text, or null	The version counter QuickBooks keeps for the record (SyncToken), as last received.
`minorversion`	text	The minor version of the Intuit API the record was pulled with.
`body`	JSON	JSON: the record exactly as QuickBooks returned it.
`pulled_at`	time
`deleted_at`	time, or null	When QuickBooks reported the record as deleted. The record is kept as last received.

QuickBooks reports

qbo_report. One row per report pulled from QuickBooks for one period, kept as returned. The ledger is built and tied out from these.

Field	Type	What it holds
`id`	id
`book_id`	id
`name`	text	The report: JournalReport, TrialBalance or GeneralLedger.
`start_date`	date	The first day of the period the report was asked for.
`end_date`	date	The last day of the period the report was asked for.
`body`	JSON	JSON: the report exactly as QuickBooks returned it.
`pulled_at`	time

Reports sent

report_email. The log of reports sent by email: one row when a send starts and one for how it ended. The message and the PDF are not stored.

Field	Type	What it holds
`id`	id
`book_id`	id
`report`	text	Which report, as a short code: profit-and-loss, balance-sheet, trial-balance, cash-flow, schedule-c, budget, reconciliation, ar-aging, general-ledger, account-review.
`title`	text	The title of the report as printed, such as Profit and loss.
`period`	text	The period or date the report covers, in words as printed on it.
`params`	JSON	JSON: what the report was asked for. Only the fields given: start, end, as_of, year, from_month, to_month, reconciliation_id, account_ids and so on.
`sent_at`	time
`sent_by`	id
`from_address`	text
`to_address`	text
`cc_addresses`	list of text	A list of the addresses copied.
`subject`	text
`outcome`	text	sending (the send was started), sent or failed. A sending row with no sent or failed row for the same send_key was never confirmed.
`error`	text, or null	What the mail server said. Set exactly when outcome is failed.
`send_key`	id	The id of one press of Send. The sending row and its sent or failed row share it.
`platform_mail`	true or false	True when the send went through HomeBooks mail, the mail server of the installation, and not the sender's own. False on rows from before HomeBooks mail.

Support access

support_grant. One row per grant of time-limited support access that an owner gave the platform administrator.

Field	Type	What it holds
`id`	id
`book_id`	id
`level`	text	viewer (view only) or editor (may edit as an editor would). Never owner powers.
`note`	text, or null	The note the owner wrote on the grant.
`granted_by`	id
`created_at`	time
`expires_at`	time	When the grant runs out: at most 7 days after it was made.
`ended_at`	time, or null	When an owner ended the grant early. Empty otherwise.
`ended_by`	id, or null
`first_used_at`	time, or null	When the platform administrator first used the grant.
`last_used_at`	time, or null	When the platform administrator last used the grant.

History

audit_event. One row per recorded change: who did what, to which record, and when. Rows are never changed or deleted.

Field	Type	What it holds
`id`	id
`book_id`	id
`user_id`	id, or null	The person who did it. Empty for what no person did, such as a scheduled bank fetch or a migration.
`at`	time	When it happened: the time of the database transaction that made the change.
`action`	text	What was done, as a dotted code: txn.post, txn.void, account.kind, feed.fetch, qbo.pull and so on.
`entity`	text	The kind of record the event is about, by its table name: txn, account, payee, invoice, bank_line, book and so on.
`entity_id`	id, or null	The id of that record in the section entity names. A few events carry another identifier here, or none.
`before`	JSON, or null	JSON: the values before the change, for the fields this event records. Empty when there were none.
`after`	JSON, or null	JSON: the values after the change, or the details of what was done. Empty when there are none.
`support_grant_id`	id, or null	The grant (Support access) in force when the platform administrator, who is no member, made this change. Empty otherwise.

Imported bank files

bank_import. One row per bank file imported into a bank or card account. Its lines are in Bank lines.

Field	Type	What it holds
`id`	id
`book_id`	id
`account_id`	id	The bank or card account (Chart of accounts) the file was imported into.
`filename`	text
`format`	text	The format of the file: ofx, qfx, qbo (a Web Connect file, not QuickBooks Online) or csv.
`imported_by`	id, or null
`imported_at`	time
`line_count`	whole number	How many lines of the file were staged as new bank lines.
`duplicate_count`	whole number	How many lines of the file were already there and were not staged again.
`statement_balance`	amount, as text, or null	The ending balance the file states (an OFX ledger balance), with the sign the file gives it. Empty when the file states none.
`statement_date`	date, or null	The date the file gives for that balance.
`csv_mapping`	JSON, or null	JSON: for a CSV, which column number holds the date, amount or debit and credit, description, memo, reference and id, plus has_header, negate and date_order.

Budgets

budget. One row per income or expense account, year and month: the amount planned. Actual figures are read from Entry lines, never stored here.

Field	Type	What it holds
`id`	id
`book_id`	id
`account_id`	id	The income or expense account (Chart of accounts) the amount is planned for.
`year`	whole number	The calendar year.
`month`	whole number	The calendar month of that year, 1 to 12.
`amount`	amount, as text	The amount planned for the month, never negative: the income expected, or the expense allowed.

Bank feed accounts

feed_account. One row per account a bank connection lists, and the account of the book it feeds, if any. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`connection_id`	id	The connection (Bank connections) that lists the account.
`external_id`	text	The id the provider gives the account.
`name`	text	The name of the account as the provider gives it.
`bank`	text	The name of the bank as the provider gives it. May be empty.
`currency`	text, or null	The currency of the account as the provider gives it.
`account_id`	id, or null	The bank or card account (Chart of accounts) this feed account feeds. Empty when it feeds none.
`start_date`	date, or null	The first day whose transactions are taken. Set exactly when account_id is set.
`backfill_from`	date, or null	The start of earlier days still to be fetched, when the start date reaches back past the regular fetch. Empty when nothing waits.
`created_at`	time
`mask`	text, or null	The last digits of the account number, as Plaid gives them.
`kind`	text, or null	The type of the account as Plaid gives it: depository, credit, loan and so on.
`paired_with`	id, or null	On a SimpleFIN account that feeds nothing: the Plaid account (Bank feed accounts) of the same bank and last four digits whose blanked descriptions it fills.

Loan terms

loan_term. One row per day the terms of a Loan account change. A row holds only what changed that day; a field with no value means as before.

Field	Type	What it holds
`id`	id
`book_id`	id
`account_id`	id	The Loan account (Chart of accounts) the terms are of.
`starts_on`	date	The day these terms begin.
`interest_method`	text, or null	How interest is calculated: monthly (balance x rate / 12) or daily (balance x rate / 365 x days).
`rate`	decimal number, as text, or null	The yearly interest rate as a percentage, 0 to 100: 6.5 is 6.5%.
`payments_due`	text, or null	monthly, quarterly or annually.
`due_day`	whole number, or null	The day of the month a payment is due, 1 to 31.
`due_month`	whole number, or null	The month a yearly payment is due, or one of the four a quarterly payment is due, 1 to 12.
`payment_type`	text, or null	interest_only or amortized.
`payment_amount`	amount, as text, or null	The regular payment of principal and interest. An amortized loan has one.
`maturity`	date, or null	The maturity date of the loan.
`escrow_amount`	amount, as text, or null	The escrow paid with each payment; 0.00 for none.
`escrow_account_id`	id, or null	The asset account (Chart of accounts) escrow is paid into.
`interest_account_id`	id, or null	The expense account (Chart of accounts) the interest goes to.
`created_at`	time

Contacts

payee. One row per contact: anyone the book pays or bills. Customers and vendors are contacts with that role.

Field	Type	What it holds
`id`	id
`book_id`	id
`name`	text
`is_customer`	true or false	True when the contact is a customer. A contact may be a customer, a vendor, both or neither.
`is_vendor`	true or false	True when the contact is a vendor.
`default_account_id`	id, or null	No longer used. The account a contact was last paid from is now read from the ledger.
`tax_exempt`	true or false	True when the customer pays no sales tax.
`active`	true or false
`created_at`	time
`billing_address`	text, or null
`terms_days`	whole number, or null	The payment terms of the customer in days, 0 to 365. A new invoice starts from it.
`tax_certificate`	text, or null	The tax exemption certificate number of the customer.
`shipping_address`	text, or null
`merged_into_id`	id, or null	On a contact merged into another, the contact (Contacts) that survives. Records that name this contact are read as naming the survivor.
`job_of_id`	id, or null	For a QuickBooks job (sub-customer), the customer (Contacts) it is a job of.

Products and services

product. One row per product or service sold. Document lines may point here.

Field	Type	What it holds
`id`	id
`book_id`	id
`name`	text
`description`	text, or null
`unit_price`	decimal number, as text	The price a new document line starts from. Up to five decimals.
`income_account_id`	id	The income account (Chart of accounts) its sales are posted to.
`taxable`	true or false	Whether sales tax applies to it by default.
`active`	true or false
`created_at`	time

Statements

reconciliation. One row per bank or card statement reconciled against an account. Its cleared lines are in Cleared lines.

Field	Type	What it holds
`id`	id
`book_id`	id
`account_id`	id	The asset or liability account (Chart of accounts) being reconciled.
`statement_date`	date
`statement_balance`	amount, as text	The ending balance of the statement, in the sign of the ledger: a card that owes 500.00 is -500.00.
`opening_balance`	amount, as text	The beginning balance of the statement, in the same sign.
`status`	text	open or finished. An account has at most one open statement.
`created_by`	id, or null
`created_at`	time
`finished_by`	id, or null
`finished_at`	time, or null	When it was finished. Set exactly when status is finished.
`show_from`	date, or null	On the first statement of an account only: entries dated before this date start as cleared before the statement. Shown as Show entries from.
`opening_day`	date, or null	The day of the opening balance the statement counts as cleared before it, on the first statement of an account: written by the database when the statement is begun, from the account as it then stands, and never changed. Empty when the account had no opening balance then, and on every statement begun before this field was added: such a statement lists an opening balance as a line to tick.

Contact emails

contact_email. One row per email address of a contact.

Field	Type	What it holds
`id`	id
`book_id`	id
`payee_id`	id	The contact (Contacts) the address belongs to.
`position`	whole number	The order of the address among the emails of the contact, starting at 0.
`address`	text
`is_primary`	true or false	True on the primary email of the contact. At most one per contact.

Merged contacts

contact_merge. One row per merge of two contacts, with what it changed so that Split can undo exactly that.

Field	Type	What it holds
`id`	id
`book_id`	id
`survivor_id`	id	The contact (Contacts) that was kept.
`merged_id`	id	The contact (Contacts) that was merged into it. Its row stays, pointing at the survivor.
`merged_by`	id
`merged_at`	time
`detail`	JSON	JSON: what the merge changed. The fields of the survivor before and after, the phones and emails added to it, and the ids of the rows moved to it.
`split_by`	id, or null	The person who split the merge again. Empty while the merge stands.
`split_at`	time, or null	When the merge was split again. Empty while the merge stands.

Not duplicates

contact_not_duplicate. One row per pair of contacts a person marked as not duplicates, so the pair is not suggested for merging again.

Field	Type	What it holds
`id`	id
`book_id`	id
`a_id`	id	One contact (Contacts) of the pair: the one with the lower id.
`b_id`	id	The other contact (Contacts) of the pair.
`dismissed_by`	id
`dismissed_at`	time

Contact phones

contact_phone. One row per phone number of a contact.

Field	Type	What it holds
`id`	id
`book_id`	id
`payee_id`	id	The contact (Contacts) the number belongs to.
`position`	whole number	The order of the number among the phones of the contact, starting at 0.
`number`	text
`label`	text	Mobile, Work, Home, Fax or Other.
`note`	text, or null
`is_primary`	true or false	True on the primary phone of the contact. At most one per contact.

Bank balances

feed_balance. One row per balance a bank feed reported for a feed account, shown as Bank balance beside the book balance. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`feed_account_id`	id	The feed account (Bank feed accounts) the balance is of.
`balance`	amount, as text	The balance at the bank, in the sign of the ledger: owed on a card or loan is negative. Plaid figures are turned to that sign; SimpleFIN figures are kept as sent.
`available_balance`	amount, as text, or null	The available balance as the provider sends it. For a Plaid card this is the credit left to spend, not an amount owed.
`as_of`	time	The moment the provider dates the balance by.
`fetched_at`	time	When HomeBooks was last told this balance.

Pending bank transactions

feed_pending. One row per transaction a bank feed lists as pending, replaced at every fetch. They are not bank lines and reach Review only once they post. Listed, not restored.

Field	Type	What it holds
`id`	id
`book_id`	id
`feed_account_id`	id	The feed account (Bank feed accounts) the transaction is on.
`external_id`	text	The id the provider gives the transaction.
`day`	date	The date of the transaction as the provider gives it.
`amount`	amount, as text	Signed as a bank line: positive is money into the account, negative is money out.
`name`	text, or null
`memo`	text, or null
`seen_at`	time	When the fetch that listed it ran.

Rules

import_rule. One row per rule that categorizes bank lines by their text. Rules apply in order and the first active one that matches decides.

Field	Type	What it holds
`id`	id
`book_id`	id
`position`	whole number	The place of the rule in the order. Lower numbers are tried first.
`match_field`	text	Which text of the bank line is matched: name (shown as Payee), memo, or any (either).
`match_type`	text	contains, starts_with or equals. Case and extra spaces are ignored.
`match_text`	text	The text looked for.
`account_id`	id	The account (Chart of accounts) the rule gives a matching line.
`use`	text, or null	personal or business: the use the rule gives the line. Empty: the default use of the account, or a business share is set instead.
`business_share`	decimal number, as text, or null	The share of the line posted as business, from 0 to 1 (0.25 is 25%). Never set together with use.
`payee_id`	id, or null	The contact (Contacts) the rule gives a matching line. Optional.
`active`	true or false
`created_at`	time
`principal_only`	true or false	On a rule to a Loan account: true posts the whole line to principal; false splits it as the payment of the loan.

Reconciliation reports

reconciliation_report. One row per finish of a statement: the reconciliation report saved at that moment. A statement reopened and finished again has more than one.

Field	Type	What it holds
`id`	id
`book_id`	id
`reconciliation_id`	id	The statement (Statements) the report is of.
`finished_at`	time
`finished_by`	id, or null
`report`	JSON	JSON: the report as saved: account, statement date, the balances and difference, the cleared and outstanding lines, the register balance, who finished it and when.

Sales tax agencies

tax_agency. One row per agency that sales tax is collected for and paid to. Its rates are in Sales tax rates.

Field	Type	What it holds
`id`	id
`book_id`	id
`name`	text
`payee_id`	id	The contact (Contacts) the sales tax payments of the agency are made to.
`active`	true or false
`created_at`	time

Entries

txn. One row per journal entry. Its lines are in Entry lines. A posted entry is never edited: it is voided by a reversing entry.

Field	Type	What it holds
`id`	id
`book_id`	id
`number`	whole number	The number of the entry in this book, counted from 1.
`date`	date
`payee_id`	id, or null	The contact (Contacts) of the entry. Optional.
`memo`	text, or null
`status`	text	posted or void. A void entry has been reversed by another entry.
`reverses_id`	id, or null	On a reversal, the entry (Entries) it reverses. An entry is reversed at most once.
`source`	text	What posted it: manual, import (a bank line), setup (opening balances), qbo, invoice, sales_receipt, credit_memo, payment, write_off, tax_payment, correction, void, close.
`source_ref`	text, or null	The key of the entry at its source, unique per source: for qbo the type and id (Invoice:130); a document, payment or write-off id; bank_line:id:attempt; the entry corrected.
`created_by`	id, or null
`created_at`	time
`reference`	text, or null	The check number, confirmation code or document number. Free text.

Bank lines

bank_line. One row per transaction a bank reported, from a file or a feed, shown under Review. A line added or matched points to its entry in Entries.

Field	Type	What it holds
`id`	id
`book_id`	id
`account_id`	id	The bank or card account (Chart of accounts) the line belongs to.
`import_id`	id, or null	The file (Imported bank files) the line came from. Empty for a line from a bank feed.
`source`	text	Where the line came from: import (a file), simplefin or plaid.
`source_ref`	text	The id the bank gave the transaction: an OFX FITID, the transaction id of the feed, or csv: plus a hash of the row. A suffix ~2, ~3 marks an id the bank used again.
`posted_on`	date	The day the bank posted the transaction.
`amount`	amount, as text	Signed from the side of the account holder: positive is money in (a deposit, a payment to a card), negative is money out (a purchase, a card charge). Never zero.
`name`	text, or null	The description or payee text the bank gave.
`memo`	text, or null	The memo the bank gave. For a Plaid line, the merchant name.
`reference`	text, or null	The check or reference number a file gave. Empty for a line from a feed.
`trntype`	text, or null	The transaction type an OFX file gave (TRNTYPE). Empty for CSV and feeds.
`fingerprint`	text	Date, amount and the first word of the name, in lower case. The same transaction from another source has the same one, which flags a possible duplicate.
`raw`	JSON	JSON: the transaction as the source gave it (OFX fields, a CSV row by column name, or the id, day, amount and texts of a feed). A Plaid amount here is positive for money out.
`status`	text	new (to review), posted (added as a new entry), matched (matched to an entry already posted) or excluded.
`txn_id`	id, or null	The entry (Entries) the line was added as or matched to. Set exactly when status is posted or matched.
`suggested_account_id`	id, or null	The account (Chart of accounts) the line will be added to, chosen by a rule or by a person.
`suggested_use`	text, or null	personal or business: the use the line will be added with. Empty: the default use of the account, or a business share is set instead.
`suggested_share`	decimal number, as text, or null	The business share the line will be split by, from 0 to 1 (0.25 is 25% business). Never set together with suggested_use.
`suggested_payee_id`	id, or null	The contact (Contacts) the line will be added with.
`rule_id`	id, or null	The rule (Rules) that made the suggestion. Empty when a person chose it or nothing is suggested.
`possible_duplicate_of`	id, or null	An earlier line (Bank lines) that may be the same transaction: the same fingerprint from another source, or the same bank id with another date or amount.
`decided_by`	id, or null	The person who added, matched or excluded the line. Empty while it is to review, and when no person did it (an automatic match).
`decided_at`	time, or null	When the line was added, matched or excluded. Empty while it is to review.
`created_at`	time
`attempt`	whole number	How many times the line went back to Review because the entry it was added as was voided. Starts at 0.
`picked_by_hand`	true or false	True when a person gave the line its account. Rules then leave the line alone.
`possible_entry_id`	id, or null	An entry (Entries) that may already record this feed line, when more than one could. The line waits for a person to decide.
`fill_name`	text, or null	A readable description taken from a SimpleFIN transaction for a Plaid line whose own description the bank blanked. Kept beside name, never in place of it.
`fill_memo`	text, or null	The memo that came with that SimpleFIN description.
`fill_ref`	text, or null	The id of the SimpleFIN transaction the description came from.
`filled_at`	time, or null	When that description was filled in.
`taken_back`	true or false	True when the bank changed or removed the transaction after it was staged. The line stays as a record and can only be excluded. Never unset.
`fill_cleared`	list of text	A list of SimpleFIN transaction ids a person cleared from this line, oldest first. None of them fills the line again.
`unmatched_from`	list of ids	A list of entry ids (Entries) a person unmatched the line from. Automatic matching never offers them again.
`pair_declined`	true or false	True when a person said the line is not one side of the transfer it was paired as. It is not paired again until the person picks the other account.

Contact aliases

contact_alias. One row per other name a contact answers to: the name of a contact merged into it, or its own name before a rename. Shown as Aliases.

Field	Type	What it holds
`id`	id
`book_id`	id
`payee_id`	id	The contact (Contacts) that answers to this name.
`name`	text
`merge_id`	id, or null	The merge (Merged contacts) that brought this name. Empty for a name kept after a rename.
`created_at`	time

Loan payments

loan_payment. One row per entry recorded as the payment of a loan, by Review or by Record payment. Its amounts are the lines of the entry.

Field	Type	What it holds
`book_id`	id
`txn_id`	id	The entry (Entries) that is the payment.
`account_id`	id	The Loan account (Chart of accounts) it pays.
`due_on`	date, or null	The due date the payment was split as paying; none for an extra payment.

Payments

payment. One row per payment received from a customer. What it paid is in Payments applied. Any amount not applied is credit of the customer.

Field	Type	What it holds
`id`	id
`book_id`	id
`customer_id`	id	The customer (Contacts) who paid.
`date`	date
`amount`	amount, as text	The amount received, always above zero.
`deposit_account_id`	id	The account (Chart of accounts) the money went into: a bank account or Undeposited funds.
`reference`	text, or null	The check number or other reference of the payment.
`memo`	text, or null
`txn_id`	id	The entry (Entries) that recorded the payment. The payment stands while that entry is not void.
`created_by`	id, or null
`created_at`	time
`qbo_ref`	text, or null	For a payment that came from QuickBooks, its transaction as type and id (Payment:128). Empty for one recorded in HomeBooks.
`method`	text, or null	The QuickBooks payment method, such as Check. Set only on a payment from QuickBooks.

Sales tax rates

tax_rate. One row per version of a sales tax rate. Rows with the same name are versions of one rate. Its parts are in Sales tax components.

Field	Type	What it holds
`id`	id
`book_id`	id
`agency_id`	id	The agency (Sales tax agencies) the rate belongs to.
`name`	text
`effective_from`	date	The first day this version applies. A document uses the newest version effective on or before its date.
`active`	true or false
`created_at`	time

Entry lines

txn_line. One row per line of an entry: an account and a signed amount. The lines of an entry add up to 0.00, and a posted line never changes.

Field	Type	What it holds
`id`	id
`book_id`	id
`txn_id`	id	The entry (Entries) this line belongs to.
`line_no`	whole number	The place of the line in the entry, starting at 1.
`account_id`	id	The account (Chart of accounts) the line is on.
`amount`	amount, as text	Signed: positive is a debit, negative is a credit. Never zero.
`use`	text, or null	personal or business. Every income and expense line has one.
`tag`	text, or null	An optional free-text label on the line. The screens leave it empty.
`memo`	text, or null
`payee_id`	id, or null	The contact (Contacts) of the line itself, as on a journal entry. Optional.

Sales documents

invoice. One row per invoice, sales receipt or credit memo. Its figures are in Document revisions, its lines in Document lines.

Field	Type	What it holds
`id`	id
`book_id`	id
`kind`	text	invoice, sales_receipt or credit_memo.
`number`	whole number, or null	The document number, given from the sequence of its kind when issued. Empty on a draft, and on a QuickBooks document whose number is in doc_number or that has none.
`customer_id`	id	The customer (Contacts).
`date`	date
`terms_days`	whole number	Days from the date to the due date. 0 to 365 for a document typed here. A QuickBooks document keeps its QuickBooks due date, so it may be outside that range.
`due_date`	date
`memo`	text, or null
`status`	text	draft (posts nothing), issued or void. Paid and partly paid are not stored: they are worked out from what is applied.
`tax_rate_id`	id, or null	The sales tax rate (Sales tax rates) chosen for the document. Empty for none.
`deposit_account_id`	id, or null	For a sales receipt, the account (Chart of accounts) the money went into. Empty on invoices and credit memos.
`current_revision`	whole number	The revision in force (Document revisions). 0 while a draft, 1 when issued, one more for each later change.
`created_by`	id, or null
`created_at`	time
`issued_at`	time, or null
`voided_at`	time, or null
`qbo_ref`	text, or null	For a document that came from QuickBooks, its transaction as type and id (Invoice:130). Empty for one typed in HomeBooks.
`doc_number`	text, or null	The QuickBooks number exactly as printed, when it cannot be held in number: not a plain number, a leading zero, or already used.
`billing_address`	text, or null	The billing address as written on a QuickBooks document. A document typed here has none and reads the address of the customer.
`shipping_address`	text, or null	The shipping address as written on a QuickBooks document. A document typed here has none and reads the address of the customer.

QuickBooks cleared marks

qbo_line_mark. One row per entry line that QuickBooks held as cleared or reconciled. The first statement of an account starts from these marks.

Field	Type	What it holds
`book_id`	id
`line_id`	id	The entry line (Entry lines) the mark is on. Only lines of entries that came from QuickBooks carry one.
`account_id`	id	The account (Chart of accounts) of that line, repeated here by the database.
`mark`	text	R (reconciled in QuickBooks) or C (cleared in QuickBooks, not yet on a finished reconciliation there).

QuickBooks record map

qbo_map. One row per QuickBooks list record and the record of the book made from it: an account, a contact, a product, a tax agency or a tax rate.

Field	Type	What it holds
`id`	id
`book_id`	id
`entity`	text	The QuickBooks record type: Account, Customer, Vendor, Item, TaxAgency or TaxCode.
`qbo_id`	text	The QuickBooks id of the record, unique within its type.
`account_id`	id, or null	The account (Chart of accounts) a QuickBooks Account became. Exactly one of the five target columns is set.
`payee_id`	id, or null	The contact (Contacts) a QuickBooks Customer or Vendor became.
`seen_name`	text, or null	The name QuickBooks last gave the record, so a rename there is told from a rename here.
`seen_active`	true or false, or null	The active flag QuickBooks last gave the record.
`product_id`	id, or null	The product or service (Products and services) a QuickBooks Item became.
`seen`	JSON, or null	JSON: the details QuickBooks last gave for a contact, a product or a tax code, so a field follows QuickBooks only when QuickBooks changed it.
`tax_agency_id`	id, or null	The agency (Sales tax agencies) a QuickBooks TaxAgency became.
`tax_rate_id`	id, or null	The rate (Sales tax rates) a QuickBooks TaxCode became.

Cleared lines

reconciliation_line. One row per entry line ticked as cleared on a statement, or marked cleared before the first statement of an account. A line is on one statement at most.

Field	Type	What it holds
`book_id`	id
`reconciliation_id`	id	The statement (Statements).
`line_id`	id	The entry line (Entry lines) that is ticked or marked.
`ticked_by`	id, or null	The person in scope when the line was ticked or marked. Empty when no person was.
`ticked_at`	time
`prior`	true or false	True for a line marked cleared before the first statement of an account. Marks count for nothing in its figures; together they must equal its beginning balance.

Marks taken off

reconciliation_line_off. One row per entry line a person took a tick or mark off on the first statement of an account, so QuickBooks marks do not put it back. No screen shows it.

Field	Type	What it holds
`book_id`	id
`reconciliation_id`	id	The statement (Statements).
`line_id`	id	The entry line (Entry lines) the tick or mark was taken off.

Sales settings

sales_setting. The sales settings of the book: one row. The accounts sales post to, the heading printed on a document, and what a new document starts from.

Field	Type	What it holds
`book_id`	id
`receivable_account_id`	id, or null	The account (Chart of accounts) used as Accounts receivable. An invoice is issued only once it is set.
`undeposited_account_id`	id, or null	The account (Chart of accounts) used as Undeposited funds, for payments received and not yet deposited.
`business_name`	text, or null	The business name printed at the head of a document.
`address`	text, or null	The address printed at the head of a document.
`phone`	text, or null	The phone number printed at the head of a document.
`email`	text, or null	The email address printed at the head of a document.
`default_terms_days`	whole number, or null	The terms in days a new invoice starts with when its customer has none.
`default_tax_rate_id`	id, or null	The sales tax rate (Sales tax rates) a new document starts with.
`default_memo`	text, or null	The memo a new document starts with.
`email_subject`	text, or null	The subject a new document email starts with.
`email_message`	text, or null	The message a new document email starts with.
`discount_account_id`	id, or null	The income or expense account (Chart of accounts) a new discount line starts with.
`bad_debt_account_id`	id, or null	The expense account (Chart of accounts) the last write-off of an invoice was charged to, offered for the next one.

Sales tax components

tax_component. One row per part of a sales tax rate, such as State, County or City, each with its own percentage and liability account.

Field	Type	What it holds
`id`	id
`book_id`	id
`rate_id`	id	The rate (Sales tax rates) the component belongs to.
`position`	whole number	The place of the component within the rate, starting at 1.
`name`	text
`percent`	decimal number, as text	The rate of the component as a percentage: 6.25 is 6.25%. From 0 to below 100, up to four decimals.
`liability_account_id`	id	The liability account (Chart of accounts) the tax of the component is credited to.

Credit applied

credit_application. One row per amount of customer credit applied to an invoice, from a credit memo or from the unapplied part of a payment. It posts no entry.

Field	Type	What it holds
`id`	id
`book_id`	id
`credit_memo_id`	id, or null	The credit memo (Sales documents) the credit comes from. Exactly one of credit_memo_id and payment_id is set.
`invoice_id`	id	The invoice (Sales documents) the credit is applied to.
`amount`	amount, as text	The credit applied, always above zero.
`qbo_ref`	text, or null	The QuickBooks transaction that made the application, as type and id (Payment:74). Empty for one applied by hand in HomeBooks.
`created_at`	time
`removed_at`	time, or null	When the application was taken back. A row is never changed or deleted, only marked removed. Empty while it stands.
`payment_id`	id, or null	The payment (Payments) whose unapplied remainder the credit comes from.
`date`	date	The day the credit was applied.
`created_by`	id, or null
`removed_by`	id, or null	The person who took it back. Empty when it stands, or when QuickBooks took it back.

Documents sent

document_email. The log of sales documents sent by email: one row when a send starts and one for how it ended. The message and the PDF are not stored.

Field	Type	What it holds
`id`	id
`book_id`	id
`invoice_id`	id	The document (Sales documents) that was sent.
`revision`	whole number	The revision of the document that was sent (Document revisions).
`sent_at`	time
`sent_by`	id
`to_address`	text
`cc_addresses`	list of text	A list of the addresses copied.
`subject`	text
`outcome`	text	sending (the send was started), sent or failed. A sending row with no sent or failed row for the same send_key was never confirmed.
`error`	text, or null	What the mail server said. Set exactly when outcome is failed.
`from_address`	text, or null	The address the message was sent from. Empty on the oldest rows.
`send_key`	id, or null	The id of one press of Send. The sending row and its sent or failed row share it. Empty on the oldest rows.
`platform_mail`	true or false	True when the send went through HomeBooks mail, the mail server of the installation, and not the sender's own. False on rows from before HomeBooks mail.

Document lines

invoice_line. One row per line of a sales document, for each of its revisions: an item, the one discount line, or a text line.

Field	Type	What it holds
`id`	id
`book_id`	id
`invoice_id`	id	The document (Sales documents) the line is on.
`revision`	whole number	The revision of the document the line belongs to. 0 for the lines of a draft.
`position`	whole number	The place of the line on the document, starting at 1.
`product_id`	id, or null	The product or service (Products and services) sold. Optional, item lines only.
`description`	text
`quantity`	decimal number, as text, or null	Up to three decimals, never zero. Item lines only.
`unit_price`	decimal number, as text, or null	Up to five decimals. Item lines only.
`taxable`	true or false, or null	Whether sales tax applies to the line. Item lines only.
`income_account_id`	id, or null	The account of the line (Chart of accounts): the income account of an item, or the account of the discount. Empty on a text line.
`amount`	amount, as text, or null	Item: quantity times unit price, rounded half up to the cent (a QuickBooks line keeps the QuickBooks amount). Discount: below zero. Text line: empty.
`line_type`	text	item, discount (at most one per revision, after the items) or text (a description only, with no amount).
`discount_percent`	decimal number, as text, or null	On a discount given as a percentage, that percentage: above 0, at most 100 (10 is 10%). Empty otherwise.

Document revisions

invoice_revision. One row per issued version of a sales document, with its totals and the entry it posted. Changing an issued document adds a revision.

Field	Type	What it holds
`id`	id
`book_id`	id
`invoice_id`	id	The document (Sales documents).
`revision`	whole number	1 for the document as first issued, then 2, 3 and so on.
`txn_id`	id	The entry (Entries) this revision posted. For a QuickBooks document, the entry built from QuickBooks for its transaction.
`date`	date	The date of the document in this revision.
`due_date`	date	The due date in this revision.
`tax_rate_id`	id, or null	The sales tax rate (Sales tax rates) used in this revision.
`subtotal`	amount, as text	The item lines plus the discount line. A credit memo keeps the same sign as an invoice.
`taxable_subtotal`	amount, as text	The part of the subtotal that sales tax is worked out on. 0.00 for a tax-exempt customer.
`tax_amount`	amount, as text	The sales tax: the sum of the rows of this revision in Document sales tax.
`total`	amount, as text	subtotal plus tax_amount.
`created_by`	id, or null
`created_at`	time

Document sales tax

invoice_tax. One row per component of the sales tax on one revision of a sales document: its percentage, its liability account and the tax.

Field	Type	What it holds
`id`	id
`book_id`	id
`invoice_id`	id	The document (Sales documents).
`revision`	whole number	The revision of the document (Document revisions).
`position`	whole number	The place of the component among the tax rows of the revision, starting at 1.
`name`	text	The name of the component, such as State or County, copied onto the document.
`percent`	decimal number, as text	The rate of the component as a percentage: 6.25 is 6.25%.
`liability_account_id`	id	The liability account (Chart of accounts) the tax was credited to.
`amount`	amount, as text	The tax for this component: the taxable subtotal times the percentage, rounded half up to the cent. A QuickBooks document keeps the QuickBooks figure.

Payments applied

payment_application. One row per amount of a payment applied to an invoice, written with the payment.

Field	Type	What it holds
`id`	id
`book_id`	id
`payment_id`	id	The payment (Payments).
`invoice_id`	id	The invoice (Sales documents) it paid.
`amount`	amount, as text	The amount applied to that invoice, always above zero.
`created_at`	time

Write-offs

write_off. One row per write-off of the balance of an invoice, or of the credit left on a payment or credit memo. It stands while its entry is not void.

Field	Type	What it holds
`id`	id
`book_id`	id
`invoice_id`	id, or null	The invoice (Sales documents) whose balance is written off. Exactly one of invoice_id, payment_id and credit_memo_id is set.
`payment_id`	id, or null	The payment (Payments) whose unapplied credit is written off.
`credit_memo_id`	id, or null	The credit memo (Sales documents) whose remaining credit is written off.
`txn_id`	id	The entry (Entries) that posted the write-off. The date, memo and expense account of the write-off are those of the entry.
`amount`	amount, as text	The amount written off, always above zero.
`created_by`	id, or null
`created_at`	time