FreshBooks v2

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.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.
0.0.0.5 - Aligned the connector contract.
0.1.0.0 - Query and mutation Methods now run the first request when the Node runs and fetch later results as the response is consumed.
0.1.1.0 - Mutation success and failure rows now include a copy of the originating input item in Flowgear.Request.
0.1.1.2 - Maintenance release.

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. The Node always targets the FreshBooks production API host, so this value does not change the API host.
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. The default is user:profile:read user:clients:read user:clients:write.
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 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. Domain is 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 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 accountId, clientId, vis_state, and response 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 when the Node runs. Additional pages are fetched only as the Workflow consumes the response stream.
  • Create, Update, and Delete process the first input item when the Node runs. Later items are processed as the Workflow consumes the response, and an empty connected input sends no request to FreshBooks.
  • Create and Update expect a nested client object rather than raw JSON text. This keeps the request contract structured in the designer.
  • Update items must not include client.vis_state. Use Delete for vis_state changes.

Known Issues

  • The Node is limited to client operations and the Get Identity (/me) lookup. Other FreshBooks resources, such as invoices, are not supported.

See also