FreshBooks Integration

This guide explains how to connect FreshBooks to Supervity, what data is available after connection, how operators can use FreshBooks data and actions within workflows, and how to remove the integration when needed.

---

Overview

The Supervity FreshBooks integration allows your workspace to securely connect FreshBooks as a governed platform capability.

Once connected, operators and workflows can use FreshBooks data and actions to automate accounting and billing workflows, manage clients, handle invoices and estimates, track business expenses, record payments, and manage projects and time tracking across systems.

With the FreshBooks integration, Supervity can:

• Manage clients: List, retrieve, create, update, and delete client profiles
• Manage invoices: List, retrieve, create, update, and delete invoices and line items
• Manage estimates: List, retrieve, create, update, and delete quotes and project estimates
• Manage expenses: List, retrieve, create, update, and track business expenses and categories
• Manage payments: List, retrieve, record, update, and delete client payments
• Manage projects: List, retrieve, create, update, and delete projects
• Track time entries: List, retrieve, log, update, and delete time entries for project billing
• Use FreshBooks accounting and project data as context for operators
• Trigger workflows based on billing, financial, project, and time-tracking activity

All FreshBooks access is governed through Supervity's security, permissions, and audit controls.

---

Prerequisites

Before connecting FreshBooks, ensure you have:

• An active Supervity workspace
• A FreshBooks account (Lite, Plus, Premium, Select, or Trial)
• Permission to authorize third-party applications on your FreshBooks account
• Access to the FreshBooks business account containing the clients, invoices, expenses, projects, and time entries you want to use

Depending on your FreshBooks account role and subscription plan, some operations (such as managing projects, expenses, or business-wide billing settings) may require administrative or business owner permissions.

---

Adding the FreshBooks Integration

Follow these steps to connect FreshBooks to Supervity. If you encounter any issues during setup, refer to the Troubleshooting section of this guide.

Step 1: Open Integrations

1. Log in to Supervity.
2. From the left navigation bar, click the Integrations icon.

This opens the Integrations page, where all available integrations are listed. Connected integrations and available integrations can both be managed from this page.

Step 2: Select FreshBooks

1. Locate FreshBooks in the available integrations list.
2. Click Connect.

Step 3: Authorize Access

You will be redirected to FreshBooks's secure authorization page.

Review the requested permissions and click Authorize (or Allow) to grant Supervity access to your FreshBooks account.

• Supervity uses FreshBooks's standard OAuth 2.0 authorization flow.
• Your FreshBooks password is never shared with or stored by Supervity.

Step 4: Complete Connection

After authorization, you will be redirected back to Supervity.

The FreshBooks integration will appear as Connected on the Integrations page. Your workspace can now securely access FreshBooks capabilities according to the permissions granted.

Having trouble? See the Troubleshooting section for step-by-step help with common setup issues.

---

How FreshBooks Works in Supervity

After connection, FreshBooks becomes available as a governed platform tool.

Operators can use FreshBooks capabilities when planning and executing tasks, while workflows can automate actions using FreshBooks data.

Common use cases include:

• Creating and updating client records automatically from CRM leads or sign-up forms
• Generating and sending invoices upon milestone completion or contract sign-off
• Creating quotes and estimates for prospective customers
• Tracking and categorizing operational and business expenses
• Recording customer payments and reconciling invoices
• Setting up new client projects automatically when deals close
• Logging billable hours and time entries against active projects
• Synchronizing financial records across FreshBooks and other connected business systems

---

Using FreshBooks in Operators

Connected FreshBooks capabilities become available to operators automatically. Operators determine when FreshBooks data or actions are required to complete a task and execute accordingly, while remaining governed by workspace permissions, security controls, and approval policies.

What Operators Can Do with FreshBooks

Operators can perform the following actions using FreshBooks:

