FreshBooks integration

What it does

The FreshBooks integration lets your agency run bookkeeping operations on behalf of your clients without leaving TaskJuice. Connect a client's FreshBooks business once and you can create and update clients, draft and send invoices, log expenses and bills, manage estimates and credit notes, and track project time. Every event FreshBooks publishes is available as a trigger, so a workflow can start the moment an invoice is sent, a payment lands, or a client record changes.

Each connection is scoped to a single FreshBooks business, so one workspace stays clean across many clients.

Connect a FreshBooks account

FreshBooks requires your agency to bring its own OAuth application. You register it once, then every client connection reuses it.

1. Create an application at my.freshbooks.com/#/developer. FreshBooks issues the client ID and secret immediately.
2. Register your TaskJuice callback as a redirect URI on that application. Redirect URIs must use HTTPS and must not carry query string parameters.
3. In TaskJuice, open Settings, then Integrations, then OAuth clients, and add the FreshBooks client ID and secret. Tick the scopes your workflows need.
4. In the workflow editor, add any FreshBooks node and connect an account from the node itself. Sign in to the FreshBooks account that has access to your client's business and approve the requested scopes.
5. Paste the FreshBooks accountId for the business you want to operate on. You can list every authorized business by calling GET https://api.freshbooks.com/auth/api/v1/users/me and reading business_memberships[].business.account_id.

Actions on the Projects, Time Tracking, and Services surfaces are addressed by business ID rather than account ID. You pick the business from a dropdown on those nodes, so there is nothing extra to paste.

To revoke access, open my.freshbooks.com, go to Settings, then Apps and Integrations, find your application, and disconnect it. See the FreshBooks Authentication guide for the full grant flow.

Set up webhook triggers

FreshBooks does not expose a console for managing webhook callbacks, so a callback is registered through its API and the registration is a two step handshake.

1. Register the callback against the event you want, for example POST https://api.freshbooks.com/events/account/<account_id>/events/callbacks with {"callback": {"event": "invoice.create", "uri": "<your TaskJuice trigger URL>"}}.
2. FreshBooks immediately posts a verification code to that URL. Echo it back with PUT https://api.freshbooks.com/events/account/<account_id>/events/callbacks/<callback_id> and {"callback": {"verifier": "<code>"}} to activate the callback.
3. Paste the same verifier token into the trigger's inbound authentication field. FreshBooks signs every later delivery with HMAC-SHA256 using that token as the secret and sends the base64 digest in the X-FreshBooks-Hmac-SHA256 header, which is how TaskJuice proves a delivery is genuine.

If you lose the verifier, send PUT ... {"callback": {"resend": true}} to have FreshBooks deliver a fresh one.

FreshBooks deliveries are thin notifications. Each carries the event name and the object ID, not the whole record, so pair a trigger with the matching list or get action to load the full object.

Triggers

One webhook trigger exists per event FreshBooks publishes.

One polling trigger remains as a fallback:

• freshbooks/invoice-updated-poll checks the invoices endpoint on a configurable interval and fires one activation per cycle, with items carrying every invoice changed since the previous watermark. Prefer the invoice webhook triggers where you can register a callback. Polling runs on a timer whether or not anything changed, so it costs far more than a webhook that fires only on a real event.

Actions

Clients and invoices

• freshbooks/list-clients lists clients with optional email and updated-since filters.
• freshbooks/create-client creates a client with email, name, organization, and address.
• freshbooks/update-client updates a client you pick from a dropdown.
• freshbooks/list-invoices lists invoices filtered by client, updated-since, and status.
• freshbooks/create-invoice drafts an invoice with line items, currency, due offset, PO number, notes, and terms.
• freshbooks/update-invoice updates an invoice you pick from a dropdown.
• freshbooks/send-invoice-email emails an invoice to its recipients.
• freshbooks/create-recurring-invoice creates a recurring invoice profile.
• freshbooks/list-recurring-invoices lists recurring invoice profiles.

Money in and out

• freshbooks/list-payments lists payments recorded against invoices.
• freshbooks/create-payment records a payment against an invoice.
• freshbooks/create-other-income records income from outside your invoicing.
• freshbooks/list-credit-notes, freshbooks/create-credit-note, freshbooks/update-credit-note manage credit notes.

Expenses and bills

• freshbooks/list-expenses, freshbooks/get-expense, freshbooks/create-expense, freshbooks/update-expense, freshbooks/delete-expense manage expenses.
• freshbooks/list-expense-categories lists the categories available for coding an expense.
• freshbooks/list-bills, freshbooks/create-bill, freshbooks/update-bill manage vendor bills.
• freshbooks/list-vendors, freshbooks/create-vendor, freshbooks/update-vendor manage bill vendors.

Estimates

• freshbooks/list-estimates, freshbooks/create-estimate, freshbooks/update-estimate manage estimates.

Projects, time, and catalog

• freshbooks/list-projects, freshbooks/create-project manage projects.
• freshbooks/create-time-entry, freshbooks/update-time-entry log and correct tracked time.
• freshbooks/list-services lists billable services.
• freshbooks/list-items lists billable items.
• freshbooks/list-taxes lists the tax rates configured on the business.

Known limitations

• Registering a webhook callback is a manual API round trip because FreshBooks has no console UI for callbacks and its activation handshake happens out of band. TaskJuice does not yet register FreshBooks callbacks for you. Follow the steps under Set up webhook triggers.
• The verifier token is delivered exactly once, in the verification request. Capture it when it arrives, or use the resend flow to get a new one.
• Connections are scoped to a single FreshBooks business by accountId. To work across several client businesses, create one connection per business.
• The FreshBooks API enforces a per-account rate limit and returns HTTP 429 on burst. TaskJuice treats those responses as retryable and backs off.
• The Accounting API expects monetary amounts as { "amount": "125.50", "code": "USD" } objects with decimal strings. Action fields accept decimal strings and the integration wraps them on the wire.
• FreshBooks documents no endpoint for generating an invoice PDF, and its Checkout Links documentation carries no endpoint paths, so neither is available as an action.
• The Staff resource is deprecated in favour of Team Members and carries no filter parameters suitable for a reliable trigger, so there is no staff trigger.