FreeAgent connector for AI agents

Tools your bookkeeping agent reaches for on FreeAgent, scoped per user.

CALL ANY TOOL

117 tools for accounting in FreeAgent: create, email, and reconcile invoices, estimates, and credit notes, record bills and expenses, explain bank transactions, log timeslips, and read financial reports.

freeagent_accounting_transaction_get

Get 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.

Parameters

Name

Type

Required

Description

transaction_id

string

Required

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_list

List accounting transactions

freeagent_bank_account_create

Create bank account

freeagent_bank_account_update

Update bank account

freeagent_bank_statement_upload

Upload bank statement

freeagent_bank_transaction_delete

Delete bank transaction

freeagent_bank_transaction_get

Get bank transaction

freeagent_bank_transactions_list

List bank transactions

freeagent_contact_create

Create 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.

Parameters

Name

Type

Required

Description

address1

string

Optional

First line of the address.

address2

string

Optional

Second line of the address.

address3

string

Optional

Third line of the address.

billing_email

string

Optional

Email address that invoices are sent to, if different from email.

charge_sales_tax

string

Optional

When to charge sales tax on invoices to this contact: Auto (default), Always or Never. One of: `Auto`, `Always`, `Never`.

contact_name_on_invoices

boolean

Optional

true to show the person's name as well as the organisation name on invoices.

country

string

Optional

Country name. Example: United Kingdom.

default_payment_terms_in_days

integer

Optional

Default payment terms for this contact's invoices, in days. Example: 30.

string

Optional

Contact's email address.

first_name

string

Optional

Contact's first name. Required with last_name when organisation_name is not given.

last_name

string

Optional

Contact's last name. Required with first_name when organisation_name is not given.

locale

string

Optional

Language used on this contact's invoices and estimates, as a locale code. Example: en. One of: `bg`, `ca`, `cy`, `cz`, `de`, `dk`, `en`, `en-US`, `es`, `et`, `fi`, `fr`, `fr-BE`, `fr-CA`, `is`, `it`, `lv-LV`, `nl`, `nl-BE`, `nk`, `pl-PL`, `pt-BR`, `ro`, `rs`, `ru`, `se`, `sk`, `tr`.

mobile

string

Optional

Mobile number.

organisation_name

string

Optional

Organisation (company) name. Required when first_name and last_name are not given.

phone_number

string

Optional

Telephone number.

postcode

string

Optional

Postcode or ZIP code.

region

string

Optional

Region, county or state.

sales_tax_registration_number

string

Optional

Contact's sales tax (VAT) registration number, shown on invoices and used for EC sales reporting.

status

string

Optional

Contact status: Active or Hidden. One of: `Active`, `Hidden`.

town

string

Optional

Town or city.

uses_contact_invoice_sequence

boolean

Optional

true to number this contact's invoices with a contact-level sequence instead of the global one.

freeagent_contact_get

Get contact

freeagent_contacts_list

List contacts

freeagent_credit_note_delete

Delete credit note

freeagent_credit_note_mark_as_draft

Credit note mark as draft

freeagent_credit_note_send_email

Credit note send email

freeagent_credit_note_update

Update 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.

Parameters

Name

Type

Required

Description

credit_note_id

string

Required

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_account

string

Optional

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_name

string

Optional

Name to show on the credit note instead of the contact's display name.

comments

string

Optional

Additional text shown at the bottom of the credit note.

contact

string

Optional

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_items

array

Optional

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"}]

currency

string

Optional

Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.

dated_on

string

Optional

Credit note date in YYYY-MM-DD format. Example: 2026-01-31.

discount_percent

number

Optional

Discount percentage applied across the whole credit note.

due_on

string

Optional

Due date of the credit note in YYYY-MM-DD format. Example: 2026-02-28.

ec_status

string

Optional

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-EC`, `EC Goods`, `EC Services`, `Reverse Charge`, `EC VAT MOSS`.

omit_header

boolean

Optional

true to leave your logo and company address off the credit note.

payment_terms

string

Optional

Custom payment terms text that overrides the normal terms and due date.

payment_terms_in_days

integer

Optional

Payment terms in days. Set 0 to show 'Due on Receipt'. Example: 30.

place_of_supply

string

Optional

EU member country name for the place of supply. Required when ec_status is EC VAT MOSS. Example: France.

po_reference

string

Optional

Purchase order reference that overrides any PO set on the project.

project

string

Optional

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.

reference

string

Optional

Credit note reference. When omitted, FreeAgent uses the next reference in the invoice sequence.

show_project_name

boolean

Optional

true to show the project name in the Other Information section.

freeagent_estimate_mark_as_approved

Estimate mark as approved

freeagent_estimate_pdf_get

Get estimate pdf

freeagent_estimates_list

List estimates

freeagent_expense_create

Create 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).

Parameters

Name

Type

Required

Description

category

string

Required

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_on

string

Required

Expense date in YYYY-MM-DD format. Example: 2026-01-31.

description

string

Required

Free-text description of the expense.

user

string

Required

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.

currency

string

Optional

Three-letter ISO 4217 currency code. Defaults to the company's native currency when omitted. Example: GBP.

ec_status

string

Optional

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-EC`, `EC Goods`, `EC Services`, `Reverse Charge`.