• Manage clients (list clients, get client details, create clients, update client information, and delete clients)
• Manage invoices (list invoices, get invoice details, create invoices with line items, update invoices, and delete invoices)
• Manage estimates (list estimates, get estimate details, create estimates with line items, update estimates, and delete estimates)
• Manage expenses (list expenses, get expense details, create expenses with amounts and categories, update expenses, and delete expenses)
• Manage payments (list payments, get payment details, record new payments against invoices, update payment notes, and delete payments)
• Manage projects (list projects, get project details, create client-associated projects, update project details, and delete projects)
• Manage time entries (list time entries, get time entry details, log time entries with duration and notes for projects, update time entries, and delete time entries)
• Correlate FreshBooks financial and time-tracking records with CRM, customer support, project management, and messaging applications
• Generate summaries, financial reports, invoice overviews, and time utilization insights
• Combine accounting actions with other applications for automated end-to-end workflows

Typical Operator Use Cases

---

Features & Prerequisites

For each FreshBooks capability available in Supervity, the following describes the use case and the prerequisites required before use.

List Clients

Use Case: Retrieve a list of all clients associated with the connected FreshBooks account. Useful for client directory lookup, reporting, and customer synchronization.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with client access permissions

---

Get Client

Use Case: Retrieve detailed profile information for a specific client by ID, including name, email, and organization details.

Prerequisites:

• FreshBooks account connected to Supervity
• Client ID must exist and be accessible within the connected account

---

Create Client

Use Case: Create a new client profile with contact and organization details. Useful for automating customer onboarding from external forms or CRM records.

Prerequisites:

• FreshBooks account connected to Supervity
• Client details (such as first name, last name, email, or organization) must be provided
• Write permissions enabled for client management

---

Update Client

Use Case: Modify contact details, organization information, or preferences for an existing client.

Prerequisites:

• FreshBooks account connected to Supervity
• Target client ID must exist
• Write permissions enabled for client management

---

Delete Client

Use Case: Remove or deactivate an existing client profile from FreshBooks when no longer required.

Prerequisites:

• FreshBooks account connected to Supervity
• Target client ID must exist
• Write permissions enabled for client management

---

List Invoices

Use Case: Retrieve all invoices from the connected FreshBooks account to review billing history, verify payment status, or generate accounts receivable reports.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with invoice access permissions

---

Get Invoice

Use Case: Retrieve complete details for a specific invoice, including line items, amounts, dates, and payment status.

Prerequisites:

• FreshBooks account connected to Supervity
• Invoice ID must exist and be accessible within the connected account

---

Create Invoice

Use Case: Create a new customer invoice with line item descriptions, quantities, unit costs, currency codes, and creation dates.

Prerequisites:

• FreshBooks account connected to Supervity
• Valid customer/client ID and invoice line item details must be provided
• Write permissions enabled for invoice management

---

Update Invoice

Use Case: Update existing invoice details, such as notes, terms, line items, or billing information.

Prerequisites:

• FreshBooks account connected to Supervity
• Target invoice ID must exist
• Write permissions enabled for invoice management

---

Delete Invoice

Use Case: Delete or void an invoice that was created in error or is no longer valid.

Prerequisites:

• FreshBooks account connected to Supervity
• Target invoice ID must exist
• Write permissions enabled for invoice management

---

List Estimates

Use Case: Retrieve a list of all quotes and estimates in the FreshBooks account to track prospective project proposals and client approvals.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with estimate access permissions

---

Get Estimate

Use Case: Retrieve the full details of a specific estimate by ID, including pricing lines, quantities, terms, and customer information.

Prerequisites:

• FreshBooks account connected to Supervity
• Estimate ID must exist and be accessible within the connected account

---

Create Estimate

Use Case: Generate a new project or service estimate with customer details, line items, quantities, pricing, and issue dates.

Prerequisites:

• FreshBooks account connected to Supervity
• Valid customer/client ID and estimate line items must be provided
• Write permissions enabled for estimate management

---

Update Estimate

Use Case: Update details, terms, conditions, or line items on an existing estimate.

Prerequisites:

• FreshBooks account connected to Supervity
• Target estimate ID must exist
• Write permissions enabled for estimate management

---

Delete Estimate

Use Case: Remove an estimate that was rejected, cancelled, or created in error.

