Overview

Pre-built tooling

Pre-built integrations

No pre-built integration yet (time to contribute: <48h)

Not seeing the integration you need? Build your own independently.

Access requirements

Pre-RequisitesStatusComment
Paid dev account✅ Not requiredFree FreshBooks account is sufficient for development.
Paid test account✅ Not requiredFree FreshBooks account is sufficient for testing.
Partnership✅ Not required
App review✅ Not requiredNo review process for OAuth apps.
Security audit✅ Not required

Setup guide

1

Create a FreshBooks account

  1. If you don’t already have a FreshBooks account, go to FreshBooks’ signup page and create one.
  2. Sign in to your FreshBooks account.
2

Access the developer portal

  1. Go to the FreshBooks developer page.
  2. Click on the “sign up” link to access your FreshBooks account.
  3. Navigate to the developer portal by clicking on “the developer page” link.
3

Create a new OAuth application

  1. In the developer portal, click on Create Application.
  2. Fill in the required information for your application:
    • Application Name: Enter a name for your application.
    • Application Description: Provide a brief description of what your application does.
    • Company Name: Enter your company name.
    • Application Website: Enter the URL of your application’s website.
4

Configure OAuth settings

  1. In the OAuth settings section, add the following redirect URI:
    • https://api.nango.dev/oauth/callback
  2. Select the appropriate scopes for your application based on your needs. Common scopes include:
    • user:profile:read - Read user profile information
    • user:clients:read - Read client information
    • user:invoices:read - Read invoice information
    • user:invoices:write - Create and update invoices
    • user:estimates:read - Read estimate information
    • user:estimates:write - Create and update estimates
    • user:expenses:read - Read expense information
    • user:expenses:write - Create and update expenses
  3. Save your application settings.
5

Obtain your OAuth credentials

After creating your application, you’ll receive:

  • Client ID: A unique identifier for your application
  • Client Secret: A secret key for your application

Make sure to store these securely, especially the Client Secret, as you’ll need them when configuring your integration in Nango.

6

Configure your integration in Nango

When setting up your FreshBooks integration in Nango:

  • Use your Client ID and Client Secret from the previous step
  • For the authorization URL, use: https://auth.freshbooks.com/oauth/authorize
  • For the token URL, use: https://api.freshbooks.com/auth/oauth/token
7

Understand the OAuth flow

The FreshBooks OAuth flow follows these steps:

  1. Users are redirected to FreshBooks’ authorization page
  2. Users log in to FreshBooks and approve access for your application
  3. After authorization, users are redirected back to your redirect URL with an authorization code
  4. Your application exchanges this code for an access token using the token endpoint
  5. The access token is used in the Authorization: Bearer {access_token} header for all API requests
  6. FreshBooks also provides a refresh token that can be used to obtain a new access token when the current one expires
8

Test the OAuth flow

  1. After configuring your integration in Nango, test the OAuth flow to ensure it works correctly.
  2. The authorization flow will redirect users to FreshBooks where they can approve access to their account.
  3. After approval, users will be redirected back to your application with an authorization code.
  4. This code will be exchanged for an access token that can be used to make API requests.
9

Next

Follow the Quickstart.

Need help getting started? Get help in the community.

Common Scopes

ScopeDescription
user:profile:readRead user profile information
user:clients:readRead client information
user:clients:writeCreate and update clients
user:invoices:readRead invoice information
user:invoices:writeCreate and update invoices
user:estimates:readRead estimate information
user:estimates:writeCreate and update estimates
user:expenses:readRead expense information
user:expenses:writeCreate and update expenses
user:payments:readRead payment information
user:payments:writeCreate and update payments
user:projects:readRead project information
user:projects:writeCreate and update projects
user:time_entries:readRead time entry information
user:time_entries:writeCreate and update time entries

API gotchas

  • FreshBooks API endpoints are account-specific. The account ID is required for most API calls and is included in the URL path.
Contribute API gotchas by editing this page