engine_size

string

Optional

Mileage claims with a Car or Motorcycle: engine size band, as listed by freeagent_expense_mileage_settings_get.

engine_type

string

Optional

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_value

number

Optional

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_receipt

boolean

Optional

Mileage claims only: true if you hold a VAT receipt for the fuel.

manual_sales_tax_amount

number

Optional

Exact sales tax amount in the company's native currency. When set, sales_tax_rate is ignored. Example: 16.67.

mileage

number

Optional

Mileage claims only: distance travelled, in the company's mileage units. Example: 42.

project

string

Optional

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_factor

number

Optional

Markup percentage or fixed price for the rebill. Required when rebill_type is markup or price. Example: 10.

rebill_type

string

Optional

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: `cost`, `markup`, `price`.

receipt_reference

string

Optional

Receipt reference.

reclaim_mileage

integer

Optional

Mileage claims only: 0 (default) to rebill without reclaiming, or 1 to reclaim at the approved mileage allowance (AMAP) rate.

recurring

string

Optional

How often this item recurs. One of: Weekly, Two Weekly, Four Weekly, Two Monthly, Quarterly, Biannually, Annually, 2-Yearly. One of: `Weekly`, `Two Weekly`, `Four Weekly`, `Two Monthly`, `Quarterly`, `Biannually`, `Annually`, `2-Yearly`.

recurring_end_date

string

Optional

Date the expense stops recurring in YYYY-MM-DD format. Example: 2026-12-31.

sales_tax_rate

number

Optional

Sales tax (VAT) rate as a percentage, one of the company's standard rates. Example: 20.

sales_tax_status

string

Optional

Mark the item as TAXABLE, EXEMPT or OUT_OF_SCOPE for sales tax instead of giving a rate. One of: `TAXABLE`, `EXEMPT`, `OUT_OF_SCOPE`.

vehicle_type

string

Optional

Mileage claims only: Car, Motorcycle or Bicycle. One of: `Car`, `Motorcycle`, `Bicycle`.

freeagent_invoice_duplicate

Duplicate invoice

freeagent_journal_set_get

Get journal set

freeagent_note_create

Create note

freeagent_note_delete

Delete note

freeagent_note_update

Update note

freeagent_notes_list

List notes

freeagent_price_list_item_update

Update price list item

freeagent_stock_item_get

Get stock item

freeagent_stock_items_list

List stock items

freeagent_timeslip_timer_start

Start timeslip timer

freeagent_timeslip_timer_stop

Stop timeslip timer

For more tools, view docs.

Build your Agent

Same auth pattern across LangChain, OpenAI, Anthropic, and Google ADK.

import { ScalekitClient } from "@scalekit-sdk/node";
import { createReactAgent } from "@langchain/langgraph/prebuilt";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

// FreeAgent tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["freeagent"], toolNames: [
    "freeagent_invoices_list",
    "freeagent_invoice_send_email",
    "freeagent_profit_and_loss_summary_get"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Find overdue invoices, email each one to its client again, and summarize this month's profit and loss" }] });

import OpenAI from "openai";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const openai = new OpenAI();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["freeagent"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Find overdue invoices, email each one to its client again, and summarize this month's profit and loss" }],
  tools,
});

// Execute the tool call with the user's vaulted FreeAgent OAuth token
await sk.tools.executeTool(res.choices[0].message.tool_calls[0], "user_123");

import Anthropic from "@anthropic-ai/sdk";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);
const anthropic = new Anthropic();

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["freeagent"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Find overdue invoices, email each one to its client again, and summarize this month's profit and loss" }],
  tools,
});

// Tool call runs with the user's vaulted FreeAgent OAuth token
await sk.tools.executeTool(msg.content, "user_123");

import { Agent } from "@google/adk/agents";
import { ScalekitClient } from "@scalekit-sdk/node";

const sk = new ScalekitClient(env.SCALEKIT_ENV_URL, env.SCALEKIT_CLIENT_ID, env.SCALEKIT_CLIENT_SECRET);

const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["freeagent"] }, pageSize: 100,
});

