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

Purchases

Bills from suppliers, expenses people paid themselves, and mileage. Conventions for ids, money, paging and errors are on Working with the tools.

Which tool to use for a cost:

  • A supplier’s invoice the company will pay: a bill (create_bill). Pay it by explaining the bank transaction with paid_bill_id.
  • Something a person paid personally and is owed back: an expense (create_expense).
  • A cost paid from a company bank account or card: neither. Explain the bank transaction instead (Banking).
  • Business mileage: create_mileage_claim.

Bills

ToolKindWhat it doesKey parameters
list_billsreadBills with reference, supplier, dates, status, total_value and due_value. view open_or_overdue shows what the company owesview: all (default), open, overdue, open_or_overdue, paid, recurring, hire_purchase or cis; contact_id, project_id, from_date, to_date, updated_since, with_items, page, per_page
get_billreadOne bill in full, with its lines, VAT and what is paid and dueid
create_billwriteRecord a bill: reference, date, lines with a category and total including VAT, and optionally the supplier’s invoice attached. Due 30 days after its date unless due_on is givencontact_id, reference, dated_on, due_on, items, attachment, currency, comments, ec_status, extra
update_billwriteChange only the fields given. items adds lines; an item with id changes that line, and with id and delete: true removes itid, bill fields
delete_billwrite, destructiveDelete a billid

ec_status is UK/Non-EC (default), EC Goods, EC Services or Reverse Charge. extra takes any other bill field by FreeAgent’s name, such as {"recurring": "Monthly"}.

Bill lines

Each item of a bill’s items:

FieldMeaning
categoryExpense category as a nominal code, such as 285 (Accommodation and Meals). Required
total_valueThe line’s total including VAT, such as 120.00
total_value_ex_taxOr the line’s total before VAT
description, quantity, project_id
unit-no unit-, Hours, Days, Weeks, Months, Years, Products, Services, Training or Stock
sales_tax_rateVAT percentage, such as 20. Default: from the category
sales_tax_statusTAXABLE, EXEMPT or OUT_OF_SCOPE
manual_sales_tax_amountAn exact VAT amount, overriding the rate
id, deleteOn update: the line to change, and delete: true to remove it

Expenses and mileage

ToolKindWhat it doesKey parameters
list_expensesreadExpense claims and mileage with user, category, date, description and gross_value (negative is money owed to the claimant)view: recent or recurring (default all); project_id, from_date, to_date, updated_since, page, per_page
get_expensereadOne expense or mileage claim in full: user, category, date, amounts, VAT, receipt and rebillingid
create_expensewriteRecord an expense someone paid personally: category, date, description and the amount spent including VAT, optionally with the receiptexpense fields (below)
create_mileage_claimwriteClaim business mileage at HMRC’s approved rates. FreeAgent works out the amountdated_on, description, mileage, and the fields below
update_expensewriteChange only the fields given. amount is what was spent, positiveid, expense fields
delete_expensewrite, destructiveDelete an expenseid

Expense fields

FieldMeaning
amountWhat was spent, including VAT, as a positive amount such as 42.50. The server stores it with FreeAgent’s sign
refundtrue when the claimant paid money back to the company instead
categoryExpense category as a nominal code, such as 285; see list_categories
dated_on, description, receipt_reference
user_idWho paid and is owed it. Default on create: the signed-in user
currencyISO 4217 code when not the company’s currency
sales_tax_rateVAT percentage. Default: from the category
manual_sales_tax_amountAn exact reclaimable VAT amount, overriding the rate
project_id, rebill_typeA project to rebill it to, and how: cost, markup or price
attachmentThe receipt
extraAny other expense field by FreeAgent’s name

Mileage fields

FieldMeaning
dated_on, descriptionRequired. The description says where and why, such as “Leeds to Manchester, client meeting”
mileageRequired. Distance in the company’s mileage units (miles unless set to kilometres)
vehicle_typeCar (default), Motorcycle or Bicycle
engine_typePetrol (default), Diesel, LPG, Electric, Electric (Home charger) or Electric (Public charger)
engine_sizeFrom FreeAgent’s mileage settings, such as “Up to 1400cc”; needed for VAT on fuel
have_vat_receiptWhether there is a VAT receipt for the fuel
reclaimReclaim at the HMRC approved rate. Default: true; false only rebills it
user_idWho drove. Default: the signed-in user
project_id

Attachments

attachment on bills, expenses and bank explanations:

FieldMeaning
file_nameRequired, such as receipt.pdf
data_base64Required. The file, base64-encoded
content_typeapplication/pdf, image/png, image/jpeg or image/gif. Default: from file_name
description

Requests to the server are limited to 1 MiB in all, so a file over about 700 KB is refused before it reaches FreeAgent.

Models cannot pass a file shared in a chat to a tool, so for those, and for anything over about 700 KB, use an upload link. Made without a target, the link holds the file for 30 minutes so the model can read it, fill in the expense, bill or explanation from it, and attach it to what it made:

ToolKindWhat it doesKey parameters
create_upload_linkwriteA single-use link, valid for 30 minutes, where the person picks a PDF, PNG, JPEG or GIF of up to 5 MB. With target and id the server attaches it in FreeAgent as them; an expense or bill holds one file, and when it already has one, replaces names it, because the upload replaces it. Without them the file is held for the modeltarget (expense, bill or bank_transaction_explanation) and id, or neither
get_upload_statusreadwaiting (with the last error, if a try failed), uploading, received (held for the model) or attachedupload_url
get_uploaded_filereadThe held file: a photo as an image the model can read, a PDF as an embedded fileupload_url
get_attachmentreadA file already attached in FreeAgent, such as an expense’s receipt, by the attachment id the item shows. The server downloads it from FreeAgent’s signed storage link, which lasts 30 seconds, without sending a FreeAgent tokenid
attach_filewriteAttach a held file (upload_url), or one the client can read itself as base64target, id, and upload_url or file_name and data_base64; description