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 read clients, draft and send invoices, log expenses, and trigger downstream workflows the moment an invoice changes status. Each connection is scoped to a single FreshBooks business so you can keep one workspace clean across many clients.

Connect a FreshBooks account

1. Open your workspace in TaskJuice and navigate to Connections.
2. Choose FreshBooks and click Connect.
3. Sign in to the FreshBooks account that has access to your client's business and approve the requested scopes (profile, clients read/write, invoices read/write, expenses read/write, time entries read).
4. After FreshBooks returns you to TaskJuice, 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 with the access token and reading business_memberships[].business.account_id.
5. TaskJuice returns you to the workspace with the connection ready to use in any workflow.

To revoke access, open my.freshbooks.com, navigate to Settings, Apps and Integrations, find the TaskJuice app, and disconnect it. See the FreshBooks Authentication guide for the full OAuth grant flow.

Triggers

• freshbooks/invoice-updated polls the FreshBooks invoices endpoint on a configurable interval (default 5 minutes) and fires one workflow activation per cycle. The items array carries every invoice whose updated timestamp is greater than the previous watermark. FreshBooks first-party callbacks authenticate by echoing a verifier token in the request body rather than a signed header, so polling the invoices endpoint with the search[updated_min] watermark is the supported trigger shape.

Actions

• freshbooks/list-clients lists clients in the connected business with optional email and updated-since filters.
• freshbooks/create-client creates a new client record with email, name, organization, and primary address.
• freshbooks/list-invoices lists invoices filtered by client, updated-since timestamp, and v3 status.
• freshbooks/create-invoice drafts a new invoice with line items, currency, due offset, PO number, notes, and terms.
• freshbooks/create-expense records an expense with amount, category, date, vendor, and optional client and project bill-back.

Known limitations

• The FreshBooks API enforces a per-account rate limit and returns HTTP 429 with a Retry-After header on burst. TaskJuice surfaces those responses as retryable errors and honors the header.
• Connections are scoped to a single FreshBooks business (accountId). To work across multiple client businesses, create one connection per business.
• The invoice-updated trigger uses polling rather than FreshBooks callbacks because the callback verifier scheme is in the request body and does not fit the platform's declarative inbound-auth envelope. The default 5 minute interval is configurable per workflow.
• The FreshBooks Accounting API expects monetary amounts as { "amount": "125.50", "code": "USD" } objects with decimal strings. Action input fields accept decimal strings and the integration wraps them on the wire.