const agent = new Agent({
  name: "bookkeeping_agent",
  model: "gemini-2.5-pro",
  instruction: "FreeAgent tools scoped to this user",
  tools,
});

await agent.run("Find overdue invoices, email each one to its client again, and summarize this month's profit and loss");

Try these prompts

Copy any prompt into your agent. Each maps directly to a FreeAgent tool. Click to copy, paste into your agent, done.

Invoicing

Copy the prompt

Copied

Create a draft invoice for Harbour Design for 12 hours of consulting at £95 an hour.

Copy the prompt

Copied

Email the latest invoice for Harbour Design to the client.

Copy the prompt

Copied

Convert the approved website estimate into an invoice.

Bank and expenses

Copy the prompt

Copied

List unexplained transactions in our business current account this month.

Copy the prompt

Copied

Explain this £240 bank payment as Travel.

Copy the prompt

Copied

Record a £36 train fare expense for Sam from yesterday.

Reports and time

Copy the prompt

Copied

Show profit and loss for this accounting year.

Copy the prompt

Copied

What tax deadlines are coming up for the company?

Copy the prompt

Copied

Log 3 hours on the Rebrand project for today.

SEE HOW AUTH WORKS

Each user signs in to FreeAgent once, and Scalekit stores and refreshes their tokens. Credentials stay vaulted, every call is scope checked, and every action is logged.

Authorize

Your user connects

FreeAgent

once. We tie it to their identity and the meetings they approved — no shared bot account, no org-wide access

Who:

user ‘A’

when:

Once per user

access:

Limited to user

Store

Their

FreeAgent

token lives in a vault scoped to them. User A's meetings are never reachable by an agent acting for user B, even on the same connection

vault:

encrypted

scope:

per-user

tokens:

auto-refreshed

Resolve

When your agent calls a

FreeAgent

tool, we fetch the right token server-side. It never touches your agent, never appears in the LLM context, never shows up in your logs

speed:

~40ms

check:

before every call

seen by:

nobody

Audit

Every

FreeAgent

tool call is logged — who triggered it, which meeting was fetched, what came back. 90 days of history, tied to the user who authorized it

history:

90 days

export:

SIEM-ready

logged:

every call

Test other agents

See the same per-user auth pattern across other accounting and finance connectors.

GTM and RevOps Teams

Revenue forecast commentary

Pulls open pipeline from Salesforce and HubSpot, calculates coverage against quota, flags at-risk stages, posts commentary to Slack, and logs every snapshot to Google Sheets.

GTM and RevOps Teams

CRM AI agent

Reads the Granola transcript after every call, extracts next steps and updates the HubSpot record, drafts the follow-up in Gmail, and confirms in Slack, all on the rep's own delegated OAuth.

Why Scalekit

Secure your agent's access. Connectors ship in minutes

01.

Shared tokens break per-user analytics

A shared FreeAgent token looks fine in a demo. In production every invoice and journal entry looks like one service account, and you cannot tell which user triggered it. Scalekit resolves the credential of the actual user who triggered the agent, never a shared bot.

// shared token
audit → bot_service_account

// scalekit
audit → user_abc ✓

02.

Authentication is not authorization

03.

Multi-tenancy is architectural

04.

FreeAgent today. Ten connectors tomorrow.

“Our agents act across Salesforce, Gong, Google Drive, and more, on behalf of every customer. Scalekit behind the scenes meant we can keep adding tools without ever rebuilding how credentials or tool calling work.”

Venu Madhav Kattagoni

Head of Engineering / Von

FAQs

Frequently Asked Questions

Does the agent access FreeAgent as the user or through a shared service account?

As the user. Each user signs in to FreeAgent once, and Scalekit stores and refreshes their tokens. Invoices, bills, and journal entries the agent creates are attributed to that user in your audit trail, not a shared service account.

Where is the FreeAgent OAuth token stored?

In Scalekit's managed AES-256 token vault, namespaced per tenant. Refresh is automatic. Revocation is a single dashboard action. Credentials never appear in prompts, logs, or LLM context.

Can I limit what the agent does in FreeAgent?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the report and list tools without freeagent_invoice_delete, which permanently deletes an invoice, or freeagent_journal_set_create, which posts manual journal entries. Scalekit also enforces scope checks before every API call.

What happens when a user revokes FreeAgent access?

The connection is invalidated on the next tool call. Subsequent requests for that user fail closed with a clear error. Other users in the tenant remain unaffected. The event is logged for audit.

Which FreeAgent company does the agent work on?

The company of the FreeAgent user who signs in. freeagent_company_get returns its details, freeagent_user_me_get returns the user who authorized the connection, and freeagent_company_tax_timeline_get lists that company's upcoming tax events, such as VAT returns and corporation tax.