# 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. {% hint style="success" %} **CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform). {% endhint %} ## 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](https://my.freshbooks.com/#/developer) 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` {% hint style="info" %} **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`. {% endhint %} ### Using `sling conns` {% code overflow="wrap" %} ```bash 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 }' ``` {% endcode %} ### Environment Variable See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file. {% code overflow="wrap" %} ```bash 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" } }' ``` {% endcode %} ### Sling Env File YAML See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file. ```yaml 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: ```yaml source: FRESHBOOKS target: MY_POSTGRES defaults: mode: full-refresh object: freshbooks.{stream_name} streams: # sync all endpoints '*': ``` **Incremental sync for supported endpoints:** ```yaml 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: ```bash 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 , on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).