Prerequisites:

• FreshBooks account connected to Supervity
• Target estimate ID must exist
• Write permissions enabled for estimate management

---

List Expenses

Use Case: Retrieve a list of recorded business expenses to monitor operational spending, tax deductions, and financial outlays.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with expense access permissions

---

Get Expense

Use Case: Retrieve specific expense details by ID, including the amount, currency, category, date, and notes.

Prerequisites:

• FreshBooks account connected to Supervity
• Expense ID must exist and be accessible within the connected account

---

Create Expense

Use Case: Record a new business expense with amount, currency code, category ID, transaction date, and optional notes.

Prerequisites:

• FreshBooks account connected to Supervity
• Expense amount, currency code, category ID, and date must be provided
• Write permissions enabled for expense management

---

Update Expense

Use Case: Modify notes, category assignments, or transaction details for an existing expense record.

Prerequisites:

• FreshBooks account connected to Supervity
• Target expense ID must exist
• Write permissions enabled for expense management

---

Delete Expense

Use Case: Remove an expense entry that is obsolete or recorded incorrectly.

Prerequisites:

• FreshBooks account connected to Supervity
• Target expense ID must exist
• Write permissions enabled for expense management

---

List Payments

Use Case: Retrieve all recorded payments across invoices to audit revenue inflows and reconcile accounting ledgers.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with payment access permissions

---

Get Payment

Use Case: Retrieve details of a specific payment transaction by ID, including invoice ID, amount, currency, date, and payment notes.

Prerequisites:

• FreshBooks account connected to Supervity
• Payment ID must exist and be accessible within the connected account

---

Create Payment

Use Case: Record a new payment against an existing invoice, specifying invoice ID, amount, currency, transaction date, and notes.

Prerequisites:

• FreshBooks account connected to Supervity
• Valid invoice ID, payment amount, currency, and date must be provided
• Write permissions enabled for payment management

---

Update Payment

Use Case: Update payment details, such as notes or descriptions associated with a recorded payment.

Prerequisites:

• FreshBooks account connected to Supervity
• Target payment ID must exist
• Write permissions enabled for payment management

---

Delete Payment

Use Case: Remove or void a recorded payment entry when needed.

Prerequisites:

• FreshBooks account connected to Supervity
• Target payment ID must exist
• Write permissions enabled for payment management

---

List Projects

Use Case: Retrieve all business projects to track active client engagements, billing structures, and project statuses.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with project access permissions

---

Get Project

Use Case: Retrieve details of a specific project by ID, including project title, associated client, and project type.

Prerequisites:

• FreshBooks account connected to Supervity
• Project ID must exist and be accessible within the connected account

---

Create Project

Use Case: Create a new project associated with a client, specifying project title and project type (e.g., fixed price).

Prerequisites:

• FreshBooks account connected to Supervity
• Project title and client ID must be provided
• Write permissions enabled for project management

---

Update Project

Use Case: Update project titles, settings, or properties for an existing project.

Prerequisites:

• FreshBooks account connected to Supervity
• Target project ID must exist
• Write permissions enabled for project management

---

Delete Project

Use Case: Remove a project from FreshBooks when it has been completed or archived.

Prerequisites:

• FreshBooks account connected to Supervity
• Target project ID must exist
• Write permissions enabled for project management

---

List Time Entries

Use Case: Retrieve logged time entries across projects to track billable work hours, team productivity, and timesheet logs.

Prerequisites:

• FreshBooks account connected to Supervity
• Active business account with time tracking access permissions

---

Get Time Entry

Use Case: Retrieve detailed information for a specific logged time entry by ID, including duration, notes, start time, and project ID.

Prerequisites:

• FreshBooks account connected to Supervity
• Time entry ID must exist and be accessible within the connected account

---

Create Time Entry

Use Case: Log new work hours against a project, specifying duration, notes, start timestamp, and project ID.

Prerequisites:

• FreshBooks account connected to Supervity
• Valid duration, start time, and project ID must be provided
• Write permissions enabled for time tracking

---

Update Time Entry

