FreshBooks connector for AI agents

Tools your billing agent reaches for on FreshBooks, scoped per user.

CALL ANY TOOL

72 tools for invoicing in FreshBooks: create and email invoices and estimates, record payments, expenses, and other income, log time entries on projects, and run profit and loss, aging, and tax reports.

freshbooks_create_client

Create client

Create a client (customer) in a FreshBooks account. Returns the created client with its new id, contact details and addresses. Use create_client before creating an invoice for a new customer. Provide at least one of fname, lname, organization or email. Requires account_id from freshbooks_get_current_user.

Parameters

Name

Type

Required

Description

account_id

string

Required

FreshBooks account ID (the `account_id`, also called accountid), a short alphanumeric string such as 'LJArJ4'. Get it from freshbooks_get_current_user: business_memberships[].business.account_id.

bus_phone

string

Optional

Business phone number, for example '416-555-0100'.

currency_code

string

Optional

Three-letter ISO currency code for the client, such as USD, CAD or EUR. Defaults to the account's primary currency when omitted.

string

Optional

Client contact's email address, for example 'jane@example.com'. Invoices are emailed here.

fax

string

Optional

Fax number.

fname

string

Optional

Client contact's first name, for example 'Jane'.

home_phone

string

Optional

Home phone number.

language

string

Optional

Two-letter language code for the client's invoices, such as 'en' or 'fr'.

lname

string

Optional

Client contact's last name, for example 'Doe'.

mob_phone

string

Optional

Mobile phone number, for example '416-555-0101'.

note

string

Optional

Private note about the client, visible only to your team.

organization

string

Optional

Name of the client's company, for example 'Acme Inc.'.

p_city

string

Optional

Billing city.

p_code

string

Optional

Billing postal or ZIP code.

p_country

string

Optional

Billing country.

p_province

string

Optional

Billing province or state.

p_street

string

Optional

Billing street address, first line.

p_street2

string

Optional

Billing street address, second line.

s_city

string

Optional

Shipping city.

s_code

string

Optional

Shipping postal or ZIP code.

s_country

string

Optional

Shipping country.

s_province

string

Optional

Shipping province or state.

s_street

string

Optional

Shipping street address, first line.

s_street2

string

Optional

Shipping street address, second line.

vat_name

string

Optional

Name of the client's VAT or tax registration, for example 'VAT'.

vat_number

string

Optional

Client's VAT or tax registration number.

freshbooks_create_estimate

Create estimate

freshbooks_create_item

Create item

freshbooks_create_payment

Create payment

freshbooks_create_task

Create task

freshbooks_delete_client

Delete client

freshbooks_delete_expense

Delete expense

freshbooks_delete_other_income

Delete other income

freshbooks_delete_project

Delete project

freshbooks_get_accounts_aging_report

Get accounts aging report

freshbooks_get_current_user

Get current user

freshbooks_get_expense_category

Get expense category

freshbooks_get_invoice_details_report

Get invoice details report

freshbooks_get_payment

Get payment

freshbooks_get_project

Get project

freshbooks_get_staff

Get staff

freshbooks_get_team_member

Get team member

freshbooks_list_clients

List clients

List clients (customers) in a FreshBooks account, optionally filtered by email, name, organization or balance status. Returns a page of clients with id, name, organization, email, phone numbers, billing address, currency and visibility state, plus page, pages, per_page and total. Use list_clients to browse or search. Use get_client when you already have the client id. Requires account_id from freshbooks_get_current_user.

Parameters

Name

Type

Required

Description

account_id

string

Required

FreshBooks account ID (the `account_id`, also called accountid), a short alphanumeric string such as 'LJArJ4'. Get it from freshbooks_get_current_user: business_memberships[].business.account_id.

string

Optional

Return only the client whose email exactly matches this address.

email_like

string

Optional

Return clients whose email contains this text.

fname_like

string

Optional

Return clients whose first name contains this text.

has_outstanding

boolean

Optional

When true, return only clients with outstanding (unpaid) invoices.

has_overdue

boolean

Optional

When true, return only clients with overdue invoices.

include

array

Optional

Related data to embed in each result. Allowed values: outstanding_balance, credit_balance, draft_balance, overdue_balance, grand_total_balance, last_activity, late_reminders, late_fee. Example: ["outstanding_balance", "credit_balance"].

lname_like

string

Optional

Return clients whose last name contains this text.

organization_like

string

Optional

Return clients whose organization name contains this text.

page

integer

Optional

Page number to return, starting at 1. Use with per_page to walk through all results.

per_page

integer

Optional

Number of results per page. FreshBooks silently caps this at 100; set it explicitly so you know how many results to expect.

updated_min

string

Optional

Return clients updated on or after this date, in YYYY-MM-DD format.

user_like

string

Optional

Return clients whose first name, last name or organization contains this text. Use this for a general name search.

vis_state

integer

Optional

Visibility state to match: 0 for active, 1 for deleted, 2 for archived. Defaults to active clients. One of: `0`, `1`, `2`.

freshbooks_list_estimates

List estimates

freshbooks_list_expenses

List expenses

freshbooks_list_items

List items

freshbooks_list_projects

List projects

freshbooks_list_staff

List staff

freshbooks_list_taxes

List taxes

freshbooks_mark_invoice_as_sent

