FreshBooks icon

FreshBooks

FreshBooks Node

Actions22

Overview

This node operation lists clients from a FreshBooks account. It is useful for retrieving client data such as contact details, status, and creation or update timestamps. Typical use cases include syncing client lists with other systems, generating reports on active or archived clients, or filtering clients based on visibility state and sorting preferences.

For example, you might use this node to:

  • Fetch all active clients to send them a newsletter.
  • Retrieve a limited number of recently updated clients for quick review.
  • List archived clients for auditing purposes.

Properties

Name Meaning
Account ID Your FreshBooks Account ID, found in your account settings (e.g., "eNVq4").
Return All Whether to return all matching clients or limit the results.
Limit Maximum number of clients to return if not returning all (minimum 1, default 50).
Search Visibility State Filter clients by visibility: "Active" (0) or "Archived" (1).
Sort Order Order in which clients are returned:
- Updated (Newest First)
- Updated (Oldest First)
- Created (Newest First)
- Created (Oldest First)

Output

The output consists of an array of client objects under the json field. Each object represents a client with properties as returned by the FreshBooks API, typically including client details like name, contact info, visibility state, creation and update timestamps, and other metadata.

No binary data is output by this node operation.

Example output snippet (simplified):

[
  {
    "json": {
      "id": 123,
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "vis_state": 0,
      "created_at": "2023-01-01T12:00:00Z",
      "updated_at": "2023-06-01T08:30:00Z"
    }
  },
  ...
]

Dependencies

  • Requires a valid FreshBooks account with an API key credential configured in n8n for authentication.
  • The node uses the FreshBooks REST API endpoint /accounting/account/{accountId}/users/clients.
  • Network access to https://api.freshbooks.com must be available.

Troubleshooting

  • Invalid Account ID: If the provided Account ID is incorrect or missing, the API will fail to return clients. Verify the Account ID in your FreshBooks account settings.
  • Authentication Errors: Ensure the API key or OAuth2 credentials are correctly set up and have sufficient permissions.
  • Empty Results: If no clients are returned, check the visibility filter (Search Visibility State) and sorting options. Also verify that clients exist in the specified state.
  • Limit vs Return All: Setting Return All to false but specifying a very high Limit may cause partial results due to API pagination limits. Use Return All to fetch all clients reliably.
  • API Rate Limits: Frequent requests may hit FreshBooks API rate limits; implement delays or reduce request frequency if errors occur.

Links and References

Discussion