Use Case: Modify duration, notes, or details of an existing logged time entry.

Prerequisites:

• FreshBooks account connected to Supervity
• Target time entry ID must exist
• Write permissions enabled for time tracking

---

Delete Time Entry

Use Case: Remove an erroneous or duplicate time entry from project timesheets.

Prerequisites:

• FreshBooks account connected to Supervity
• Target time entry ID must exist
• Write permissions enabled for time tracking

---

Permissions Requested

Supervity only requests the permissions required for enabled FreshBooks capabilities.

Depending on the features used in your workspace, permissions may include:

Supervity follows least-privilege principles and only accesses data necessary to provide requested functionality.

---

Authentication & Security

The FreshBooks integration uses OAuth 2.0 authentication.

Security controls include:

• Encrypted credential storage (AES-256)
• Least-privilege access scopes
• Token refresh and rotation support
• Immediate revocation capabilities
• Workspace-level governance controls
• Complete audit logging
• TLS 1.3 for all API and UI connections

All FreshBooks access remains subject to Supervity security policies and role-based permissions.

---

Managing the Integration

View Connection Status

From the left navigation bar, click the Integrations icon.

For FreshBooks you can view:

• Connection status
• Granted permissions
• Last usage information
• Associated workflows and operators

Reconnect FreshBooks

If FreshBooks authorization expires or security policies change:

1. Open the Integrations page from the left navigation bar.
2. Select FreshBooks.
3. Click Reconnect.
4. Complete authorization again through the FreshBooks portal.

Existing workflows and operators do not need to be recreated.

Removing the FreshBooks Integration

You can remove the FreshBooks connection from your Supervity workspace at any time directly from within the Supervity platform.

Steps to Remove

1. Log in to Supervity.
2. From the left navigation bar, click the Integrations icon.
3. Locate and select FreshBooks from the integrations list.
4. Click Disconnect.
5. Confirm the action when prompted.

Implications of Removal

Once removed:

• Supervity immediately loses all access to your FreshBooks account and associated data
• No new FreshBooks data will be retrieved or modified after removal
• All active FreshBooks connections within your Supervity workspace are terminated
• Scheduled or active workflows that depend on FreshBooks will stop executing
• FreshBooks-dependent workflow steps will fail safely with clear error messages
• Existing workflow definitions within Supervity are not deleted — only the active connection is terminated
• Historical execution logs remain available for auditing purposes

Disconnecting FreshBooks does not delete workflow definitions, operators, or previously generated outputs.

How Your Data Is Handled After Removal

Data Handling on Removal:

• Supervity immediately loses access to your FreshBooks account upon removal
• No new FreshBooks records or data will be collected or processed after disconnection
• Temporary files processed during workflow execution are deleted after execution completes
• FreshBooks access tokens and all account-related data are permanently deleted from Supervity's platform within 15 minutes of disconnection — no background access continues after removal

---

Auditing & Observability

All FreshBooks activity performed through Supervity is logged.

Audit records include:

• Which operator requested access
• Which workflow executed the action
• Timestamp of execution
• Success or failure status
• Relevant inputs and outputs (sensitive values are redacted)

This supports compliance, troubleshooting, governance, and operational visibility.

---

Troubleshooting

If you encounter issues at any stage, refer to the steps below. For issues not covered here, contact the Supervity support team.

Authorization Failed During Setup

Likely Cause: Incorrect FreshBooks account credentials, or insufficient permissions to authorize third-party applications.

Resolution:

1. Ensure you are signed in to the correct FreshBooks account with appropriate administrative or owner privileges.
2. Return to Supervity → Integrations → FreshBooks and click Connect to retry.
3. If the issue persists, contact your FreshBooks account administrator.

---

FreshBooks Shows Connected but Records Are Missing

Likely Cause: Insufficient permissions on specific business resources, or records exist under a different business account.

Resolution:

1. Verify that the requested clients, invoices, expenses, or projects exist in the connected FreshBooks account.
2. Confirm the account connected to Supervity has permissions to view and manage those resources.
3. Reconnect the integration via Integrations → FreshBooks → Reconnect to refresh permissions.

