FreshBooks
Connects to the FreshBooks Accounting API so you can inspect the authenticated identity profile, discover memberships, and query, create, update, and delete client data from a Flowgear Workflow.
Revision History
0.0.0.1 - 2026/05/08 - Initial V2 FreshBooks release for client query and CRUD operations.
0.0.0.3 - 2026/05/11 - Added the on-demand Get Identity (/me) query template, updated query template selection to use OperationId, and expanded identity validation coverage.
0.0.0.4 - 2026/05/11 - Improved /me identity handling for current FreshBooks response shapes and kept the query template contract aligned with the current OperationId-driven flow.
Connection
Use the FreshBooks connection to store the OAuth application details, tokens, requested scopes, and the accounting account ID for the FreshBooks business you want to access.
| Property | Type | Description |
|---|---|---|
Client ID |
String | The OAuth client identifier from your FreshBooks app registration. |
Client Secret |
Masked | The OAuth client secret from your FreshBooks app registration. |
Scope |
String | The space-delimited FreshBooks scopes requested during authorization. |
Access Token |
Masked | The OAuth access token used for FreshBooks API requests. |
Refresh Token |
Masked | The OAuth refresh token used to renew the access token. |
Account ID |
String | The FreshBooks accounting account ID used for /accounting requests. |
Business ID |
String | The FreshBooks business ID discovered from the identity endpoint. |
Memberships |
String | The raw FreshBooks membership payload returned by the identity endpoint so you can confirm or copy the correct account details. |
Domain |
String | An optional compatibility field retained from existing profiles. |
Setup Notes
You need a FreshBooks OAuth app registration before you can use this node, because the connection requires a Client ID and Client Secret.
Authorize the connection to populate the Access Token and Refresh Token fields. If Scope is left blank, the connection falls back to its default FreshBooks scope set for user profile and client access.
Run the connection metadata or connection test flow to refresh Memberships. If the connected identity has access to one accounting account, the node can select that Account ID automatically. If multiple memberships are returned, use Memberships or the Get Identity (/me) query template to choose the correct account details.
Methods
The FreshBooks node exposes separate methods for client reads, creates, updates, and soft deletes. Templates guide the expected request shape for each method.
Query
Use Query to list clients for the selected account, retrieve one client by ID, or load the authenticated FreshBooks identity details from /me.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The FreshBooks connection containing OAuth credentials and, for client calls, the selected account. |
OperationId |
String | The template-supplied operation identifier used to select the query shape for List Clients, Get Client, or Get Identity (/me). |
Options |
Object | Template-driven query options when the selected template requires extra inputs. List Clients supports documented filters such as email, partial email, partial user name, partial organisation name, updated date range, and visibility state. Get Client requires ClientId. Get Identity (/me) does not require Options. Paging is handled internally for client lists. |
| Return | Type | Description |
|---|---|---|
Response |
Array | One output item per returned provider record. Client templates return client rows. Get Identity (/me) returns the authenticated identity payload plus the standard status fields. |
Create
Use Create to add one or more FreshBooks clients from typed client payloads.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The 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, including the normalized status fields. |
Update
Use Update to change one or more FreshBooks clients by ID.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The 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, including the normalized status fields. |
Delete
Use Delete to soft-delete one or more FreshBooks clients.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | The 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, including the normalized status fields. |
Usage Notes
Start by selecting a method template so the node can show the expected request shape for that FreshBooks operation.
Query templates populate OperationId automatically behind the scenes. In most cases you only need to fill in the visible Options fields exposed by the selected template.
Query supports a client 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 your memberships before selecting an accounting account.
The list flow supports documented search fields such as email, partial email, partial user name, partial organisation name, updated date range, and visibility state.
Create and Update expect a nested client object rather than raw JSON text. This keeps the request contract structured in the designer.
Delete is a dedicated soft-delete operation. It sets the FreshBooks vis_state value used for deletion, so update payloads should not include vis_state.
Each emitted output item includes the default Flowgear status fields: status, statusMessage, and errorMessage. Successful items return OK, Operation completed successfully., and an empty errorMessage.
The connector always targets the documented FreshBooks production API host. The Domain connection property is retained only for compatibility with imported profiles.
Known Issues
The first FreshBooks V2 release is intentionally limited to client query and CRUD operations. Broader FreshBooks resources such as invoices and reports are not included in this version.