FreshBooks
FreshBooks is a cloud accounting platform used to manage business memberships, clients, invoicing, and related accounting data through the FreshBooks Accounting API.
The Flowgear FreshBooks Node lets you look up account identity and manage the supported FreshBooks client operations, including query, create, update, and soft-delete flows, from a Workflow.
Revision History
0.1.1.0 - Added detached request echoes to mutation success and failure rows.
0.1.0.0 - Completed the V2 overhaul with eager first-request startup and lazy continuation.
0.0.0.5 - Aligned the V2 connector contract and public help article.
0.0.0.1 - Initial release for client query and CRUD operations.
0.0.0.3 - Added Get Identity (/me) query template, updated query template selection to use OperationId, and expanded identity validation coverage.
0.0.0.4 - Improved /me identity handling for current FreshBooks response shapes and kept query template contract aligned with OperationId-driven flow.
Connection
Use the Connection to store the OAuth application details, tokens, requested scopes, and cached membership details needed to access the selected FreshBooks account.
| Property | Type | Description |
|---|---|---|
Domain |
String | Optional compatibility field retained from existing profiles; this value is kept for profile continuity and does not use it to switch API hosts. |
Client ID |
String | OAuth client identifier from your FreshBooks app registration. |
Client Secret |
Masked | OAuth client secret from your FreshBooks app registration. |
Scope |
String | Space-delimited FreshBooks OAuth scopes requested during authorization. |
Access Token |
Masked | OAuth access token used for FreshBooks API requests. |
Refresh Token |
Masked | OAuth refresh token used to renew the access token. |
Account ID |
String | FreshBooks account ID used for accounting endpoints. |
Business ID |
String | FreshBooks business ID discovered from the identity endpoint. |
Memberships |
String | Raw FreshBooks business membership payload returned by the identity endpoint, so you can confirm or copy the correct account details. |
Setup Notes
You need a FreshBooks OAuth app registration before you can use this Node, because the connection requires Client ID and Client Secret.
Authorize the Connection to populate Access Token and Refresh Token. If Scope is blank, the Connection falls back to the built-in default FreshBooks scope set for user profile and client access.
Run the Connection Acquire Metadata and Test to refresh Memberships. If the connected identity returns one business membership, the Node can auto-select Account ID and Business ID. If multiple memberships are returned, use Memberships or the Get Identity (/me) query template to identify the correct account details.
This Node always targets the documented FreshBooks production API host.
Domainis retained only for compatibility with imported profiles.
Methods
The FreshBooks Node exposes separate Methods for client reads, creates, updates, and soft deletes. Templates provide the expected request shape for each Method.
Query
Use Query to run the List Clients, Get Client, or Get Identity (/me) template.
This Method supports a list flow, a get-by-ID flow, and a Get Identity (/me) flow. The identity flow does not require Account ID or Options, so you can use it to inspect memberships before selecting an account.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | FreshBooks Connection containing OAuth credentials and, for client operations, the selected account. |
OperationId |
String | Operation identifier supplied by the selected template. |
Options |
Object | Template-driven query options for operations that require additional inputs. List Clients supports Email, EmailLike, UserLike, OrganizationLike, UpdatedMin, UpdatedMax, and VisState. Get Client requires Options.ClientId. Get Identity (/me) does not require Options. Paging is handled internally. |
| Return | Type | Description |
|---|---|---|
Response |
Array | One output item per returned provider record. Query rows keep the FreshBooks payload together with source-backed helper fields such as accountId, clientId, providerStatus, and response, but they do not include mutation default fields. No-match queries return zero rows. If the first provider query call fails, Flowgear surfaces that FreshBooks error instead of returning an empty result. |
Create
Use Create to add one or more FreshBooks clients from typed nested client payloads.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | FreshBooks Connection containing OAuth credentials and the selected account. |
Items |
Array | One or more objects that contain a nested client object with the FreshBooks client fields to create. |
| Return | Type | Description |
|---|---|---|
Response |
Array | One output item per created client. Mutation rows include the normalized provider payload together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Update
Use Update to change one or more FreshBooks clients by ID using typed nested client payloads.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | FreshBooks Connection containing OAuth credentials and the selected account. |
Items |
Array | One or more objects that include an id value and a nested client object with the fields to update. |
| Return | Type | Description |
|---|---|---|
Response |
Array | One output item per updated client. Mutation rows include the normalized provider payload together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Delete
Use Delete to soft-delete one or more FreshBooks clients by id.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | FreshBooks Connection containing OAuth credentials and the selected account. |
Items |
Array | One or more objects that include the FreshBooks client id to delete. |
| Return | Type | Description |
|---|---|---|
Response |
Array | One output item per deleted client. Delete rows include the normalized provider payload together with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Usage Notes
- Start by selecting a Method template so the Node can show the expected request shape for that FreshBooks operation.
- Query completes the first FreshBooks request or client-list page while the Node invoke is awaited. Additional pages are fetched only as the Workflow consumes the response stream.
- Create, Update, and Delete complete the first input item while the Node invoke is awaited. Later items are consumed lazily, and an empty connected input sends no provider request.
CreateandUpdateexpect a nestedclientobject rather than raw JSON text. This keeps the request contract structured in the designer.Updateitems must not includeclient.vis_state. UseDeleteforvis_statechanges.
Known Issues
- Current release is limited to client operations. Broader FreshBooks resources are not currently supported.