---

Connection Expired or Token Invalid

Likely Cause: OAuth token expired or was revoked in FreshBooks settings.

Resolution:

1. Go to Integrations → FreshBooks → Reconnect.
2. Complete the FreshBooks authorization flow again.
3. Existing workflows do not need to be reconfigured after reconnection.

---

Workflow Cannot Access FreshBooks

Likely Cause: FreshBooks may have been disconnected, or workspace governance policies may restrict access.

Resolution:

1. Confirm FreshBooks is still connected under the Integrations page.
2. Verify the workflow has permission to use FreshBooks within your workspace governance settings.
3. Check that workspace policies allow FreshBooks execution for the relevant operators or workflows.

---

Creating Invoices or Estimates Fails

Likely Cause: Missing required fields, invalid customer ID, or malformed line item data.

Resolution:

1. Verify that a valid customer ID is provided and that the client exists in FreshBooks.
2. Ensure line items include required fields such as quantity, description/name, and unit cost amount.
3. Check that the currency code matches the currency configured in your FreshBooks account.

---

Recording Payments Fails

Likely Cause: Invalid invoice ID, payment amount exceeding invoice balance, or missing date.

Resolution:

1. Verify that the target invoice ID exists and is in an open/payable state.
2. Ensure payment amount and date are properly specified.
3. Confirm that the account has permissions to record payments.

---

Logging Time Entries Fails

Likely Cause: Invalid project ID, missing duration, or start timestamp format issues.

Resolution:

1. Ensure the specified project ID exists in FreshBooks.
2. Verify duration is specified in seconds and start time is formatted correctly.
3. Confirm the user has time tracking privileges on the target project.

---

Frequently Asked Questions

Q: Is my FreshBooks password shared with or stored by Supervity?

No. Supervity uses FreshBooks's standard OAuth 2.0 authorization flow. Your FreshBooks password is never shared with or stored by Supervity. Only scoped access tokens are stored, and these are encrypted at rest using AES-256.

---

Q: What FreshBooks plans are supported?

All standard FreshBooks plans (Lite, Plus, Premium, Select) as well as active trial accounts are supported.

---

Q: Will I need to reconfigure my workflows after reconnecting FreshBooks?

No. If you reconnect FreshBooks due to token expiry or permission updates, existing workflow definitions and operators do not need to be recreated or reconfigured.

---

Q: What happens to my workflows if I disconnect or remove FreshBooks?

Workflow definitions are not deleted when FreshBooks is disconnected or removed. However, any workflow steps that depend on FreshBooks will fail safely with clear error messages until FreshBooks is reconnected.

---

Q: How do I authorize the Supervity FreshBooks integration?

Log in to Supervity at Supervity, navigate to the Integrations page from the left navigation bar, locate FreshBooks, and click Connect. You will be redirected to FreshBooks's authorization page where you can review and approve the requested permissions. After authorization, you will be redirected back to Supervity automatically. See the Adding the FreshBooks Integration section above for full step-by-step instructions.

---

Q: Can I limit which FreshBooks data Supervity can access?

Supervity requests only the permissions required for enabled capabilities, following least-privilege principles. You can review all requested access types during the OAuth authorization step before approving.

---

Q: Who do I contact if I have an issue with the integration?

Contact the Supervity support team. See the Support section below for full contact details, support hours, and SLA information.

---

Support

If you need assistance with the FreshBooks integration, visit the Support page.

Support Hours

• Monday to Friday, 9:00 AM – 6:00 PM IST
• Requests submitted outside business hours will be addressed on the next business day

First Response SLA

• All support requests receive an initial response within 24 business hours

Contact Information

When Contacting Support, Please Provide

• Workspace name
• FreshBooks account email or identifier used for authorization
• Relevant workflow or operator information
• Error messages or screenshots when available

This helps the support team investigate and resolve issues more quickly.

---

Related Documentation

• Integrations Overview
• OAuth2
• Security & Privacy
• Supervity Website