> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maesn.com/llms.txt
> Use this file to discover all available pages before exploring further.
# FreshBooks
> Integrate Freshbooks easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `freshbooks`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :----------------------------------------------------: | :----------------------------------------------------: | :----------------------------------------------------: | :----------------------------------------------------: | :----------------------------------------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by FreshBooks
## How to connect to FreshBooks
To allow your customers to link your application with their FreshBooks accounts, you need to set up a FreshBooks App and submit your application credentials to maesn.
Before you begin, ensure you have the following:
* An active FreshBooks account.
If you do not already have a FreshBooks account, you can sign up for a free trial at [FreshBooks Sign-Up](https://auth.freshbooks.com/service/auth/integrations/sign_up). Note that this FreshBooks account will only be used to manage your FreshBooks App and, optionally, to become a FreshBooks partner in the future.
This step will guide you through creating the App that users can install in their FreshBooks account to authorize integration with your application.
* Visit the FreshBooks [Developer Portal](https://my.freshbooks.com/#/developer) and log in, if you are not already logged in.
* Click **"Create New App"**.
* Enter the following details:
* **Name**: The name of your application. This is what users will see when they are asked to authorize integration with their FreshBooks account.
* **Application Type**: Select **Public App**.
* **Website URL**: Enter the homepage URL of your company, e.g., `https://yourcompany.com`.
* **Redirect URL**: Set this to `https://api.maesn.dev/auth/callback/freshbooks`.
To enable data access for your users, you must add the following scopes to your application:
* `user:profile:read`
* `user:clients:read`
* `user:clients:write`
* `user:bill_vendors:read`
* `user:bill_vendors:write`
Click **Save** to create your application.
Once the setup is complete, click on your application to access your OAuth credentials. You will find both your OAuth Client Identifier and your OAuth Client Secret, which are required to connect to the FreshBooks API.
In the last step, we setup your API tenant with your App's details:
* Get in touch with your contact person at maesn to submit the client id and client secret.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
## Webhooks
Freshbooks supports the following parameters for webhooks:
Resources:
* `ACCOUNT`
* `CUSTOMER`
* `CREDIT_NOTE`
* `INVOICE`
* `ITEM`
* `PAYMENT`
* `SUPPLIER`
* `TAX_RATE`
Freshbooks sends `CREATED`, `UPDATED` and `DELETED` events.
The subscription is created **per customer**, which means for each customer, you will create a customized subscription for the events and resources you want to be notified about.
To set this up, call Maesn's create webhook endpoint `POST /webhooks?companyId=` (`companyId` query parameter required if not using the interactive flow) with the following example body:
```javascript Example code snippet theme={null}
const response = await axios.post(url, {
"callbackUrl": callbackUrl,
"eventType": "CREATED",
"resource": "CUSTOMER"
}, {
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
It will return the `id` associated with the subscription:
```json Example response theme={null}
{
"data": {
"id": "830251",
"callbackUrl": "https://example.com/webhook-endpoint/12345",
"createdDate": null,
"expiresDate": "null",
"secret": "2f1fd5f883d4c0adf5b31b91e4d6ae2d2975620c67bac8fdb864c78047b1d522"
"updatedDate": "null"
},
"meta": {}
}
```
At this point, your system is ready to receive end-user–related events at the callback URL you provided. The event response will provide the following information:
```json Example event body theme={null}
{
"eventType": "CREATED",
"filterDate": null, //not supported by freshbooks
"resource": "CUSTOMER",
"resourceId": "1605408d-ed88-4228-8a12-ab857a2972d8",
"userId": null //not supported by freshbooks
}
```
To delete the webhook subscription, you can call the `DELETE` `/webhooks/{webhookId}?companyId=` endpoint provinding both your `X-API-KEY` and the end user `X-ACCOUNT-KEY`.