> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FreshBooks

> Integration details and setup guide for the FreshBooks connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                     |
| ----------------------------------- | ----------------------------------------------------------- |
| **Authentication**                  | Bearer Token (OAuth 2.0)                                    |
| **Two-Way Sync**                    | Yes                                                         |
| **Events Supported**                | Yes (Webhooks)                                              |
| **Realtime**                        | Yes                                                         |
| **Supports Rate Limiting**          | Yes                                                         |
| **Authentication Scopes Supported** | N/A (OAuth token provides access based on user permissions) |

***

## Objects Supported

Alloy Automation supports syncing the following objects from **FreshBooks**:

* **Account Info**
* **Accounts**
* **Balance Sheet**
* **Cash Flow Rate**
* **Clients**
* **Estimates**
* **Expenses**
* **Invoices**
* **Items**
* **Payments**
* **Projects**
* **Tasks**
* **Time Entries**
* **Taxes**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                                                                       |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Offers free trial?**                             | Yes. FreshBooks offers a 30-day free trial with full access to features. Sign up at [https://www.freshbooks.com](https://www.freshbooks.com) to get started. |
| **Requires requires paid sandbox**                 | No paid sandbox required. You can use the trial account for testing.                                                                                         |
| **Requires partnership to obtain authentication?** | No. OAuth credentials can be obtained directly from the FreshBooks Developer Portal.                                                                         |

***

### Authentication (OAuth 2.0)

For customers who want to completely whitelabel their OAuth experience, you can provide your own developer keys instead of using Alloy Automation's.

1. Go to **FreshBooks Developer Portal** at [https://www.freshbooks.com/developers](https://www.freshbooks.com/developers).
2. Sign in with your FreshBooks account and navigate to **My Apps**.
3. Click **Create App** and fill in the required information:
   * App name
   * Description
   * Website URL
4. Add the redirect URI: [https://api.runalloy.com/api/strategy/connector/freshbooks/callback](https://api.runalloy.com/api/strategy/connector/freshbooks/callback)
5. Copy your **Client ID** and **Client Secret**.
6. Enter your **Client ID** and **Client Secret** into Alloy Automation.

#### OAuth Scopes

FreshBooks OAuth provides access based on user permissions. The authenticated user's access level determines what data and operations are available through the API.

#### API Documentation

For detailed API documentation, visit: [https://www.freshbooks.com/api/start](https://www.freshbooks.com/api/start)

#### Important Notes

* FreshBooks uses OAuth 2.0 for authentication
* Access tokens expire and must be refreshed using refresh tokens
* The API provides access to accounting data, invoicing, expense tracking, and time tracking
* Multi-business accounts may require additional configuration

***

## Use Cases

### 1) Invoice automation

Automatically create and send FreshBooks invoices when orders are completed in your ecommerce platform or project milestones are reached in your project management system.

### 2) Expense tracking

Sync expenses from corporate credit cards, receipt scanning apps, or travel booking systems into FreshBooks for automated expense categorization and reimbursement.

### 3) Time tracking integration

Push time entries from project management tools or time tracking apps into FreshBooks for accurate client billing and project profitability tracking.

### 4) Payment reconciliation

Automatically record payments in FreshBooks when they're received through payment gateways like Stripe or PayPal, keeping financial records in sync.

### 5) Financial reporting

Pull accounting data from FreshBooks into business intelligence platforms to create custom financial reports and dashboards combining data from multiple sources.

***

## API Gotchas

* **Account ID requirement:** Most FreshBooks API calls require an account ID parameter. You'll need to fetch the account ID after authentication before making other API calls.
* **OAuth token refresh:** Access tokens expire regularly. Implement token refresh logic to maintain continuous access without requiring re-authentication.
* **Rate limiting:** FreshBooks enforces rate limits on API requests. Monitor response headers and implement exponential backoff when rate limits are hit.
* **Webhook retries:** FreshBooks webhooks will retry failed deliveries. Ensure your webhook endpoint is idempotent to handle duplicate deliveries gracefully.
* **Multi-currency support:** FreshBooks supports multiple currencies. Always check and handle currency codes properly when working with invoices and payments.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.