Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to FreshBooks

Scalekit connector
Open markdown

The FreshBooks connector lets your AI agent act in each user's FreshBooks account. Each user signs in to FreshBooks once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 72 tools.

Tools
72
What they doRead · write · destructive
37 · 25 · 1037 read25 write10 destructive
Users sign in with
OAuth app
Your own FreshBooks app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. 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>

  3. Create the FreshBooks connection

    In AgentKit > Connections, create a FreshBooks connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    FreshBooks connections use your own OAuth app. Register one with FreshBooks and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the FreshBooks connection.

  5. 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.actions
    

    const connector = 'freshbooks'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize FreshBooks:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'freshbooks_get_current_user',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • freshbooks_get_accounts_aging_reportRun the Accounts Aging report, which shows overdue invoice amounts per client in 0-30, 31-60, 61-90 and 91+ day buckets.Read-only

    Get Accounts Aging Report

    Run the Accounts Aging report, which shows overdue invoice amounts per client in 0-30, 31-60, 61-90 and 91+ day buckets. Returns totals per age bucket and a list of clients with their overdue amounts. Use get_accounts_aging_report to see who owes you and for how long. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    end_datestring
    Last day of the report period, in YYYY-MM-DD format.
    start_datestring
    First day of the report period, in YYYY-MM-DD format.
  • freshbooks_get_clientGet one client by id.Read-only

    Get Client

    Get one client by id. Returns the client with contact details, billing and shipping address, currency, language, notes and visibility state. Use get_client for full details of a known client. Use list_clients to search. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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_idintegerrequired
    Numeric ID of the client (also called customerid or userid), such as 238951.
    includearray
    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"].
  • freshbooks_get_current_userGet the authenticated FreshBooks user and the businesses they can act on.Read-only

    Get Current User

    Get the authenticated FreshBooks user and the businesses they can act on. Returns the user profile plus business_memberships, each with the business id, business_uuid, name, account_id and the user's role. Use this first to find the account_id, business_id or business_uuid that every other FreshBooks tool needs.

    Inputs

    This tool takes no inputs.

  • freshbooks_get_estimateGet one estimate by id.Read-only

    Get Estimate

    Get one estimate by id. Returns the estimate with amounts, status, dates, client details and, when requested through include, its lines. Use get_estimate for a known estimate. Use list_estimates to search. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    estimate_idintegerrequired
    Numeric ID of the estimate, such as 2201278.
    includearray
    Related data to embed in each result. Allowed values: lines, contacts, owner, audit_logs, comments, presentation, project, invoices, system. Example: ["lines", "contacts"].
  • freshbooks_get_expenseGet one expense by id.Read-only

    Get Expense

    Get one expense by id. Returns the expense with amount, date, vendor, category, client, project, notes and tax details. Use get_expense for a known expense. Use list_expenses to search. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    expense_idintegerrequired
    Numeric ID of the expense (expenseid), such as 1569533.
    includearray
    Related data to embed in each result. Allowed values: category, attachment, expense_profile, project, account. Example: ["category", "attachment"].
  • freshbooks_get_expense_categoryGet one expense category by id.Read-only

    Get Expense Category

    Get one expense category by id. Returns the category with its name, parent category id and editable flag. Use get_expense_category for a known category. Use list_expense_categories to browse. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    category_idintegerrequired
    Numeric ID of the expense category, such as 93992990.
  • freshbooks_get_invoiceGet one invoice by id.Read-only

    Get Invoice

    Get one invoice by id. Returns the invoice with amounts, status, dates, client details and, when requested through include, its lines. Use get_invoice for a known invoice. Include 'lines' to see line items. Use list_invoices to search. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    invoice_idintegerrequired
    Numeric ID of the invoice (invoiceid), such as 2214249.
    includearray
    Related data to embed in each result. Allowed values: lines, contacts, owner, audit_logs, client_audits, comments, allowed_gateways, late_fee, late_reminders, presentation, project_total_amounts, latest_journal_entry, system. Example: ["lines", "contacts"].
  • freshbooks_get_invoice_details_reportRun the Invoice Details report for a date range.Read-only

    Get Invoice Details Report

    Run the Invoice Details report for a date range. Returns invoices with number, client, status, dates, totals, tax, paid and outstanding amounts, plus a summary with totals. Use get_invoice_details_report for invoice-level reporting. Use get_payments_collected_report for money received. Requires account_id from freshbooks_get_current_user.

    Inputs

    account_idstringrequired
    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.
    currency_codestring
    Report in this three-letter currency, such as USD.
    date_typestring
    Which date the range applies to: 'issue' for invoice issue date or 'paid' for paid date.one of issuepaid
    end_datestring
    Last day of the report period, in YYYY-MM-DD format.
    start_datestring
    First day of the report period, in YYYY-MM-DD format.
All 37 in Accounting & Finance