Mark invoice as sent

freshbooks_send_invoice_by_email

Send invoice by email

freshbooks_update_client

Update client

Update fields on an existing client. Only the fields you provide change. Returns the updated client. Use update_client to change contact or address details. Use delete_client to remove a client. Requires account_id from freshbooks_get_current_user.

Parameters

Name

Type

Required

Description

account_id

string

Required

FreshBooks account ID (the `account_id`, also called accountid), a short alphanumeric string such as 'LJArJ4'. Get it from freshbooks_get_current_user: business_memberships[].business.account_id.

client_id

integer

Required

Numeric ID of the client to update, such as 238951.

bus_phone

string

Optional

Business phone number, for example '416-555-0100'.

currency_code

string

Optional

Three-letter ISO currency code for the client, such as USD, CAD or EUR. Defaults to the account's primary currency when omitted.

string

Optional

Client contact's email address, for example 'jane@example.com'. Invoices are emailed here.

fax

string

Optional

Fax number.

fname

string

Optional

Client contact's first name, for example 'Jane'.

home_phone

string

Optional

Home phone number.

language

string

Optional

Two-letter language code for the client's invoices, such as 'en' or 'fr'.

lname

string

Optional

Client contact's last name, for example 'Doe'.

mob_phone

string

Optional

Mobile phone number, for example '416-555-0101'.

note

string

Optional

Private note about the client, visible only to your team.

organization

string

Optional

Name of the client's company, for example 'Acme Inc.'.

p_city

string

Optional

Billing city.

p_code

string

Optional

Billing postal or ZIP code.

p_country

string

Optional

Billing country.

p_province

string

Optional

Billing province or state.

p_street

string

Optional

Billing street address, first line.

p_street2

string

Optional

Billing street address, second line.

s_city

string

Optional

Shipping city.

s_code

string

Optional

Shipping postal or ZIP code.

s_country

string

Optional

Shipping country.

s_province

string

Optional

Shipping province or state.

s_street

string

Optional

Shipping street address, first line.

s_street2

string

Optional

Shipping street address, second line.

vat_name

string

Optional

Name of the client's VAT or tax registration, for example 'VAT'.

vat_number

string

Optional

Client's VAT or tax registration number.

vis_state

integer

Optional

Set to 2 to archive the client or 0 to make an archived client active again. One of: `0`, `2`.

freshbooks_update_expense

Update expense

freshbooks_update_other_income

Update other income

freshbooks_update_project

Update project

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);

// FreshBooks tools scoped to this user
const { tools } = await sk.tools.listScopedTools("user_123", {
  filter: { connectionNames: ["freshbooks"], toolNames: [
    "freshbooks_get_accounts_aging_report",
    "freshbooks_list_invoices",
    "freshbooks_send_invoice_by_email"] },
  pageSize: 100,
});

const agent = createReactAgent({ llm, tools });
await agent.invoke({ messages: [{ role: "user", content: "Find clients more than 60 days overdue and email their open invoices again" }] });

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: ["freshbooks"] }, pageSize: 100,
});

const res = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Find clients more than 60 days overdue and email their open invoices again" }],
  tools,
});

// Execute the tool call with the user's vaulted FreshBooks 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: ["freshbooks"] }, pageSize: 100,
});

const msg = await anthropic.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Find clients more than 60 days overdue and email their open invoices again" }],
  tools,
});

// Tool call runs with the user's vaulted FreshBooks 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: ["freshbooks"] }, pageSize: 100,
});

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

await agent.run("Find clients more than 60 days overdue and email their open invoices again");

Try these prompts

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

Invoices and estimates

Copy the prompt

Copied

Create a draft invoice for Brightline Media for the October retainer.

Copy the prompt

Copied

Email invoice 0042 to the client and mark it sent.

Copy the prompt

Copied

List estimates that are still in draft.

Payments and expenses

Copy the prompt

Copied

Record a $1,200 payment against invoice 0039.

Copy the prompt

Copied

Log an $86 software expense under Office Expenses.

Copy the prompt

Copied

Run the payments collected report for this month.

Reports and time

Copy the prompt

Copied

Run profit and loss for last quarter.

Copy the prompt

Copied

Show the tax summary for this year.

Copy the prompt

Copied

Log 2.5 hours on the Website Redesign project.

SEE HOW AUTH WORKS

Each user signs in to FreshBooks 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

FreshBooks

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

FreshBooks

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

FreshBooks

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

FreshBooks

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 FreshBooks token looks fine in a demo. In production every invoice and payment 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.

FreshBooks 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 FreshBooks as the user or through a shared service account?

As the user. Each user signs in to FreshBooks once, and Scalekit stores and refreshes their tokens. Invoices, payments, and expenses the agent records are attributed to that user in your audit trail, not a shared service account.

Where is the FreshBooks 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 FreshBooks?

Yes. Filter by tool name in listScopedTools to expose only what you want, for example the list and report tools without freshbooks_delete_project, which deletes a project permanently. Scalekit also enforces scope checks before every API call.

What happens when a user revokes FreshBooks 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 FreshBooks business does the agent act on?

freshbooks_get_current_user returns the signed-in user and the businesses they can act on. Invoice, client, and expense tools work within the FreshBooks account, and project, service, and time entry tools work within a business.