The FreeAgent connector lets your AI agent act in each user's FreeAgent account. Each user signs in to FreeAgent once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 117 tools.
- Tools
- 117
- What they doRead · write · destructive
- 57 · 46 · 1457 read46 write14 destructive
- Users sign in with
- OAuth
- OAuth app
- Your own FreeAgent app
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the FreeAgent connection
In AgentKit > Connections, create a FreeAgent connection and copy its redirect URI. The name you give it is the
connection_nameyour code passes. See Configure connections.Register an OAuth app
FreeAgent connections use your own OAuth app. Register one with FreeAgent and add the redirect URI you copied.
Then enter the app's Client ID and Client Secret on the FreeAgent connection.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'freeagent'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize FreeAgent:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'freeagent_accounting_transactions_list',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "freeagent"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize FreeAgent:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="freeagent_accounting_transactions_list",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolfreeagent_accounting_transaction_getGet one FreeAgent accounting transaction by ID.Read-onlyGet Accounting Transaction
Get one FreeAgent accounting transaction by ID. Returns its date, description, category, nominal code, debit value, source item and foreign currency data. Use freeagent_accounting_transactions_list to find the ID.
Inputs
transaction_idstringrequired- Numeric ID of the accounting transaction: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/accounting/transactions/123 the ID is 123). Get it from freeagent_accounting_transactions_list.
freeagent_accounting_transactions_listList FreeAgent's underlying accounting (ledger) transactions for a period, optionally for one nominal code.Read-onlyList Accounting Transactions
List FreeAgent's underlying accounting (ledger) transactions for a period, optionally for one nominal code. Returns each transaction's url, date, description, category, nominal code, debit value and source item. The period must be 12 months or less, or within one accounting year; with no dates it covers the current accounting year to date.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
nominal_codestring- Only return transactions for this category nominal code. Example: 285.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
freeagent_attachment_getGet one FreeAgent attachment (for example a receipt) by ID.Read-onlyGet Attachment
Get one FreeAgent attachment (for example a receipt) by ID. Returns its file name, content type, size, description and temporary content_src download URLs with their expiry. Find attachment URLs on expenses, bills and bank transaction explanations.
Inputs
attachment_idstringrequired- Numeric ID of the attachment: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/attachments/123 the ID is 123). Get it from the attachment field of an expense, bill or bank transaction explanation.
freeagent_balance_sheet_getGet the FreeAgent balance sheet as at a date.Read-onlyGet Balance Sheet
Get the FreeAgent balance sheet as at a date. Returns capital assets, current assets and liabilities, net current assets, total assets and owner's equity. With no date it is as at today from the start of the current accounting period.
Inputs
as_at_datestring- Date to report the balance sheet as at in YYYY-MM-DD format. Example: 2026-03-31.
freeagent_bank_account_getGet one FreeAgent bank account by ID.Read-onlyGet Bank Account
Get one FreeAgent bank account by ID. Returns the account's type, name, currency, balances, bank details and status. Use freeagent_bank_accounts_list to find the ID.
Inputs
bank_account_idstringrequired- Numeric ID of the bank account: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_accounts/123 the ID is 123). Get it from freeagent_bank_accounts_list.
freeagent_bank_accounts_listList the company's FreeAgent bank, credit card and PayPal accounts.Read-onlyList Bank Accounts
List the company's FreeAgent bank, credit card and PayPal accounts. Returns each account's url, type, name, currency, current balance and latest activity date. Use this to find a bank account URL before listing transactions or creating explanations.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
viewstring- Filter by view. One of: standard_bank_accounts, credit_card_accounts, paypal_accounts.one of
standard_bank_accountscredit_card_accountspaypal_accounts
freeagent_bank_transaction_explanation_getGet one FreeAgent bank transaction explanation by ID.Read-onlyGet Bank Transaction Explanation
Get one FreeAgent bank transaction explanation by ID. Returns its type, date, amount, category, sales tax, description, lock state and linked records. Use freeagent_bank_transaction_explanations_list to find the ID.
Inputs
bank_transaction_explanation_idstringrequired- Numeric ID of the bank transaction explanation: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_transaction_explanations/123 the ID is 123). Get it from freeagent_bank_transaction_explanations_list.
freeagent_bank_transaction_explanations_listList the explanations recorded against transactions in one FreeAgent bank account, filtered by date range or update time.Read-onlyList Bank Transaction Explanations
List the explanations recorded against transactions in one FreeAgent bank account, filtered by date range or update time. Returns each explanation's url, type, date, amount, category, description and linked invoice, bill or user. Use freeagent_bank_transactions_list to see transactions and how much is still unexplained. Requires a bank account URL from freeagent_bank_accounts_list.
Inputs
bank_accountstringrequired- FreeAgent URL of the bank account, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
freeagent_bank_transaction_getGet one FreeAgent bank transaction by ID.Read-onlyGet Bank Transaction
Get one FreeAgent bank transaction by ID. Returns its bank account, date, amount, description, unexplained amount and bank_transaction_explanations. Use freeagent_bank_transactions_list to find the ID.
Inputs
bank_transaction_idstringrequired- Numeric ID of the bank transaction: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_transactions/123 the ID is 123). Get it from freeagent_bank_transactions_list.
freeagent_bank_transactions_listList bank transactions in one FreeAgent bank account, filtered by date range, explained status or update time.Read-onlyList Bank Transactions
List bank transactions in one FreeAgent bank account, filtered by date range, explained status or update time. Returns each transaction's url, date, amount, description, unexplained amount and its explanations. Use view unexplained to find transactions that still need explaining; use freeagent_bank_transaction_explanation_create to explain one. Requires a bank account URL from freeagent_bank_accounts_list.
Inputs
bank_accountstringrequired- FreeAgent URL of the bank account, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
last_uploadedboolean- true to return only transactions from the most recently uploaded statement.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: all, unexplained, explained, manual, imported, marked_for_review. Defaults to all.one of
allunexplainedexplainedmanualimportedmarked_for_review
freeagent_bill_getGet one FreeAgent bill by ID, including its items.Read-onlyGet Bill
Get one FreeAgent bill by ID, including its items. Returns the bill's contact, reference, dates, totals, status and bill_items. Use freeagent_bills_list to find the ID.
Inputs
bill_idstringrequired- Numeric ID of the bill: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bills/123 the ID is 123). Get it from freeagent_bills_list.
freeagent_bills_listList FreeAgent supplier bills, filtered by status view, date range, contact, project or update time.Read-onlyList Bills
List FreeAgent supplier bills, filtered by status view, date range, contact, project or update time. Returns each bill's url, contact, reference, dates, totals, due value and status. Use this to see what the company owes suppliers; use freeagent_bill_get for one bill with its items.
Inputs
contactstring- FreeAgent URL of the supplier contact whose bills to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
nested_bill_itemsboolean- true to include each bill's items in the list.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose bills to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: all, open, overdue, open_or_overdue, open_or_overdue_payments, open_or_overdue_refunds, paid, recurring, hire_purchase, cis. Defaults to all.one of
allopenoverdueopen_or_overdueopen_or_overdue_paymentsopen_or_overdue_refundspaidrecurringhire_purchasecis
freeagent_cashflow_getGet FreeAgent's historic cashflow summary for a date range.Read-onlyGet Cashflow
Get FreeAgent's historic cashflow summary for a date range. Returns money in, money out and balance totals, with monthly breakdowns. Projected cashflow is not returned, so future dates give totals of 0.
Inputs
from_datestringrequired- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
to_datestringrequired- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
freeagent_categories_listList the company's FreeAgent accounting categories, grouped into admin expenses, cost of sales, income and general.Read-onlyList Categories
List the company's FreeAgent accounting categories, grouped into admin expenses, cost of sales, income and general. Returns each category's url, description, nominal code and tax settings. Use this to find category URLs for bills, expenses, invoice items and bank explanations.
Inputs
sub_accountsboolean- true to list sub accounts (such as 750-1 for a specific bank account) in place of their top-level accounts.
freeagent_category_getGet one FreeAgent accounting category by its nominal code.Read-onlyGet Category
Get one FreeAgent accounting category by its nominal code. Returns the category's url, description, nominal code, group and tax settings. Use freeagent_categories_list to find nominal codes.
Inputs
nominal_codestringrequired- Nominal code of the category, e.g. 285 (also the number at the end of its FreeAgent URL). Get it from freeagent_categories_list.
freeagent_company_business_categories_listList the business categories FreeAgent accepts for a company's business_category setting.Read-onlyList Business Categories
List the business categories FreeAgent accepts for a company's business_category setting. Returns an array of business category names. Use this only to look up valid business category values.
Inputs
This tool takes no inputs.
freeagent_company_getGet the FreeAgent company's details: name, type, currency, address, accounting dates, and sales tax settings.Read-onlyGet Company
Get the FreeAgent company's details: name, type, currency, address, accounting dates, and sales tax settings. Returns the company object. Use this to learn the company's native currency, sales tax rates and accounting year before creating records.
Inputs
This tool takes no inputs.
freeagent_company_tax_timeline_getGet the company's upcoming tax events, such as VAT returns, corporation tax and payment deadlines.Read-onlyGet Tax Timeline
Get the company's upcoming tax events, such as VAT returns, corporation tax and payment deadlines. Returns timeline items with description, nature, date and amount. Use this to see what tax filings and payments are due next. Requires the Tax, Accounting & Users permission.
Inputs
This tool takes no inputs.
freeagent_contact_getGet one FreeAgent contact by ID.Read-onlyGet Contact
Get one FreeAgent contact by ID. Returns the contact's name, organisation, emails, phone, address, tax settings, balance and status. Use freeagent_contacts_list to find the ID.
Inputs
contact_idstringrequired- Numeric ID of the contact: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/contacts/123 the ID is 123). Get it from freeagent_contacts_list.
freeagent_contacts_listList contacts (clients and suppliers) in FreeAgent, filtered by view and sorted by name or date.Read-onlyList Contacts
List contacts (clients and suppliers) in FreeAgent, filtered by view and sorted by name or date. Returns each contact's url, name, organisation, email, address, balance and status. Use this to find a contact's URL before creating invoices, bills, estimates or projects; use freeagent_contact_get for one contact.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
sortstring- Sort order. One of: name, created_at, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to name.one of
namecreated_atupdated_at-name-created_at-updated_at updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: active, all, clients, suppliers, active_projects, completed_projects, open_clients, open_suppliers, hidden. Defaults to active.one of
activeallclientssuppliersactive_projectscompleted_projectsopen_clientsopen_suppliershidden
freeagent_credit_note_getGet one FreeAgent credit note by ID, including its line items.Read-onlyGet Credit Note
Get one FreeAgent credit note by ID, including its line items. Returns the credit note's contact, reference, dates, totals, status and credit_note_items. Use freeagent_credit_notes_list to find the ID.
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
freeagent_credit_note_pdf_getGet a FreeAgent credit note as a PDF.Read-onlyGet Credit Note PDF
Get a FreeAgent credit note as a PDF. Returns JSON with pdf.content holding the base64-encoded PDF file. Use freeagent_credit_note_get for the data instead of the document. Requires a credit_note_id from freeagent_credit_notes_list.
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
freeagent_credit_note_reconciliation_getGet one FreeAgent credit note reconciliation by ID.Read-onlyGet Credit Note Reconciliation
Get one FreeAgent credit note reconciliation by ID. Returns the invoice and credit note URLs, the amount reconciled, the date and currency. Use freeagent_credit_note_reconciliations_list to find the ID.
Inputs
credit_note_reconciliation_idstringrequired- Numeric ID of the credit note reconciliation: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_note_reconciliations/123 the ID is 123). Get it from freeagent_credit_note_reconciliations_list.
freeagent_credit_note_reconciliations_listList FreeAgent credit note reconciliations — credit notes applied against invoices — filtered by date or update time.Read-onlyList Credit Note Reconciliations
List FreeAgent credit note reconciliations — credit notes applied against invoices — filtered by date or update time. Returns each reconciliation's url, invoice, credit note, amount, date and currency. Use this to see which credit notes have been applied to which invoices.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
freeagent_credit_notes_listList FreeAgent credit notes, filtered by status view, contact, project or update time.Read-onlyList Credit Notes
List FreeAgent credit notes, filtered by status view, contact, project or update time. Returns each credit note's url, contact, reference, dates, totals, refunded and due values, and status. Use this to browse credit notes; use freeagent_credit_note_get for one with its items.
Inputs
contactstring- FreeAgent URL of the contact whose credit notes to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
nested_credit_note_itemsboolean- true to include each credit note's line items in the list.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose credit notes to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
sortstring- Sort order. One of: created_at, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to created_at.one of
created_atupdated_at-created_at-updated_at updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by status view: all (default), recent_open_or_overdue, open, overdue, open_or_overdue, draft, refunded, or last_N_months (for example last_6_months).
freeagent_email_addresses_listList the verified sender email addresses FreeAgent can send invoices, estimates and credit notes from.Read-onlyList Sender Email Addresses
List the verified sender email addresses FreeAgent can send invoices, estimates and credit notes from. Returns an array of addresses formatted as 'Name <email>'. Use this to pick a valid from value for the send_email tools.
Inputs
This tool takes no inputs.
freeagent_estimate_getGet one FreeAgent estimate by ID, including its line items.Read-onlyGet Estimate
Get one FreeAgent estimate by ID, including its line items. Returns the estimate's contact, reference, type, dates, totals, status and estimate_items. Use freeagent_estimates_list to find the ID.
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_pdf_getGet a FreeAgent estimate as a PDF.Read-onlyGet Estimate PDF
Get a FreeAgent estimate as a PDF. Returns JSON with pdf.content holding the base64-encoded PDF file. Use freeagent_estimate_get for the estimate data instead of the document. Requires an estimate_id from freeagent_estimates_list.
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimates_listList FreeAgent estimates, quotes and proposals, filtered by status view, date range, contact, project or invoice.Read-onlyList Estimates
List FreeAgent estimates, quotes and proposals, filtered by status view, date range, contact, project or invoice. Returns each estimate's url, contact, reference, type, dates, totals and status. Use this to browse estimates; use freeagent_estimate_get for one estimate with its items.
Inputs
contactstring- FreeAgent URL of the contact whose estimates to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
invoicestring- FreeAgent URL of the invoice whose estimates to list, as returned in the `url` field by freeagent_invoices_list. Example: https://api.freeagent.com/v2/invoices/123.
nested_estimate_itemsboolean- true to include each estimate's line items in the list.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose estimates to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: all, recent, draft, non_draft, sent, approved, rejected, invoiced. Defaults to all.one of
allrecentdraftnon_draftsentapprovedrejectedinvoiced
freeagent_expense_getGet one FreeAgent expense by ID.Read-onlyGet Expense
Get one FreeAgent expense by ID. Returns the expense's user, category, date, amounts, sales tax, rebilling and mileage details. Use freeagent_expenses_list to find the ID.
Inputs
expense_idstringrequired- Numeric ID of the expense: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/expenses/123 the ID is 123). Get it from freeagent_expenses_list.
freeagent_expense_mileage_settings_getGet the company's mileage claim settings, including valid engine types and sizes by date and the mileage rates.Read-onlyGet Mileage Settings
Get the company's mileage claim settings, including valid engine types and sizes by date and the mileage rates. Returns the mileage settings object. Use this before freeagent_expense_create for a mileage claim to pick a valid engine_type and engine_size.
Inputs
This tool takes no inputs.
freeagent_expenses_listList FreeAgent expense claims, filtered by view, date range, project or update time.Read-onlyList Expenses
List FreeAgent expense claims, filtered by view, date range, project or update time. Returns each expense's url, user, category, date, amounts, sales tax and description. Use this to review claims; use freeagent_expense_get for one expense.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose expenses to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: recent, recurring.one of
recentrecurring
freeagent_invoice_getGet one FreeAgent invoice by ID, including its line items.Read-onlyGet Invoice
Get one FreeAgent invoice by ID, including its line items. Returns the invoice's contact, reference, dates, totals, status, payment methods and invoice_items. Use freeagent_invoices_list to find the ID; use freeagent_invoice_pdf_get for the PDF.
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_pdf_getGet a FreeAgent invoice as a PDF.Read-onlyGet Invoice PDF
Get a FreeAgent invoice as a PDF. Returns JSON with pdf.content holding the base64-encoded PDF file. Use freeagent_invoice_get for the invoice data instead of the document. Requires an invoice_id from freeagent_invoices_list.
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_timeline_getGet the company's invoice timeline of recent invoice events such as payments received.Read-onlyGet Invoice Timeline
Get the company's invoice timeline of recent invoice events such as payments received. Returns timeline items with reference, summary, description, date and amount. Use this for a recent activity feed; use freeagent_invoices_list to list invoices.
Inputs
This tool takes no inputs.
freeagent_invoices_listList FreeAgent sales invoices, filtered by status view, contact, project or update time.Read-onlyList Invoices
List FreeAgent sales invoices, filtered by status view, contact, project or update time. Returns each invoice's url, contact, reference, dates, currency, totals, paid and due values, and status. Use this to browse or find invoices; use freeagent_invoice_get for one invoice with its items.
Inputs
contactstring- FreeAgent URL of the contact whose invoices to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
nested_invoice_itemsboolean- true to include each invoice's line items in the list.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose invoices to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
sortstring- Sort order. One of: created_at, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to created_at.one of
created_atupdated_at-created_at-updated_at updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by status view: all (default), recent_open_or_overdue, open, overdue, open_or_overdue, draft, paid, scheduled_to_email, thank_you_emails, reminder_emails, or last_N_months (for example last_3_months).
freeagent_journal_set_getGet one FreeAgent journal set by ID, with its journal entries.Read-onlyGet Journal Set
Get one FreeAgent journal set by ID, with its journal entries. Returns the set's date, description, tag and journal_entries (category and debit value). Use freeagent_journal_sets_list to find the ID.
Inputs
journal_set_idstringrequired- Numeric ID of the journal set: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/journal_sets/123 the ID is 123). Get it from freeagent_journal_sets_list.
freeagent_journal_sets_listList FreeAgent journal sets (balanced groups of manual journal entries), filtered by date range, tag or update time.Read-onlyList Journal Sets
List FreeAgent journal sets (balanced groups of manual journal entries), filtered by date range, tag or update time. Returns each journal set's url, date, description and tag. Use freeagent_journal_set_get for the entries in one set.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
tagstring- Only return journal sets with this tag.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
freeagent_note_getGet one FreeAgent note by ID.Read-onlyGet Note
Get one FreeAgent note by ID. Returns the note's text, parent contact or project URL, author and timestamps. Use freeagent_notes_list to find the ID.
Inputs
note_idstringrequired- Numeric ID of the note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/notes/123 the ID is 123). Get it from freeagent_notes_list.
freeagent_notes_listList the notes attached to one FreeAgent contact or project.Read-onlyList Notes
List the notes attached to one FreeAgent contact or project. Returns each note's url, text, parent URL, author and timestamps. Give exactly one of contact or project.
Inputs
contactstring- FreeAgent URL of the contact whose notes to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123. Give this or project.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose notes to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123. Give this or contact.
freeagent_price_list_item_getGet one FreeAgent price list item by ID.Read-onlyGet Price List Item
Get one FreeAgent price list item by ID. Returns its code, description, item type, quantity, price, tax settings and category. Use freeagent_price_list_items_list to find the ID.
Inputs
price_list_item_idstringrequired- Numeric ID of the price list item: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/price_list_items/123 the ID is 123). Get it from freeagent_price_list_items_list.
freeagent_price_list_items_listList the saved products and services in the FreeAgent price list.Read-onlyList Price List Items
List the saved products and services in the FreeAgent price list. Returns each item's url, code, description, item type, quantity, price and tax settings. Use this to reuse standard prices on invoices and estimates.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
sortstring- Sort order. One of: created_at, code, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to created_at.one of
created_atcodeupdated_at-created_at-code-updated_at
freeagent_profit_and_loss_summary_getGet the FreeAgent profit and loss summary for a date range or accounting period.Read-onlyGet Profit and Loss
Get the FreeAgent profit and loss summary for a date range or accounting period. Returns income, expenses, operating profit, deductions and retained profit in the native currency. With no parameters it covers the current accounting year to date; the range must be 12 months or less or within one accounting year.
Inputs
accounting_periodstring- Annual accounting period as start/end years, e.g. 2025/26. Use instead of from_date and to_date.
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
freeagent_project_getGet one FreeAgent project by ID.Read-onlyGet Project
Get one FreeAgent project by ID. Returns the project's contact, name, status, currency, budget, billing settings, dates and whether it can be deleted. Use freeagent_projects_list to find the ID.
Inputs
project_idstringrequired- Numeric ID of the project: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/projects/123 the ID is 123). Get it from freeagent_projects_list.
freeagent_projects_listList FreeAgent projects, filtered by status view or contact and sorted by name, contact or date.Read-onlyList Projects
List FreeAgent projects, filtered by status view or contact and sorted by name, contact or date. Returns each project's url, contact, name, status, currency, budget and billing rate. Use this to find a project URL for invoices, tasks and timeslips; use freeagent_project_get for one project.
Inputs
contactstring- FreeAgent URL of the contact whose projects to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
nestedboolean- true to return each project's full contact details instead of a contact URL.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
sortstring- Sort order. One of: name, contact_name, contact_display_name, created_at, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to name.one of
namecontact_namecontact_display_namecreated_atupdated_at-name-contact_name-contact_display_name-created_at-updated_at viewstring- Filter by view. One of: active, completed, cancelled, hidden.one of
activecompletedcancelledhidden
freeagent_recurring_invoice_getGet one FreeAgent recurring invoice template by ID.Read-onlyGet Recurring Invoice
Get one FreeAgent recurring invoice template by ID. Returns its contact, frequency, recurring status, end date, next recurrence date and line items. Use freeagent_recurring_invoices_list to find the ID.
Inputs
recurring_invoice_idstringrequired- Numeric ID of the recurring invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/recurring_invoices/123 the ID is 123). Get it from freeagent_recurring_invoices_list.
freeagent_recurring_invoices_listList FreeAgent recurring invoice templates, filtered by status or contact.Read-onlyList Recurring Invoices
List FreeAgent recurring invoice templates, filtered by status or contact. Returns each recurring invoice's url, contact, frequency, recurring status, next recurrence date and invoice details. Use this to see scheduled repeat billing; use freeagent_invoices_list for issued invoices.
Inputs
contactstring- FreeAgent URL of the contact whose recurring invoices to list, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
viewstring- Filter by view. One of: draft, active, inactive.one of
draftactiveinactive
freeagent_stock_item_getGet one FreeAgent stock item by ID.Read-onlyGet Stock Item
Get one FreeAgent stock item by ID. Returns its description, opening quantity and balance, cost-of-sale category and stock on hand. Use freeagent_stock_items_list to find the ID.
Inputs
stock_item_idstringrequired- Numeric ID of the stock item: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/stock_items/123 the ID is 123). Get it from freeagent_stock_items_list.
freeagent_stock_items_listList the stock items defined in FreeAgent.Read-onlyList Stock Items
List the stock items defined in FreeAgent. Returns each item's url, description, opening quantity and balance, cost-of-sale category and stock on hand. Use this to find a stock item URL for invoices, bills or price list items.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
sortstring- Sort order. One of: created_at, description, updated_at — prefix with a hyphen (e.g. -updated_at) for descending order. Defaults to created_at.one of
created_atdescriptionupdated_at-created_at-description-updated_at
freeagent_task_getGet one FreeAgent task by ID.Read-onlyGet Task
Get one FreeAgent task by ID. Returns the task's project, name, currency, billable flag, billing rate, status and whether it can be deleted. Use freeagent_tasks_list to find the ID.
Inputs
task_idstringrequired- Numeric ID of the task: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/tasks/123 the ID is 123). Get it from freeagent_tasks_list.
freeagent_tasks_listList FreeAgent project tasks, filtered by status view, project or update time.Read-onlyList Tasks
List FreeAgent project tasks, filtered by status view, project or update time. Returns each task's url, project, name, billable flag, billing rate and status. Use this to find a task URL for timeslips; use freeagent_task_get for one task.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose tasks to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
sortstring- Sort order: name (default), project, billing_rate, created_at or updated_at.one of
nameprojectbilling_ratecreated_atupdated_at updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
viewstring- Filter by view. One of: all, active, completed, hidden. Defaults to all.one of
allactivecompletedhidden
freeagent_timeslip_getGet one FreeAgent timeslip by ID.Read-onlyGet Timeslip
Get one FreeAgent timeslip by ID. Returns its user, project, task, date, hours, comment, billing invoice and any running timer. Use freeagent_timeslips_list to find the ID.
Inputs
timeslip_idstringrequired- Numeric ID of the timeslip: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/timeslips/123 the ID is 123). Get it from freeagent_timeslips_list.
freeagent_timeslips_listList FreeAgent timeslips (logged time), filtered by date range, user, task, project, billing state or update time.Read-onlyList Timeslips
List FreeAgent timeslips (logged time), filtered by date range, user, task, project, billing state or update time. Returns each timeslip's url, user, project, task, date, hours, comment and billing invoice. Use view unbilled to find time not yet invoiced; use freeagent_timeslip_get for one timeslip.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
nestedboolean- true to return the user, project and task as nested objects instead of URLs.
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
projectstring- FreeAgent URL of the project whose timeslips to list, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
taskstring- FreeAgent URL of the task whose timeslips to list, as returned in the `url` field by freeagent_tasks_list. Example: https://api.freeagent.com/v2/tasks/123.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
updated_sincestring- Only return records updated on or after this ISO 8601 timestamp. Example: 2026-01-01T00:00:00.000Z.
userstring- FreeAgent URL of the user whose timeslips to list, as returned in the `url` field by freeagent_users_list. Example: https://api.freeagent.com/v2/users/123.
viewstring- Filter by view. One of: all, unbilled, running. Defaults to all.one of
allunbilledrunning
freeagent_trial_balance_summary_getGet the FreeAgent trial balance summary for a period.Read-onlyGet Trial Balance
Get the FreeAgent trial balance summary for a period. Returns each category's nominal code, display nominal code, name and total. With no dates it is for today; with only to_date it runs from the start of that accounting period.
Inputs
from_datestring- Start of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-01-01.
to_datestring- End of the date range (inclusive) in YYYY-MM-DD format. Example: 2026-03-31.
freeagent_user_getGet one FreeAgent user by ID.Read-onlyGet User
Get one FreeAgent user by ID. Returns the user's name, email, role, permission level and payroll profile summary. Use freeagent_users_list to find the ID; use freeagent_user_me_get for the authorized user.
Inputs
user_idstringrequired- Numeric ID of the user: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/users/123 the ID is 123). Get it from freeagent_users_list.
freeagent_user_me_getGet the profile of the FreeAgent user who authorized this connection.Read-onlyGet Current User
Get the profile of the FreeAgent user who authorized this connection. Returns the user's url, name, email, role and permission level. Use this to find the current user's URL for expenses and timeslips; use freeagent_user_get for another user.
Inputs
This tool takes no inputs.
freeagent_users_listList the users in the FreeAgent company, optionally filtered to staff or advisors.Read-onlyList Users
List the users in the FreeAgent company, optionally filtered to staff or advisors. Returns each user's url, name, email, role and permission level. Use this to find a user's URL for expenses, timeslips or explanations. Requires the Tax, Accounting & Users permission.
Inputs
pageinteger- Page number of results to return, starting at 1. FreeAgent returns 25 items per page by default; the response's Link header points to the next page.
per_pageinteger- Number of items per page, from 1 to 100. Defaults to 25.
viewstring- Filter by view. One of: all, staff, active_staff, advisors, active_advisors. Defaults to all.one of
allstaffactive_staffadvisorsactive_advisors
freeagent_bank_account_createAdd a bank, credit card or e-commerce account to FreeAgent.WriteCreate Bank Account
Add a bank, credit card or e-commerce account to FreeAgent. Returns the new bank account, including its url. Use freeagent_bank_account_update to change an existing account.
Inputs
namestringrequired- Account name shown in FreeAgent.
opening_balancenumberrequired- Account balance at the FreeAgent start date; use 0 for accounts opened after that date. Example: 0.
account_numberstring- Account number. For credit card accounts only the last four digits are needed.
bank_namestring- Name of the bank.
bicstring- Bank Identifier Code (SWIFT).
currencystring- Accounting currency of the account (ISO 4217). Defaults to the native currency and cannot change once the account has transactions. Example: GBP.
ibanstring- International Bank Account Number.
is_personalboolean- true for a personal account, false for a business account.
secondary_sort_codestring- Secondary sort code, only if the account has two.
sort_codestring- Sort code or routing number.
typestring- Account type: StandardBankAccount (default), CreditCardAccount or EcommerceAccount.one of
StandardBankAccountCreditCardAccountEcommerceAccount
freeagent_bank_account_updateUpdate a FreeAgent bank account's name, bank details, currency or opening balance.WriteUpdate Bank Account
Update a FreeAgent bank account's name, bank details, currency or opening balance. Returns the updated bank account. Only the fields you pass are changed. Requires a bank_account_id from freeagent_bank_accounts_list.
- Idempotent
Inputs
bank_account_idstringrequired- Numeric ID of the bank account: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_accounts/123 the ID is 123). Get it from freeagent_bank_accounts_list.
account_numberstring- Account number. For credit card accounts only the last four digits are needed.
bank_namestring- Name of the bank.
bicstring- Bank Identifier Code (SWIFT).
currencystring- Accounting currency of the account (ISO 4217). Defaults to the native currency and cannot change once the account has transactions. Example: GBP.
ibanstring- International Bank Account Number.
is_personalboolean- true for a personal account, false for a business account.
namestring- Account name shown in FreeAgent.
opening_balancenumber- Account balance at the FreeAgent start date; use 0 for accounts opened after that date. Example: 0.
secondary_sort_codestring- Secondary sort code, only if the account has two.
sort_codestring- Sort code or routing number.
freeagent_bank_statement_uploadImport bank transactions into a FreeAgent bank account from a list of statement lines (JSON, not a file).WriteUpload Bank Statement
Import bank transactions into a FreeAgent bank account from a list of statement lines (JSON, not a file). Returns 200 when the upload is accepted; check freeagent_bank_transactions_list to confirm the import. Transactions matching an existing one on the same date, amount and description are skipped, so send a whole day's lines together. Requires a bank account URL from freeagent_bank_accounts_list.
Inputs
bank_accountstringrequired- FreeAgent URL of the bank account, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
statementarrayrequired- Statement lines to import. Each line needs dated_on (YYYY-MM-DD) and usually an amount (negative for money out) and description; optionally a unique fitid and a transaction_type such as CREDIT, DEBIT, FEE, PAYMENT, DIRECTDEP or OTHER (default). Example: [{"dated_on": "2026-01-05", "amount": -100, "description": "Local Council", "fitid": "049b807d"}]
freeagent_bank_transaction_explanation_createExplain a FreeAgent bank transaction as a categorised payment or receipt, an invoice or bill payment, a user payment or a transfer — or create a new transaction with its explanation.WriteCreate Bank Transaction Explanation
Explain a FreeAgent bank transaction as a categorised payment or receipt, an invoice or bill payment, a user payment or a transfer — or create a new transaction with its explanation. Returns the new explanation. Set category for payments and receipts; set paid_invoice, paid_bill, paid_user or transfer_bank_account instead for those types. Requires a bank_transaction URL from freeagent_bank_transactions_list, or a bank_account URL.
Inputs
dated_onstringrequired- Date of the explanation in YYYY-MM-DD format. Example: 2026-01-31.
gross_valuenumberrequired- Amount explained, in the bank account's currency. Negative for money out (payments, bill payments), positive for money in (receipts, invoice payments). FreeAgent rejects a sign that does not match the explanation type. Example: -120.
bank_accountstring- FreeAgent URL of the bank account in which to create a new transaction together with its explanation, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123. Give this or bank_transaction.
bank_transactionstring- FreeAgent URL of the existing bank transaction to explain, as returned in the `url` field by freeagent_bank_transactions_list. Example: https://api.freeagent.com/v2/bank_transactions/123. Give this or bank_account.
categorystring- FreeAgent URL of the accounting category that explains the transaction, as returned in the `url` field by freeagent_categories_list. Example: https://api.freeagent.com/v2/categories/123. Not needed when paying an invoice or bill or transferring between accounts.
cheque_numberstring- Cheque number, if paid by cheque.
descriptionstring- Description of the transaction. Not required for transfers or invoice receipts.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS foreign_currency_valuenumber- For a foreign-currency invoice or bill: the gross_value expressed in that foreign currency. Example: -140.
marked_for_reviewboolean- true to mark the explanation as awaiting review.
paid_billstring- FreeAgent URL of the bill this payment settles or refunds, as returned in the `url` field by freeagent_bills_list. Example: https://api.freeagent.com/v2/bills/123.
paid_invoicestring- FreeAgent URL of the invoice this payment settles (or credit note it refunds), as returned in the `url` field by freeagent_invoices_list. Example: https://api.freeagent.com/v2/invoices/123.
paid_userstring- FreeAgent URL of the user money was paid to or received from, as returned in the `url` field by freeagent_users_list. Example: https://api.freeagent.com/v2/users/123. Omit category for a smart user payment.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
projectstring- FreeAgent URL of the project the payment is linked or rebilled to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice receipt_referencestring- Receipt reference for a payment or refund.
sales_tax_ratenumber- Sales tax (VAT) rate as a percentage, one of the company's standard rates. Example: 20.
sales_tax_statusstring- Mark the item as TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax instead of giving a rate.one of
TAXABLEEXEMPTOUT_OF_SCOPE stock_altering_quantityinteger- For stock purchases or sales: how many units were bought or sold. Example: 10.
stock_itemstring- FreeAgent URL of the stock item purchased or sold, as returned in the `url` field by freeagent_stock_items_list. Example: https://api.freeagent.com/v2/stock_items/123.
transfer_bank_accountstring- FreeAgent URL of the other bank account in a transfer between accounts, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
freeagent_bank_transaction_explanation_updateUpdate a FreeAgent bank transaction explanation.WriteUpdate Bank Transaction Explanation
Update a FreeAgent bank transaction explanation. Returns the updated explanation. Only the fields you pass are changed; locked attributes cannot be modified. Requires a bank_transaction_explanation_id from freeagent_bank_transaction_explanations_list.
- Idempotent
Inputs
bank_transaction_explanation_idstringrequired- Numeric ID of the bank transaction explanation: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_transaction_explanations/123 the ID is 123). Get it from freeagent_bank_transaction_explanations_list.
categorystring- FreeAgent URL of the accounting category that explains the transaction, as returned in the `url` field by freeagent_categories_list. Example: https://api.freeagent.com/v2/categories/123. Not needed when paying an invoice or bill or transferring between accounts.
cheque_numberstring- Cheque number, if paid by cheque.
dated_onstring- Date of the explanation in YYYY-MM-DD format. Example: 2026-01-31.
descriptionstring- Description of the transaction. Not required for transfers or invoice receipts.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS foreign_currency_valuenumber- For a foreign-currency invoice or bill: the gross_value expressed in that foreign currency. Example: -140.
gross_valuenumber- Amount explained, in the bank account's currency. Negative for money out (payments, bill payments), positive for money in (receipts, invoice payments). FreeAgent rejects a sign that does not match the explanation type. Example: -120.
marked_for_reviewboolean- true to mark the explanation as awaiting review.
paid_billstring- FreeAgent URL of the bill this payment settles or refunds, as returned in the `url` field by freeagent_bills_list. Example: https://api.freeagent.com/v2/bills/123.
paid_invoicestring- FreeAgent URL of the invoice this payment settles (or credit note it refunds), as returned in the `url` field by freeagent_invoices_list. Example: https://api.freeagent.com/v2/invoices/123.
paid_userstring- FreeAgent URL of the user money was paid to or received from, as returned in the `url` field by freeagent_users_list. Example: https://api.freeagent.com/v2/users/123. Omit category for a smart user payment.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
projectstring- FreeAgent URL of the project the payment is linked or rebilled to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice receipt_referencestring- Receipt reference for a payment or refund.
sales_tax_ratenumber- Sales tax (VAT) rate as a percentage, one of the company's standard rates. Example: 20.
sales_tax_statusstring- Mark the item as TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax instead of giving a rate.one of
TAXABLEEXEMPTOUT_OF_SCOPE stock_altering_quantityinteger- For stock purchases or sales: how many units were bought or sold. Example: 10.
stock_itemstring- FreeAgent URL of the stock item purchased or sold, as returned in the `url` field by freeagent_stock_items_list. Example: https://api.freeagent.com/v2/stock_items/123.
transfer_bank_accountstring- FreeAgent URL of the other bank account in a transfer between accounts, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
freeagent_bill_createRecord a supplier bill in FreeAgent with one or more categorised items.WriteCreate Bill
Record a supplier bill in FreeAgent with one or more categorised items. Returns the new bill, including its url. Use this for supplier invoices; use freeagent_expense_create for costs paid personally by a user. Requires a contact URL from freeagent_contacts_list and category URLs from freeagent_categories_list.
Inputs
bill_itemsarrayrequired- Bill line items (up to 40). Each item needs an accounting category URL and a total_value (including tax) or total_value_ex_tax, and usually a description; optionally a sales_tax_rate, sales_tax_status, quantity, unit or project URL. When updating, every item must carry a url: an existing item's URL to change it, the URL plus "_destroy": 1 to delete it, or an empty string to add a new item. Example: [{"category": "https://api.freeagent.com/v2/categories/285", "description": "Office supplies", "total_value": 120, "sales_tax_rate": 20}]
contactstringrequired- FreeAgent URL of the supplier contact being billed, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
dated_onstringrequired- Bill date in YYYY-MM-DD format. Example: 2026-01-31.
due_onstringrequired- Bill due date in YYYY-MM-DD format. Example: 2026-02-28.
referencestringrequired- Free-text bill reference, usually the supplier's invoice number.
commentsstring- Free-text comments on the bill.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse Charge is_paid_by_hire_purchaseboolean- true if the bill will be paid using a hire purchase agreement. Defaults to false.
projectstring- FreeAgent URL of the project the bill relates to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice recurringstring- How often this item recurs. One of: Weekly, Two Weekly, Four Weekly, Two Monthly, Quarterly, Biannually, Annually, 2-Yearly.one of
WeeklyTwo WeeklyFour WeeklyTwo MonthlyQuarterlyBiannuallyAnnually2-Yearly recurring_end_datestring- Date the bill stops recurring in YYYY-MM-DD format. Example: 2026-12-31.
freeagent_bill_updateUpdate a FreeAgent bill's details or items.WriteUpdate Bill
Update a FreeAgent bill's details or items. Returns the updated bill. Only the fields you pass are changed; each bill item must include its url (empty string for a new item). Requires a bill_id from freeagent_bills_list.
- Idempotent
Inputs
bill_idstringrequired- Numeric ID of the bill: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bills/123 the ID is 123). Get it from freeagent_bills_list.
bill_itemsarray- Bill line items (up to 40). Each item needs an accounting category URL and a total_value (including tax) or total_value_ex_tax, and usually a description; optionally a sales_tax_rate, sales_tax_status, quantity, unit or project URL. When updating, every item must carry a url: an existing item's URL to change it, the URL plus "_destroy": 1 to delete it, or an empty string to add a new item. Example: [{"category": "https://api.freeagent.com/v2/categories/285", "description": "Office supplies", "total_value": 120, "sales_tax_rate": 20}]
commentsstring- Free-text comments on the bill.
contactstring- FreeAgent URL of the supplier contact being billed, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
dated_onstring- Bill date in YYYY-MM-DD format. Example: 2026-01-31.
due_onstring- Bill due date in YYYY-MM-DD format. Example: 2026-02-28.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse Charge is_paid_by_hire_purchaseboolean- true if the bill will be paid using a hire purchase agreement. Defaults to false.
projectstring- FreeAgent URL of the project the bill relates to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice recurringstring- How often this item recurs. One of: Weekly, Two Weekly, Four Weekly, Two Monthly, Quarterly, Biannually, Annually, 2-Yearly.one of
WeeklyTwo WeeklyFour WeeklyTwo MonthlyQuarterlyBiannuallyAnnually2-Yearly recurring_end_datestring- Date the bill stops recurring in YYYY-MM-DD format. Example: 2026-12-31.
referencestring- Free-text bill reference, usually the supplier's invoice number.
freeagent_contact_createCreate a FreeAgent contact (client or supplier) for a person or organisation.WriteCreate Contact
Create a FreeAgent contact (client or supplier) for a person or organisation. Returns the new contact, including its url. Use this before invoicing or billing someone new; use freeagent_contact_update to change an existing contact. Give either organisation_name or both first_name and last_name.
Inputs
address1string- First line of the address.
address2string- Second line of the address.
address3string- Third line of the address.
billing_emailstring- Email address that invoices are sent to, if different from email.
charge_sales_taxstring- When to charge sales tax on invoices to this contact: Auto (default), Always or Never.one of
AutoAlwaysNever contact_name_on_invoicesboolean- true to show the person's name as well as the organisation name on invoices.
countrystring- Country name. Example: United Kingdom.
default_payment_terms_in_daysinteger- Default payment terms for this contact's invoices, in days. Example: 30.
emailstring- Contact's email address.
first_namestring- Contact's first name. Required with last_name when organisation_name is not given.
last_namestring- Contact's last name. Required with first_name when organisation_name is not given.
localestring- Language used on this contact's invoices and estimates, as a locale code. Example: en.one of
bgcacyczdedkenen-USesetfifrfr-BEfr-CAisitlv-LVnlnl-BEnkpl-PLpt-BRrorsrusesktr mobilestring- Mobile number.
organisation_namestring- Organisation (company) name. Required when first_name and last_name are not given.
phone_numberstring- Telephone number.
postcodestring- Postcode or ZIP code.
regionstring- Region, county or state.
sales_tax_registration_numberstring- Contact's sales tax (VAT) registration number, shown on invoices and used for EC sales reporting.
statusstring- Contact status: Active or Hidden.one of
ActiveHidden townstring- Town or city.
uses_contact_invoice_sequenceboolean- true to number this contact's invoices with a contact-level sequence instead of the global one.
freeagent_contact_updateUpdate a FreeAgent contact's name, contact details, address, invoice settings or status.WriteUpdate Contact
Update a FreeAgent contact's name, contact details, address, invoice settings or status. Returns the updated contact. Only the fields you pass are changed. Use freeagent_contact_create to add a new contact. Requires a contact_id from freeagent_contacts_list.
- Idempotent
Inputs
contact_idstringrequired- Numeric ID of the contact: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/contacts/123 the ID is 123). Get it from freeagent_contacts_list.
address1string- First line of the address.
address2string- Second line of the address.
address3string- Third line of the address.
billing_emailstring- Email address that invoices are sent to, if different from email.
charge_sales_taxstring- When to charge sales tax on invoices to this contact: Auto (default), Always or Never.one of
AutoAlwaysNever contact_name_on_invoicesboolean- true to show the person's name as well as the organisation name on invoices.
countrystring- Country name. Example: United Kingdom.
default_payment_terms_in_daysinteger- Default payment terms for this contact's invoices, in days. Example: 30.
emailstring- Contact's email address.
first_namestring- Contact's first name. Required with last_name when organisation_name is not given.
last_namestring- Contact's last name. Required with first_name when organisation_name is not given.
localestring- Language used on this contact's invoices and estimates, as a locale code. Example: en.one of
bgcacyczdedkenen-USesetfifrfr-BEfr-CAisitlv-LVnlnl-BEnkpl-PLpt-BRrorsrusesktr mobilestring- Mobile number.
organisation_namestring- Organisation (company) name. Required when first_name and last_name are not given.
phone_numberstring- Telephone number.
postcodestring- Postcode or ZIP code.
regionstring- Region, county or state.
sales_tax_registration_numberstring- Contact's sales tax (VAT) registration number, shown on invoices and used for EC sales reporting.
statusstring- Contact status: Active or Hidden.one of
ActiveHidden townstring- Town or city.
uses_contact_invoice_sequenceboolean- true to number this contact's invoices with a contact-level sequence instead of the global one.
freeagent_credit_note_createCreate a draft credit note in FreeAgent for a contact, with line items.WriteCreate Credit Note
Create a draft credit note in FreeAgent for a contact, with line items. Returns the new credit note in Draft status, including its url. Use freeagent_credit_note_reconciliation_create to apply it to an invoice, and freeagent_credit_note_mark_as_sent to issue it. Requires a contact URL from freeagent_contacts_list.
Inputs
contactstringrequired- FreeAgent URL of the contact being credited, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
dated_onstringrequired- Credit note date in YYYY-MM-DD format. Example: 2026-01-31.
payment_terms_in_daysintegerrequired- Payment terms in days. Set 0 to show 'Due on Receipt'. Example: 30.
bank_accountstring- FreeAgent URL of the bank account shown for remittance on the credit note, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
client_contact_namestring- Name to show on the credit note instead of the contact's display name.
commentsstring- Additional text shown at the bottom of the credit note.
credit_note_itemsarray- Line items for the credit note. Each item needs a description; most also take an item_type (Hours, Products, Services, Expenses, Discount, Credit and similar — leave it out for 'No Unit'), a quantity and a unit price, and optionally a sales_tax_rate (or sales_tax_status EXEMPT) and an income category URL. When updating, include the item's id to change it, or id plus "_destroy": 1 to remove it. Example: [{"item_type": "Services", "quantity": 1, "price": 150, "description": "Refund for cancelled session"}]
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
discount_percentnumber- Discount percentage applied across the whole credit note.
due_onstring- Due date of the credit note in YYYY-MM-DD format. Example: 2026-02-28.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS omit_headerboolean- true to leave your logo and company address off the credit note.
payment_termsstring- Custom payment terms text that overrides the normal terms and due date.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
po_referencestring- Purchase order reference that overrides any PO set on the project.
projectstring- FreeAgent URL of the project being credited, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
referencestring- Credit note reference. When omitted, FreeAgent uses the next reference in the invoice sequence.
show_project_nameboolean- true to show the project name in the Other Information section.
freeagent_credit_note_mark_as_draftMove a FreeAgent credit note back to Draft status so it can be edited.WriteMark Credit Note as Draft
Move a FreeAgent credit note back to Draft status so it can be edited. Returns the updated credit note. Use freeagent_credit_note_mark_as_sent to issue it again. Requires a credit_note_id from freeagent_credit_notes_list.
- Idempotent
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
freeagent_credit_note_mark_as_sentMark a FreeAgent credit note as sent without emailing it.WriteMark Credit Note as Sent
Mark a FreeAgent credit note as sent without emailing it. Returns the updated credit note. Use freeagent_credit_note_send_email to email it instead. Requires a credit_note_id from freeagent_credit_notes_list.
- Idempotent
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
freeagent_credit_note_reconciliation_createApply a FreeAgent credit note against an invoice for a given amount.WriteCreate Credit Note Reconciliation
Apply a FreeAgent credit note against an invoice for a given amount. Returns the new credit note reconciliation. Use this to settle part or all of an invoice with a credit note. Requires an invoice URL from freeagent_invoices_list and a credit note URL from freeagent_credit_notes_list.
Inputs
credit_notestringrequired- FreeAgent URL of the credit note being applied, as returned in the `url` field by freeagent_credit_notes_list. Example: https://api.freeagent.com/v2/credit_notes/123.
gross_valuenumberrequired- Amount to reconcile between the credit note and the invoice. Example: 150.
invoicestringrequired- FreeAgent URL of the invoice the credit is applied to, as returned in the `url` field by freeagent_invoices_list. Example: https://api.freeagent.com/v2/invoices/123.
currencystring- Three-letter ISO 4217 currency code of the reconciliation. Example: GBP.
dated_onstring- Date the reconciliation takes effect in YYYY-MM-DD format. Example: 2026-01-31.
exchange_ratenumber- Rate for converting the amount into the company's native currency, for foreign-currency documents. Example: 1.17.
freeagent_credit_note_send_emailEmail a FreeAgent credit note to its recipient, using a saved template or a custom subject and body.WriteEmail Credit Note
Email a FreeAgent credit note to its recipient, using a saved template or a custom subject and body. Returns the credit note on success. Use freeagent_credit_note_mark_as_sent to mark it sent without emailing. Requires a credit_note_id from freeagent_credit_notes_list.
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
attachmentsarray- Extra files to attach, each up to 5 MB, with file_name, content_type (MIME type) and data (base64-encoded file content). Example: [{"file_name": "timesheet.csv", "content_type": "text/csv", "data": "MTIvMDkvMjAyMiw1LjAw"}]
bodystring- Email body text.
email_to_senderboolean- true (default) to also send a copy to the sender.
fromstring- Sender, which must belong to a registered FreeAgent user, as 'Name <email>' or a bare email. Use freeagent_email_addresses_list for valid senders. Example: Jane Doe <jane@yourco.example>.
subjectstring- Email subject line.
tostring- Recipient email address(es). Example: client@acme.example.
use_templateboolean- true to send using the company's saved email template; the other email fields are then not needed.
freeagent_credit_note_updateUpdate a FreeAgent credit note's details or line items.WriteUpdate Credit Note
Update a FreeAgent credit note's details or line items. Returns the updated credit note. Only the fields you pass are changed. To change status use freeagent_credit_note_mark_as_sent or freeagent_credit_note_mark_as_draft. Requires a credit_note_id from freeagent_credit_notes_list.
- Idempotent
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
bank_accountstring- FreeAgent URL of the bank account shown for remittance on the credit note, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
client_contact_namestring- Name to show on the credit note instead of the contact's display name.
commentsstring- Additional text shown at the bottom of the credit note.
contactstring- FreeAgent URL of the contact being credited, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
credit_note_itemsarray- Line items for the credit note. Each item needs a description; most also take an item_type (Hours, Products, Services, Expenses, Discount, Credit and similar — leave it out for 'No Unit'), a quantity and a unit price, and optionally a sales_tax_rate (or sales_tax_status EXEMPT) and an income category URL. When updating, include the item's id to change it, or id plus "_destroy": 1 to remove it. Example: [{"item_type": "Services", "quantity": 1, "price": 150, "description": "Refund for cancelled session"}]
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
dated_onstring- Credit note date in YYYY-MM-DD format. Example: 2026-01-31.
discount_percentnumber- Discount percentage applied across the whole credit note.
due_onstring- Due date of the credit note in YYYY-MM-DD format. Example: 2026-02-28.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS omit_headerboolean- true to leave your logo and company address off the credit note.
payment_termsstring- Custom payment terms text that overrides the normal terms and due date.
payment_terms_in_daysinteger- Payment terms in days. Set 0 to show 'Due on Receipt'. Example: 30.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
po_referencestring- Purchase order reference that overrides any PO set on the project.
projectstring- FreeAgent URL of the project being credited, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
referencestring- Credit note reference. When omitted, FreeAgent uses the next reference in the invoice sequence.
show_project_nameboolean- true to show the project name in the Other Information section.
freeagent_estimate_convert_to_invoiceConvert a FreeAgent estimate into a new invoice.WriteConvert Estimate to Invoice
Convert a FreeAgent estimate into a new invoice. Returns the estimate with status Invoiced and an invoice field holding the new invoice's URL. Use this once a client accepts an estimate; use freeagent_invoice_create for an invoice without an estimate. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_createCreate a FreeAgent estimate, quote or proposal for a contact, with line items.WriteCreate Estimate
Create a FreeAgent estimate, quote or proposal for a contact, with line items. Returns the new estimate, including its url. Use freeagent_estimate_send_email to send it and freeagent_estimate_convert_to_invoice once it is accepted. Requires a contact URL from freeagent_contacts_list.
Inputs
contactstringrequired- FreeAgent URL of the contact the estimate is for, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
currencystringrequired- Three-letter ISO 4217 currency code of the estimate. Example: GBP.
dated_onstringrequired- Estimate date in YYYY-MM-DD format. Example: 2026-01-31.
estimate_typestringrequired- Kind of document: Estimate, Quote or Proposal.one of
EstimateQuoteProposal referencestringrequired- Free-text estimate reference.
statusstringrequired- Initial status of the estimate. Use Draft for a new estimate, then use the mark_as_* tools to change it.one of
DraftSentOpenApprovedRejectedInvoiced client_contact_namestring- Name to show on the estimate instead of the contact's display name.
discount_percentnumber- Discount percentage applied across the whole estimate. Example: 5.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS estimate_itemsarray- Line items for the estimate. Each item needs an item_type (Hours, Days, Weeks, Months, Years, -no unit-, Products, Services, Training, Expenses, Comments, Bills, Discount or Credit), a price and a description, plus an optional quantity, sales_tax_rate and income category URL. Example: [{"item_type": "Days", "quantity": 5, "price": 600, "description": "Design sprint", "sales_tax_rate": 20}]
include_sales_tax_on_total_valueboolean- true (default) to include sales tax in the totals shown on the estimate.
notesstring- Additional text shown on the estimate.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
projectstring- FreeAgent URL of the project being estimated, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
freeagent_estimate_duplicateCopy a FreeAgent estimate into a new draft dated today with the next reference.WriteDuplicate Estimate
Copy a FreeAgent estimate into a new draft dated today with the next reference. Returns the new draft estimate. Use this to re-quote similar work; use freeagent_estimate_create to start from scratch. Requires an estimate_id from freeagent_estimates_list.
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_mark_as_approvedMark a FreeAgent estimate as approved by the client.WriteMark Estimate as Approved
Mark a FreeAgent estimate as approved by the client. Returns the updated estimate. Use freeagent_estimate_convert_to_invoice to bill it. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_mark_as_draftMove a FreeAgent estimate back to Draft status so it can be edited.WriteMark Estimate as Draft
Move a FreeAgent estimate back to Draft status so it can be edited. Returns the updated estimate. Use freeagent_estimate_mark_as_sent to issue it again. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_mark_as_rejectedMark a FreeAgent estimate as rejected by the client.WriteMark Estimate as Rejected
Mark a FreeAgent estimate as rejected by the client. Returns the updated estimate. Use freeagent_estimate_delete to remove it entirely instead. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_mark_as_sentMark a FreeAgent estimate as sent without emailing it.WriteMark Estimate as Sent
Mark a FreeAgent estimate as sent without emailing it. Returns the updated estimate. Use freeagent_estimate_send_email to email it instead. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_estimate_send_emailEmail a FreeAgent estimate to its recipient, using a saved template or a custom subject and body.WriteEmail Estimate
Email a FreeAgent estimate to its recipient, using a saved template or a custom subject and body. Returns the estimate on success. Use freeagent_estimate_mark_as_sent to mark it sent without emailing. Requires an estimate_id from freeagent_estimates_list.
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
attachmentsarray- Extra files to attach, each up to 5 MB, with file_name, content_type (MIME type) and data (base64-encoded file content). Example: [{"file_name": "timesheet.csv", "content_type": "text/csv", "data": "MTIvMDkvMjAyMiw1LjAw"}]
bodystring- Email body text.
email_to_senderboolean- true (default) to also send a copy to the sender.
fromstring- Sender, which must belong to a registered FreeAgent user, as 'Name <email>' or a bare email. Use freeagent_email_addresses_list for valid senders. Example: Jane Doe <jane@yourco.example>.
subjectstring- Email subject line.
tostring- Recipient email address(es). Example: client@acme.example.
use_templateboolean- true to send using the company's saved email template; the other email fields are then not needed.
freeagent_estimate_updateUpdate a FreeAgent estimate's details or line items.WriteUpdate Estimate
Update a FreeAgent estimate's details or line items. Returns the updated estimate. Only the fields you pass are changed. To change status use the freeagent_estimate_mark_as_* tools. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
client_contact_namestring- Name to show on the estimate instead of the contact's display name.
contactstring- FreeAgent URL of the contact the estimate is for, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
currencystring- Three-letter ISO 4217 currency code of the estimate. Example: GBP.
dated_onstring- Estimate date in YYYY-MM-DD format. Example: 2026-01-31.
discount_percentnumber- Discount percentage applied across the whole estimate. Example: 5.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS estimate_itemsarray- Line items for the estimate. Each item needs an item_type (Hours, Days, Weeks, Months, Years, -no unit-, Products, Services, Training, Expenses, Comments, Bills, Discount or Credit), a price and a description, plus an optional quantity, sales_tax_rate and income category URL. Example: [{"item_type": "Days", "quantity": 5, "price": 600, "description": "Design sprint", "sales_tax_rate": 20}]
estimate_typestring- Kind of document: Estimate, Quote or Proposal.one of
EstimateQuoteProposal include_sales_tax_on_total_valueboolean- true (default) to include sales tax in the totals shown on the estimate.
notesstring- Additional text shown on the estimate.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
projectstring- FreeAgent URL of the project being estimated, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
referencestring- Free-text estimate reference.
freeagent_expense_createRecord an expense claim or mileage claim for a FreeAgent user.WriteCreate Expense
Record an expense claim or mileage claim for a FreeAgent user. Returns the new expense, including its url. Use this for costs a user paid personally; use freeagent_bill_create for supplier bills. Requires a user URL from freeagent_users_list and a category URL from freeagent_categories_list (or Mileage).
Inputs
categorystringrequired- Accounting category URL from freeagent_categories_list (e.g. https://api.freeagent.com/v2/categories/285), or the literal value Mileage for a mileage claim.
dated_onstringrequired- Expense date in YYYY-MM-DD format. Example: 2026-01-31.
descriptionstringrequired- Free-text description of the expense.
userstringrequired- FreeAgent URL of the user claiming the expense, as returned in the `url` field by freeagent_users_list or freeagent_user_me_get. Example: https://api.freeagent.com/v2/users/123.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse Charge engine_sizestring- Mileage claims with a Car or Motorcycle: engine size band, as listed by freeagent_expense_mileage_settings_get.
engine_typestring- Mileage claims with a Car or Motorcycle: engine type such as Petrol (default), Diesel, LPG or an Electric option. Valid electric options are listed by freeagent_expense_mileage_settings_get.
gross_valuenumber- Total amount in the expense currency. Negative for money paid to the claimant (a cost), positive for a refund due from the claimant. Required unless category is Mileage. Example: -45.5.
have_vat_receiptboolean- Mileage claims only: true if you hold a VAT receipt for the fuel.
manual_sales_tax_amountnumber- Exact sales tax amount in the company's native currency. When set, sales_tax_rate is ignored. Example: 16.67.
mileagenumber- Mileage claims only: distance travelled, in the company's mileage units. Example: 42.
projectstring- FreeAgent URL of the project to rebill the expense to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice receipt_referencestring- Receipt reference.
reclaim_mileageinteger- Mileage claims only: 0 (default) to rebill without reclaiming, or 1 to reclaim at the approved mileage allowance (AMAP) rate.
recurringstring- How often this item recurs. One of: Weekly, Two Weekly, Four Weekly, Two Monthly, Quarterly, Biannually, Annually, 2-Yearly.one of
WeeklyTwo WeeklyFour WeeklyTwo MonthlyQuarterlyBiannuallyAnnually2-Yearly recurring_end_datestring- Date the expense stops recurring in YYYY-MM-DD format. Example: 2026-12-31.
sales_tax_ratenumber- Sales tax (VAT) rate as a percentage, one of the company's standard rates. Example: 20.
sales_tax_statusstring- Mark the item as TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax instead of giving a rate.one of
TAXABLEEXEMPTOUT_OF_SCOPE vehicle_typestring- Mileage claims only: Car, Motorcycle or Bicycle.one of
CarMotorcycleBicycle
freeagent_expense_updateUpdate a FreeAgent expense claim.WriteUpdate Expense
Update a FreeAgent expense claim. Returns the updated expense. Only the fields you pass are changed. Requires an expense_id from freeagent_expenses_list.
- Idempotent
Inputs
expense_idstringrequired- Numeric ID of the expense: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/expenses/123 the ID is 123). Get it from freeagent_expenses_list.
categorystring- Accounting category URL from freeagent_categories_list (e.g. https://api.freeagent.com/v2/categories/285), or the literal value Mileage for a mileage claim.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
dated_onstring- Expense date in YYYY-MM-DD format. Example: 2026-01-31.
descriptionstring- Free-text description of the expense.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse Charge engine_sizestring- Mileage claims with a Car or Motorcycle: engine size band, as listed by freeagent_expense_mileage_settings_get.
engine_typestring- Mileage claims with a Car or Motorcycle: engine type such as Petrol (default), Diesel, LPG or an Electric option. Valid electric options are listed by freeagent_expense_mileage_settings_get.
gross_valuenumber- Total amount in the expense currency. Negative for money paid to the claimant (a cost), positive for a refund due from the claimant. Required unless category is Mileage. Example: -45.5.
have_vat_receiptboolean- Mileage claims only: true if you hold a VAT receipt for the fuel.
manual_sales_tax_amountnumber- Exact sales tax amount in the company's native currency. When set, sales_tax_rate is ignored. Example: 16.67.
mileagenumber- Mileage claims only: distance travelled, in the company's mileage units. Example: 42.
projectstring- FreeAgent URL of the project to rebill the expense to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
rebill_factornumber- Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.
rebill_typestring- How to rebill this cost to the project's client: cost (at cost), markup (cost plus rebill_factor percent) or price (fixed rebill_factor amount).one of
costmarkupprice receipt_referencestring- Receipt reference.
reclaim_mileageinteger- Mileage claims only: 0 (default) to rebill without reclaiming, or 1 to reclaim at the approved mileage allowance (AMAP) rate.
recurringstring- How often this item recurs. One of: Weekly, Two Weekly, Four Weekly, Two Monthly, Quarterly, Biannually, Annually, 2-Yearly.one of
WeeklyTwo WeeklyFour WeeklyTwo MonthlyQuarterlyBiannuallyAnnually2-Yearly recurring_end_datestring- Date the expense stops recurring in YYYY-MM-DD format. Example: 2026-12-31.
sales_tax_ratenumber- Sales tax (VAT) rate as a percentage, one of the company's standard rates. Example: 20.
sales_tax_statusstring- Mark the item as TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax instead of giving a rate.one of
TAXABLEEXEMPTOUT_OF_SCOPE userstring- FreeAgent URL of the user claiming the expense, as returned in the `url` field by freeagent_users_list or freeagent_user_me_get. Example: https://api.freeagent.com/v2/users/123.
vehicle_typestring- Mileage claims only: Car, Motorcycle or Bicycle.one of
CarMotorcycleBicycle
freeagent_invoice_createCreate a draft sales invoice in FreeAgent for a contact, with line items or billed project time, expenses and estimates.WriteCreate Invoice
Create a draft sales invoice in FreeAgent for a contact, with line items or billed project time, expenses and estimates. Returns the new invoice in Draft status, including its url. Use freeagent_invoice_mark_as_sent or freeagent_invoice_send_email afterwards to issue it. Requires a contact URL from freeagent_contacts_list.
Inputs
contactstringrequired- FreeAgent URL of the contact being invoiced, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
dated_onstringrequired- Invoice date in YYYY-MM-DD format. Example: 2026-01-31.
payment_terms_in_daysintegerrequired- Payment terms in days, used to compute the due date. Set 0 to show 'Due on Receipt'. Example: 30.
always_show_bic_and_ibanboolean- true to always show the bank account's BIC and IBAN on the invoice.
bank_accountstring- FreeAgent URL of the bank account shown for remittance on the invoice, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
client_contact_namestring- Name to show on the invoice instead of the contact's display name.
commentsstring- Additional text shown at the bottom of the invoice.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
discount_percentnumber- Discount percentage applied across the whole invoice. Example: 10.
due_onstring- Due date of the invoice in YYYY-MM-DD format. Example: 2026-02-28.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS include_estimatesstring- Add the project's open or approved estimates: billed_grouped_by_single_estimate (one line) or billed_grouped_by_estimate (one line each).one of
billed_grouped_by_single_estimatebilled_grouped_by_estimate include_expensesstring- Add the project's unbilled expenses, bills and bank entries: billed_grouped_by_single_expense (one line) or billed_grouped_by_expense (one line each).one of
billed_grouped_by_single_expensebilled_grouped_by_expense include_timeslipsstring- Add the project's unbilled timeslips to the invoice: billed_grouped_by_single_timeslip (one line), billed_grouped_by_timeslip (one line each), billed_grouped_by_timeslip_task or billed_grouped_by_timeslip_date.one of
billed_grouped_by_single_timeslipbilled_grouped_by_timeslipbilled_grouped_by_timeslip_taskbilled_grouped_by_timeslip_date invoice_itemsarray- Line items for the invoice. Each item needs a description; most also take an item_type (Hours, Days, Products, Services, Expenses, Comment, Discount, Stock and similar — leave it out for 'No Unit'), a quantity and a unit price, and optionally a sales_tax_rate (or sales_tax_status EXEMPT) and an income category URL. When updating, include the item's id to change it, or id plus "_destroy": 1 to remove it. Example: [{"item_type": "Hours", "quantity": 8, "price": 75, "description": "Consulting", "sales_tax_rate": 20}]
omit_headerboolean- true to leave your logo and company address off the invoice.
payment_methodsobject- Online payment options to enable on the invoice, as true/false flags: paypal, stripe, gocardless_preauth, gocardless_instant_bank_pay, tyl. Options that are not set up for the company or invoice currency are ignored. Example: {"stripe": true}
payment_termsstring- Custom payment terms text that overrides the normal payment terms and due date.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
po_referencestring- Purchase order reference that overrides any PO set on the project.
projectstring- FreeAgent URL of the project being invoiced, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
referencestring- Invoice reference. When omitted, FreeAgent uses the next reference in the invoice sequence.
send_new_invoice_emailsboolean- true to email the invoice automatically using your default template (templates must exist).
send_reminder_emailsboolean- true to email payment reminders if the invoice goes unpaid (templates must exist).
send_thank_you_emailsboolean- true to email a thank-you once the invoice is paid (templates must exist).
show_project_nameboolean- true to show the project name in the invoice's Other Information section.
freeagent_invoice_duplicateCopy a FreeAgent invoice into a new draft dated today with the next invoice reference.WriteDuplicate Invoice
Copy a FreeAgent invoice into a new draft dated today with the next invoice reference. Returns the new draft invoice. Use this to re-issue a similar invoice; use freeagent_invoice_create to start from scratch. Requires an invoice_id from freeagent_invoices_list.
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_mark_as_cancelledWrite off a sent FreeAgent invoice as unpaid by marking it cancelled.WriteMark Invoice as Cancelled
Write off a sent FreeAgent invoice as unpaid by marking it cancelled. The invoice must be sent and past its due date. Returns the updated invoice. Use freeagent_invoice_delete to remove a draft instead. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_mark_as_draftMove a FreeAgent invoice back to Draft status so it can be edited.WriteMark Invoice as Draft
Move a FreeAgent invoice back to Draft status so it can be edited. Returns the updated invoice. Use freeagent_invoice_mark_as_sent to issue it again. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_mark_as_scheduledSchedule a FreeAgent invoice to be emailed automatically.WriteMark Invoice as Scheduled
Schedule a FreeAgent invoice to be emailed automatically. Returns the updated invoice. Use freeagent_invoice_send_email to email it now. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_mark_as_sentMark a FreeAgent invoice as sent without emailing it, or re-open a cancelled invoice.WriteMark Invoice as Sent
Mark a FreeAgent invoice as sent without emailing it, or re-open a cancelled invoice. Returns the updated invoice. Use freeagent_invoice_send_email to email it instead. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_invoice_send_emailEmail a FreeAgent invoice to its recipient, using a saved template or a custom subject and body.WriteEmail Invoice
Email a FreeAgent invoice to its recipient, using a saved template or a custom subject and body. Returns the invoice on success. Use this to deliver an invoice by email; use freeagent_invoice_mark_as_sent to mark it sent without emailing. Requires an invoice_id from freeagent_invoices_list.
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
attach_expense_receiptsboolean- true to attach receipts of rebilled expenses to the email.
attachmentsarray- Extra files to attach, each up to 5 MB, with file_name, content_type (MIME type) and data (base64-encoded file content). Example: [{"file_name": "timesheet.csv", "content_type": "text/csv", "data": "MTIvMDkvMjAyMiw1LjAw"}]
bodystring- Email body text.
email_to_senderboolean- true (default) to also send a copy to the sender.
fromstring- Sender, which must belong to a registered FreeAgent user, as 'Name <email>' or a bare email. Use freeagent_email_addresses_list for valid senders. Example: Jane Doe <jane@yourco.example>.
subjectstring- Email subject line.
tostring- Recipient email address(es). Example: client@acme.example.
use_templateboolean- true to send using the company's saved email template; the other email fields are then not needed.
freeagent_invoice_updateUpdate a FreeAgent invoice's details or line items.WriteUpdate Invoice
Update a FreeAgent invoice's details or line items. Returns the updated invoice. Only the fields you pass are changed. To change status use freeagent_invoice_mark_as_sent, freeagent_invoice_mark_as_draft or freeagent_invoice_mark_as_cancelled. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
always_show_bic_and_ibanboolean- true to always show the bank account's BIC and IBAN on the invoice.
bank_accountstring- FreeAgent URL of the bank account shown for remittance on the invoice, as returned in the `url` field by freeagent_bank_accounts_list. Example: https://api.freeagent.com/v2/bank_accounts/123.
client_contact_namestring- Name to show on the invoice instead of the contact's display name.
commentsstring- Additional text shown at the bottom of the invoice.
contactstring- FreeAgent URL of the contact being invoiced, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
currencystring- Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.
dated_onstring- Invoice date in YYYY-MM-DD format. Example: 2026-01-31.
discount_percentnumber- Discount percentage applied across the whole invoice. Example: 10.
due_onstring- Due date of the invoice in YYYY-MM-DD format. Example: 2026-02-28.
ec_statusstring- VAT status for EC/VAT reporting. One of: UK/Non-EC, EC Goods, EC Services, Reverse Charge, EC VAT MOSS. EC Goods and EC Services are not valid for Great Britain companies on or after 2021-01-01; Reverse Charge is only valid on or after 2021-01-01.one of
UK/Non-ECEC GoodsEC ServicesReverse ChargeEC VAT MOSS invoice_itemsarray- Line items for the invoice. Each item needs a description; most also take an item_type (Hours, Days, Products, Services, Expenses, Comment, Discount, Stock and similar — leave it out for 'No Unit'), a quantity and a unit price, and optionally a sales_tax_rate (or sales_tax_status EXEMPT) and an income category URL. When updating, include the item's id to change it, or id plus "_destroy": 1 to remove it. Example: [{"item_type": "Hours", "quantity": 8, "price": 75, "description": "Consulting", "sales_tax_rate": 20}]
omit_headerboolean- true to leave your logo and company address off the invoice.
payment_methodsobject- Online payment options to enable on the invoice, as true/false flags: paypal, stripe, gocardless_preauth, gocardless_instant_bank_pay, tyl. Options that are not set up for the company or invoice currency are ignored. Example: {"stripe": true}
payment_termsstring- Custom payment terms text that overrides the normal payment terms and due date.
payment_terms_in_daysinteger- Payment terms in days, used to compute the due date. Set 0 to show 'Due on Receipt'. Example: 30.
place_of_supplystring- EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.
po_referencestring- Purchase order reference that overrides any PO set on the project.
projectstring- FreeAgent URL of the project being invoiced, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
referencestring- Invoice reference. When omitted, FreeAgent uses the next reference in the invoice sequence.
send_new_invoice_emailsboolean- true to email the invoice automatically using your default template (templates must exist).
send_reminder_emailsboolean- true to email payment reminders if the invoice goes unpaid (templates must exist).
send_thank_you_emailsboolean- true to email a thank-you once the invoice is paid (templates must exist).
show_project_nameboolean- true to show the project name in the invoice's Other Information section.
freeagent_journal_set_createPost a balanced set of manual journal entries to the FreeAgent accounts.WriteCreate Journal Set
Post a balanced set of manual journal entries to the FreeAgent accounts. Returns the new journal set with its entries. Use this for accounting corrections; the entries' debit values must sum to zero. Requires category URLs from freeagent_categories_list. Needs the Tax, Accounting & Users permission.
Inputs
dated_onstringrequired- Date of the journal entries in YYYY-MM-DD format. Example: 2026-01-31.
descriptionstringrequired- Free-text description of the journal set.
journal_entriesarrayrequired- Journal entries, which must balance (debit values sum to zero). Each entry needs a category URL and a debit_value (negative for a credit), plus a description; some categories also need a user, stock_item (with stock_altering_quantity) or capital_asset_type URL. Example: [{"category": "https://api.freeagent.com/v2/categories/285", "debit_value": 100, "description": "Accrual"}, {"category": "https://api.freeagent.com/v2/categories/796", "debit_value": -100, "description": "Accrual"}]
tagstring- Free-text tag to identify journal sets created by your integration. Tagged sets can only be edited through the API.
freeagent_note_createAdd a note to a FreeAgent contact or project.WriteCreate Note
Add a note to a FreeAgent contact or project. Returns the new note. Give exactly one of contact or project.
Inputs
notestringrequired- Text of the note.
contactstring- FreeAgent URL of the contact to attach the note to, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123. Give this or project.
projectstring- FreeAgent URL of the project to attach the note to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123. Give this or contact.
freeagent_note_updateReplace the text of a FreeAgent note.WriteUpdate Note
Replace the text of a FreeAgent note. Returns the updated note. Requires a note_id from freeagent_notes_list.
- Idempotent
Inputs
notestringrequired- Text of the note.
note_idstringrequired- Numeric ID of the note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/notes/123 the ID is 123). Get it from freeagent_notes_list.
freeagent_price_list_item_createAdd a product or service with a standard price to the FreeAgent price list.WriteCreate Price List Item
Add a product or service with a standard price to the FreeAgent price list. Returns the new price list item. Use freeagent_price_list_item_update to change an existing item.
Inputs
codestringrequired- Unique name or code used to pick the item when adding it to an invoice or estimate.
descriptionstringrequired- Free-text description of the item.
item_typestringrequired- Unit type: Hours, Days, Weeks, Months, Years, Products, Services, Training, Expenses, Comment, Bills, Discount, Credit, VAT, Stock.one of
HoursDaysWeeksMonthsYearsProductsServicesTrainingExpensesCommentBillsDiscountCreditVATStock pricenumberrequired- Unit price. Example: 75.
quantitynumberrequired- Default quantity. Example: 1.
categorystring- FreeAgent URL of the income category for the item, as returned in the `url` field by freeagent_categories_list. Example: https://api.freeagent.com/v2/categories/123.
sales_tax_ratenumber- Universal and US accounts only: sales tax rate as a percentage. Example: 8.
stock_itemstring- FreeAgent URL of the stock item, when item_type is Stock, as returned in the `url` field by freeagent_stock_items_list. Example: https://api.freeagent.com/v2/stock_items/123.
vat_statusstring- UK accounts only: VAT status out_of_scope (default), reduced, standard or zero.one of
out_of_scopereducedstandardzero
freeagent_price_list_item_updateUpdate a FreeAgent price list item's code, description, price or tax settings.WriteUpdate Price List Item
Update a FreeAgent price list item's code, description, price or tax settings. Returns the updated item. Only the fields you pass are changed. Requires a price_list_item_id from freeagent_price_list_items_list.
- Idempotent
Inputs
price_list_item_idstringrequired- Numeric ID of the price list item: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/price_list_items/123 the ID is 123). Get it from freeagent_price_list_items_list.
categorystring- FreeAgent URL of the income category for the item, as returned in the `url` field by freeagent_categories_list. Example: https://api.freeagent.com/v2/categories/123.
codestring- Unique name or code used to pick the item when adding it to an invoice or estimate.
descriptionstring- Free-text description of the item.
item_typestring- Unit type: Hours, Days, Weeks, Months, Years, Products, Services, Training, Expenses, Comment, Bills, Discount, Credit, VAT, Stock.one of
HoursDaysWeeksMonthsYearsProductsServicesTrainingExpensesCommentBillsDiscountCreditVATStock pricenumber- Unit price. Example: 75.
quantitynumber- Default quantity. Example: 1.
sales_tax_ratenumber- Universal and US accounts only: sales tax rate as a percentage. Example: 8.
stock_itemstring- FreeAgent URL of the stock item, when item_type is Stock, as returned in the `url` field by freeagent_stock_items_list. Example: https://api.freeagent.com/v2/stock_items/123.
vat_statusstring- UK accounts only: VAT status out_of_scope (default), reduced, standard or zero.one of
out_of_scopereducedstandardzero
freeagent_project_createCreate a FreeAgent project for a client contact, with budget and billing settings.WriteCreate Project
Create a FreeAgent project for a client contact, with budget and billing settings. Returns the new project, including its url. Use freeagent_task_create to add tasks and freeagent_timeslip_create to log time on it. Requires a contact URL from freeagent_contacts_list.
Inputs
budget_unitsstringrequired- Unit of the budget: Hours, Days or Monetary (ex-VAT).one of
HoursDaysMonetary contactstringrequired- FreeAgent URL of the client contact to bill for the project, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
currencystringrequired- Three-letter ISO 4217 currency code for the project. Example: GBP.
namestringrequired- Project name.
statusstringrequired- Project status: Active, Completed, Cancelled or Hidden.one of
ActiveCompletedCancelledHidden billing_periodstring- Unit for normal_billing_rate: hour or day.one of
hourday budgetnumber- Project budget in budget_units; 0 if there is no budget. Example: 120.
contract_po_referencestring- Contract or purchase order reference.
ends_onstring- Project end date in YYYY-MM-DD format. Example: 2026-06-30.
hours_per_daynumber- Working hours per day, as a decimal (1:30 is 1.5). Example: 7.5.
include_unbilled_time_in_profitabilityboolean- true to include unbilled time in the project's profitability report.
is_ir35boolean- true if the project falls under IR35 as de facto employment.
normal_billing_ratenumber- Normal billing rate per billing_period. Example: 85.
starts_onstring- Project start date in YYYY-MM-DD format. Example: 2026-01-31.
uses_project_invoice_sequenceboolean- true to number this project's invoices with a project-level sequence.
freeagent_project_updateUpdate a FreeAgent project's name, status, budget, billing settings or dates.WriteUpdate Project
Update a FreeAgent project's name, status, budget, billing settings or dates. Returns the updated project. Only the fields you pass are changed. Requires a project_id from freeagent_projects_list.
- Idempotent
Inputs
project_idstringrequired- Numeric ID of the project: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/projects/123 the ID is 123). Get it from freeagent_projects_list.
billing_periodstring- Unit for normal_billing_rate: hour or day.one of
hourday budgetnumber- Project budget in budget_units; 0 if there is no budget. Example: 120.
budget_unitsstring- Unit of the budget: Hours, Days or Monetary (ex-VAT).one of
HoursDaysMonetary contactstring- FreeAgent URL of the client contact to bill for the project, as returned in the `url` field by freeagent_contacts_list. Example: https://api.freeagent.com/v2/contacts/123.
contract_po_referencestring- Contract or purchase order reference.
currencystring- Three-letter ISO 4217 currency code for the project. Example: GBP.
ends_onstring- Project end date in YYYY-MM-DD format. Example: 2026-06-30.
hours_per_daynumber- Working hours per day, as a decimal (1:30 is 1.5). Example: 7.5.
include_unbilled_time_in_profitabilityboolean- true to include unbilled time in the project's profitability report.
is_ir35boolean- true if the project falls under IR35 as de facto employment.
namestring- Project name.
normal_billing_ratenumber- Normal billing rate per billing_period. Example: 85.
starts_onstring- Project start date in YYYY-MM-DD format. Example: 2026-01-31.
statusstring- Project status: Active, Completed, Cancelled or Hidden.one of
ActiveCompletedCancelledHidden uses_project_invoice_sequenceboolean- true to number this project's invoices with a project-level sequence.
freeagent_task_createCreate a task under a FreeAgent project.WriteCreate Task
Create a task under a FreeAgent project. Returns the new task, including its url. Use freeagent_timeslip_create to log time against it. Requires a project URL from freeagent_projects_list.
Inputs
namestringrequired- Task name.
projectstringrequired- FreeAgent URL of the project to add the task to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
billing_periodstring- Unit for billing_rate: hour or day.one of
hourday billing_ratenumber- Billing rate per billing_period. Example: 85.
is_billableboolean- true if the client is charged for this task.
statusstring- Task status: Active, Completed or Hidden.one of
ActiveCompletedHidden
freeagent_task_updateUpdate a FreeAgent task's name, billing settings or status.WriteUpdate Task
Update a FreeAgent task's name, billing settings or status. Returns the updated task. Only the fields you pass are changed. Requires a task_id from freeagent_tasks_list.
- Idempotent
Inputs
task_idstringrequired- Numeric ID of the task: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/tasks/123 the ID is 123). Get it from freeagent_tasks_list.
billing_periodstring- Unit for billing_rate: hour or day.one of
hourday billing_ratenumber- Billing rate per billing_period. Example: 85.
is_billableboolean- true if the client is charged for this task.
namestring- Task name.
statusstring- Task status: Active, Completed or Hidden.one of
ActiveCompletedHidden
freeagent_timeslip_createLog time worked by a user on a FreeAgent project task.WriteCreate Timeslip
Log time worked by a user on a FreeAgent project task. Returns the new timeslip. Use freeagent_timeslip_timer_start to time work live instead. Requires task, user and project URLs from freeagent_tasks_list, freeagent_users_list and freeagent_projects_list.
Inputs
dated_onstringrequired- Date the work was done in YYYY-MM-DD format. Example: 2026-01-31.
hoursnumberrequired- Hours worked, as a decimal (1:30 is 1.5). Example: 2.5.
projectstringrequired- FreeAgent URL of the project the task belongs to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
taskstringrequired- FreeAgent URL of the task the time was spent on, as returned in the `url` field by freeagent_tasks_list. Example: https://api.freeagent.com/v2/tasks/123.
userstringrequired- FreeAgent URL of the user who did the work, as returned in the `url` field by freeagent_users_list or freeagent_user_me_get. Example: https://api.freeagent.com/v2/users/123.
commentstring- Free-text comment about the work.
freeagent_timeslip_timer_startStart a running timer on a FreeAgent timeslip, adding elapsed time to its hours.WriteStart Timeslip Timer
Start a running timer on a FreeAgent timeslip, adding elapsed time to its hours. Returns the timeslip with its timer details. Use freeagent_timeslip_timer_stop to stop it. Requires a timeslip_id from freeagent_timeslips_list or freeagent_timeslip_create.
Inputs
timeslip_idstringrequired- Numeric ID of the timeslip: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/timeslips/123 the ID is 123). Get it from freeagent_timeslips_list.
freeagent_timeslip_updateUpdate a FreeAgent timeslip's task, project, date, hours or comment.WriteUpdate Timeslip
Update a FreeAgent timeslip's task, project, date, hours or comment. Returns the updated timeslip. Only the fields you pass are changed. Requires a timeslip_id from freeagent_timeslips_list.
- Idempotent
Inputs
timeslip_idstringrequired- Numeric ID of the timeslip: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/timeslips/123 the ID is 123). Get it from freeagent_timeslips_list.
commentstring- Free-text comment about the work.
dated_onstring- Date the work was done in YYYY-MM-DD format. Example: 2026-01-31.
hoursnumber- Hours worked, as a decimal (1:30 is 1.5). Example: 2.5.
projectstring- FreeAgent URL of the project the task belongs to, as returned in the `url` field by freeagent_projects_list. Example: https://api.freeagent.com/v2/projects/123.
taskstring- FreeAgent URL of the task the time was spent on, as returned in the `url` field by freeagent_tasks_list. Example: https://api.freeagent.com/v2/tasks/123.
userstring- FreeAgent URL of the user who did the work, as returned in the `url` field by freeagent_users_list or freeagent_user_me_get. Example: https://api.freeagent.com/v2/users/123.
freeagent_bank_transaction_deletePermanently delete a FreeAgent bank transaction.DestructiveDelete Bank Transaction
Permanently delete a FreeAgent bank transaction. Only transactions that are fully unexplained (have no explanations) can be deleted. Returns an empty response on success. Use freeagent_bank_transaction_explanation_delete to remove an explanation instead. Requires a bank_transaction_id from freeagent_bank_transactions_list.
- Idempotent
Inputs
bank_transaction_idstringrequired- Numeric ID of the bank transaction: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_transactions/123 the ID is 123). Get it from freeagent_bank_transactions_list.
freeagent_bank_transaction_explanation_deleteDelete a FreeAgent bank transaction explanation, leaving the transaction unexplained.DestructiveDelete Bank Transaction Explanation
Delete a FreeAgent bank transaction explanation, leaving the transaction unexplained. Returns an empty response on success. Requires a bank_transaction_explanation_id from freeagent_bank_transaction_explanations_list.
- Idempotent
Inputs
bank_transaction_explanation_idstringrequired- Numeric ID of the bank transaction explanation: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bank_transaction_explanations/123 the ID is 123). Get it from freeagent_bank_transaction_explanations_list.
freeagent_bill_deletePermanently delete a FreeAgent bill.DestructiveDelete Bill
Permanently delete a FreeAgent bill. Returns an empty response on success. Requires a bill_id from freeagent_bills_list.
- Idempotent
Inputs
bill_idstringrequired- Numeric ID of the bill: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/bills/123 the ID is 123). Get it from freeagent_bills_list.
freeagent_contact_deletePermanently delete a FreeAgent contact.DestructiveDelete Contact
Permanently delete a FreeAgent contact. Returns an empty response on success. Use freeagent_contact_update with status Hidden to hide a contact instead of deleting it. Requires a contact_id from freeagent_contacts_list.
- Idempotent
Inputs
contact_idstringrequired- Numeric ID of the contact: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/contacts/123 the ID is 123). Get it from freeagent_contacts_list.
freeagent_credit_note_deletePermanently delete a FreeAgent credit note.DestructiveDelete Credit Note
Permanently delete a FreeAgent credit note. Returns an empty response on success. Requires a credit_note_id from freeagent_credit_notes_list.
- Idempotent
Inputs
credit_note_idstringrequired- Numeric ID of the credit note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/credit_notes/123 the ID is 123). Get it from freeagent_credit_notes_list.
freeagent_estimate_deletePermanently delete a FreeAgent estimate.DestructiveDelete Estimate
Permanently delete a FreeAgent estimate. Returns an empty response on success. Use freeagent_estimate_mark_as_rejected to record a declined estimate instead. Requires an estimate_id from freeagent_estimates_list.
- Idempotent
Inputs
estimate_idstringrequired- Numeric ID of the estimate: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/estimates/123 the ID is 123). Get it from freeagent_estimates_list.
freeagent_expense_deletePermanently delete a FreeAgent expense.DestructiveDelete Expense
Permanently delete a FreeAgent expense. Returns an empty response on success. Requires an expense_id from freeagent_expenses_list.
- Idempotent
Inputs
expense_idstringrequired- Numeric ID of the expense: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/expenses/123 the ID is 123). Get it from freeagent_expenses_list.
freeagent_invoice_deletePermanently delete a FreeAgent invoice.DestructiveDelete Invoice
Permanently delete a FreeAgent invoice. Returns an empty response on success. Use freeagent_invoice_mark_as_cancelled to write off a sent invoice instead. Requires an invoice_id from freeagent_invoices_list.
- Idempotent
Inputs
invoice_idstringrequired- Numeric ID of the invoice: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/invoices/123 the ID is 123). Get it from freeagent_invoices_list.
freeagent_note_deletePermanently delete a FreeAgent note.DestructiveDelete Note
Permanently delete a FreeAgent note. Returns an empty response on success. Requires a note_id from freeagent_notes_list.
- Idempotent
Inputs
note_idstringrequired- Numeric ID of the note: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/notes/123 the ID is 123). Get it from freeagent_notes_list.
freeagent_price_list_item_deletePermanently delete a FreeAgent price list item.DestructiveDelete Price List Item
Permanently delete a FreeAgent price list item. Returns an empty response on success. Requires a price_list_item_id from freeagent_price_list_items_list.
- Idempotent
Inputs
price_list_item_idstringrequired- Numeric ID of the price list item: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/price_list_items/123 the ID is 123). Get it from freeagent_price_list_items_list.
freeagent_project_deletePermanently delete a FreeAgent project.DestructiveDelete Project
Permanently delete a FreeAgent project. Only projects whose is_deletable is true can be deleted. Returns an empty response on success. Use freeagent_project_update with status Completed or Hidden to close a project instead. Requires a project_id from freeagent_projects_list.
- Idempotent
Inputs
project_idstringrequired- Numeric ID of the project: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/projects/123 the ID is 123). Get it from freeagent_projects_list.
freeagent_task_deletePermanently delete a FreeAgent task.DestructiveDelete Task
Permanently delete a FreeAgent task. Only tasks whose is_deletable is true can be deleted. Returns an empty response on success. Use freeagent_task_update with status Completed or Hidden to retire a task instead. Requires a task_id from freeagent_tasks_list.
- Idempotent
Inputs
task_idstringrequired- Numeric ID of the task: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/tasks/123 the ID is 123). Get it from freeagent_tasks_list.
freeagent_timeslip_deletePermanently delete a FreeAgent timeslip.DestructiveDelete Timeslip
Permanently delete a FreeAgent timeslip. Returns an empty response on success. Requires a timeslip_id from freeagent_timeslips_list.
- Idempotent
Inputs
timeslip_idstringrequired- Numeric ID of the timeslip: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/timeslips/123 the ID is 123). Get it from freeagent_timeslips_list.
freeagent_timeslip_timer_stopStop the running timer on a FreeAgent timeslip; the timeslip itself is kept.DestructiveStop Timeslip Timer
Stop the running timer on a FreeAgent timeslip; the timeslip itself is kept. Returns the timeslip with its updated hours. Use freeagent_timeslips_list with view running to find running timers. Requires a timeslip_id from freeagent_timeslips_list.
- Idempotent
Inputs
timeslip_idstringrequired- Numeric ID of the timeslip: the number at the end of its FreeAgent `url` (for https://api.freeagent.com/v2/timeslips/123 the ID is 123). Get it from freeagent_timeslips_list.
No tools match.
