FreshBooks

Connect & Ingest data from FreshBooks

FreshBooks is a cloud-based accounting and invoicing platform for small businesses and freelancers. The Sling FreshBooks connector extracts data from the FreshBooks REST API, supporting clients, invoices, expenses, payments, estimates, projects, time entries, bills, and more.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

The following credentials and inputs are accepted:

Secrets:

• client_id (required) -> Your FreshBooks OAuth App Client ID

• client_secret (required) -> Your FreshBooks OAuth App Client Secret

Inputs:

• account_id (required) -> Your FreshBooks Account ID (e.g., 02NWnd)

• business_id (required) -> Your FreshBooks Business ID (e.g., 14420744)

• anchor_date (optional) -> Starting date for first sync of incremental endpoints (ISO 8601 format, e.g., 2024-01-01T00:00:00Z). Defaults to 1 year ago.

Authentication

FreshBooks uses OAuth 2.0 with the Authorization Code flow. Sling handles the OAuth flow automatically, including token refresh.

1. Go to FreshBooks Developer Portal

2. Click Create an App

3. Fill in the app details:

   • Application Name: e.g., "Sling Integration"

   • Redirect URIs: Add https://slingdata.io/callback

4. Note the Client ID and Client Secret

5. Find your Account ID and Business ID:

   • Call GET https://api.freshbooks.com/auth/api/v1/users/me with an access token

   • account_id is found under business_memberships[].business.account_id

   • business_id is found under business_memberships[].business.id

Required Scopes: When authorizing, request these read scopes: user:profile:read, user:clients:read, user:invoices:read, user:expenses:read, user:payments:read, user:estimates:read, user:projects:read, user:time_entries:read, user:taxes:read, user:bills:read, user:bill_payments:read, user:bill_vendors:read, user:other_income:read, user:billable_items:read, user:business:read, user:teams:read.

Using sling conns

sling conns set FRESHBOOKS type=api spec=freshbooks secrets='{ client_id: your_client_id, client_secret: your_client_secret }' inputs='{ account_id: your_account_id, business_id: your_business_id }'

Environment Variable

See here to learn more about the .env.sling file.

export FRESHBOOKS='{ type: api, spec: freshbooks, secrets: { client_id: "your_client_id", client_secret: "your_client_secret" }, inputs: { account_id: "your_account_id", business_id: "your_business_id" } }'

Sling Env File YAML

See here to learn more about the sling env.yaml file.

connections:
  FRESHBOOKS:
    type: api
    spec: freshbooks
    secrets:
      client_id: "your_client_id"
      client_secret: "your_client_secret"
    inputs:
      account_id: "your_account_id"
      business_id: "your_business_id"

Replication

Here's an example replication configuration to sync FreshBooks data to a PostgreSQL database:

source: FRESHBOOKS
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: freshbooks.{stream_name}

streams:
  # sync all endpoints
  '*':

Incremental sync for supported endpoints:

source: FRESHBOOKS
target: MY_POSTGRES

defaults:
  object: freshbooks.{stream_name}

streams:
  clients:
    mode: incremental
    primary_key: [id]
    update_key: updated
  invoices:
    mode: incremental
    primary_key: [id]
    update_key: updated
  expenses:
    mode: incremental
    primary_key: [id]
    update_key: updated
  payments:
    mode: incremental
    primary_key: [id]
    update_key: updated
  estimates:
    mode: incremental
    primary_key: [id]
    update_key: updated
  items:
    mode: incremental
    primary_key: [id]
    update_key: updated
  bills:
    mode: incremental
    primary_key: [id]
    update_key: updated
  bill_vendors:
    mode: incremental
    primary_key: [id]
    update_key: updated
  other_income:
    mode: incremental
    primary_key: [incomeid]
    update_key: updated_at
  projects:
    mode: incremental
    primary_key: [id]
    update_key: updated_at
  time_entries:
    mode: incremental
    primary_key: [id]
    update_key: created_at
  # Full-refresh only endpoints
  expense_categories:
    mode: full-refresh
  taxes:
    mode: full-refresh
  staff:
    mode: full-refresh
  bill_payments:
    mode: full-refresh
  credit_notes:
    mode: full-refresh
  services:
    mode: full-refresh

Endpoints

Endpoint	Description	Incremental
clients	All clients	Yes
invoices	All invoices	Yes
expenses	All expenses	Yes
expense_categories	Expense categories	No
payments	All payments	Yes
estimates	All estimates	Yes
items	All billable items	Yes
taxes	Tax definitions	No
bills	Bills (accounts payable)	Yes
bill_vendors	Bill vendors	Yes
bill_payments	Bill payments	No
other_income	Other income entries	Yes
staff	Staff members	No
credit_notes	Credit notes	No
projects	All projects	Yes
time_entries	All time entries	Yes
services	Billable services	No

To discover available endpoints:

sling conns discover FRESHBOOKS

Incremental Sync

Most endpoints support incremental sync using the updated_min or updated_since parameter:

• First run: Fetches all records updated within the last year (or since anchor_date if provided)

• Subsequent runs: Only fetches records modified after the last sync timestamp

• Update key: updated for accounting endpoints, updated_at for project/time endpoints

The expense_categories, taxes, staff, bill_payments, credit_notes, and services endpoints always run in full-refresh mode since they don't support time-based filtering.

Rate Limiting

The FreshBooks API enforces rate limits. The connector automatically:

• Uses conservative rate limiting (5 requests/second with concurrency of 3)

• Retries with exponential backoff on 429 (rate limit) responses, up to 5 attempts

If you are facing issues connecting, please reach out to us at [email protected], on discord or open a Github Issue here.