Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Banking

Bank accounts, their transactions, and explaining what each transaction was. Conventions for ids, money, paging and errors are on Working with the tools.

Bank amounts follow FreeAgent: money out is negative and money in positive.

Accounts and transactions

ToolKindWhat it doesKey parameters
list_bank_accountsreadThe company’s bank, credit card and PayPal accounts with id, name, type, currency and FreeAgent’s current_balance (from explained transactions, not the bank’s live balance)view: standard_bank_accounts, credit_card_accounts or paypal_accounts (default all)
get_bank_accountreadOne bank account in full: type, currency, balance, account details and latest activityid
list_bank_transactionsreadOne account’s transactions with date, amount, description, unexplained_amount and their explanationsbank_account_id, view, from_date, to_date, updated_since, last_uploaded, page, per_page
get_bank_transactionreadOne bank transaction in full, with its explanationsid
list_bank_feedsreadWhich accounts are connected to their bank, the feed state, and when its authorisation (SCA) expires and must be renewed in FreeAgentnone
upload_bank_statementwriteAdd transactions to an account from statement lines, for example for an account without a bank feedbank_account_id, lines (1 to 100, below)

list_bank_transactions view: all (default), unexplained (what still needs explaining), explained, manual, imported or marked_for_review (explained by FreeAgent’s guess, awaiting approval). last_uploaded: true shows only the transactions of the latest statement upload.

Statement lines

Each line of upload_bank_statement’s lines:

FieldMeaning
dated_on, descriptionRequired
amountRequired. Money out negative, money in positive
fitidThe bank’s own transaction id, if known, so it is not imported twice
transaction_typeCREDIT, DEBIT, INT, DIV, FEE, SRVCHG, DEP, ATM, POS, XFER, CHECK, PAYMENT, CASH, DIRECTDEP, DIRECTDEBIT, REPEATPMT or OTHER (default)

Upload whole days: FreeAgent skips lines that match one already there by date, amount and description. Afterwards, list_bank_transactions with last_uploaded: true shows what was imported.

Explanations

ToolKindWhat it doesKey parameters
list_bank_transaction_explanationsreadThe explanations of one account’s transactions: what each payment or receipt was (category, invoice, bill, transfer or user), with VATbank_account_id, marked_for_review_only, from_date, to_date, updated_since, page, per_page
explain_bank_transactionwriteExplain (categorise) a transaction: what the money was (below)bank_transaction_id, and one of category, paid_invoice_id, paid_bill_id, transfer_bank_account_id or paid_user_id
update_bank_transaction_explanationwriteChange only the fields given. marked_for_review: false approves one FreeAgent guessedid, explanation fields, marked_for_review
delete_bank_transaction_explanationwrite, destructiveDelete an explanation, leaving the transaction unexplained againid
approve_explanationswriteApprove explanations FreeAgent guessed in one account (below)bank_account_id, explanation_ids or approve_all, from_date, to_date

Explaining a transaction

explain_bank_transaction takes the transaction (bank_transaction_id, from list_bank_transactions with view unexplained) and one way of saying what the money was:

FieldThe money was
categoryAn ordinary payment or receipt, by nominal code such as 285 or 001; see list_categories
paid_invoice_idA customer paying an invoice (or a credit note refunded)
paid_bill_idPaying a supplier’s bill (or a bill refund)
transfer_bank_account_idMoved to or from another of the company’s own accounts
paid_user_idPaid to or received from a director or employee (expenses repaid, salary, director’s loan). Add category for a specific kind, such as 902 net salary

Other fields: gross_value (the amount explained), dated_on, description, sales_tax_rate (default from the category), sales_tax_status (TAXABLE, EXEMPT or OUT_OF_SCOPE), ec_status (UK/Non-EC, EC Goods, EC Services, Reverse Charge or EC VAT MOSS), foreign_currency_value (for a foreign-currency invoice or bill, the amount in its currency), project_id and rebill_type (cost, markup or price), receipt_reference, attachment (see Attachments) and extra for any other explanation field, such as a stock item or capital asset.

  • gross_value and dated_on default to the transaction’s unexplained amount and date.
  • An amount with the wrong sign, or more than is unexplained, is refused. So is a transaction that is already fully explained: change its explanation with update_bank_transaction_explanation instead.
  • A part explanation leaves the rest unexplained, to explain separately.

Approving FreeAgent’s guesses

FreeAgent guesses explanations for imported transactions and marks them for review. approve_explanations works on one account:

  • With neither explanation_ids nor approve_all, it only lists the explanations awaiting approval (in the dates given) and changes nothing, so you can show them to the person.
  • With explanation_ids, it approves those, up to 200; the dates are then not used.
  • With approve_all: true, it approves every explanation awaiting approval in the account and dates, up to 200.

The result lists the ids approved and any that failed. update_bank_transaction_explanation with marked_for_review: false approves a single one.