FreshBooks API

Number of APIs: 182

Quick Start

The column on the right hand side has a curl call that demonstrates the required Headers and general format of requests to the FreshBooks API.

Requests are authenticated using OAuth2 Bearer tokens which you receive in exchange for a code we issue after a logged-in user performs an authorization grant request. You can create an OAuth application and get a client_id and secret at the developer page.

The FreshBooks API is an interface for accessing your FreshBooks data using JSON. The API makes it easy to create web and desktop applications that integrate with your account. Possible uses for it include automatically creating and sending invoices when users sign up on your website, pulling lists of client information, copying data to 3rd party services, and more...

Check out our Scenarios and API Reference sections to see what to expect, and when you're ready, sign up for a FreshBooks account if you don't have one, and proceed to the developer page to create an application and start development.

Oh, and we're not trying to be secretive about the URL of the developer page, it's: https://www.my.freshbooks.com/#/developer

Creating your application on FreshBooks

Create an account by visiting our sign up page. If you already have a FreshBooks account, log in by visiting our log in page. You can reach out to our support team to have your account put on our partner plan.

1. Now visit the developer page and create a new app.
2. Make sure to include the name of the application and redirect URI in the application form.
   The name of the application has to be unique as it will be used to display on the FreshBooks app store and on a FreshBooks user’s integrations page once they have connected with your application. The redirect URI should be an endpoint in your application that will receive the authorization code and will use it to retrieve the bearer token and refresh token. These will be necessary to make authenticated calls to the FreshBooks API. To get more information on our authentication process visit our Oauth documentation.
3. Save your application.

Required Headers

There are two required headers:

1. Content-Type: application/json
2. Authorization: Bearer

Getting Help

If there’s no one around to help, we’ve got your back. Shoot us an email at api@freshbooks.com and tell us what you’re aiming to accomplish, what you’ve done so far, and what went wrong. Maybe we can find the missing piece of the puzzle together.

Identity Model

FreshBooks users are uniquely identified by their email across our entire product. One user may act on several Businesses in different ways, so if leafy@example.com is an Administrator of one account and gets added as a Client on another, they will have some access to both. They could then open a second business of their own, or be added as an employee of another person’s business—we live complicated lives! Our Identity model is how we keep track of it.

Account IDs & Business IDs

You can find ids for the Businesses and Accounts a user can interact with by making a call to the Identity Info endpoint (or /me). An example of its response is in the code pane on the right. The key we care about most is business_memberships.

All of the business objects listed in the business_memberships will have an accountId as well as a role on that business (see Roles below). Those business objects also each have an id which is the business_id. Be careful not to mistake the business’s id for the id of the business_membership object itself.

For example, in the Identity Info (/me) response:

"business_memberships": [
{
    "id": 111,
    "role": "owner",
    "business": {
        "id": 240340,
        "business_uuid": "046cc001-0002-e93e-1db1-1186b2983879",
        "name": "Awesome Business Inc.",
        "account_id": "ABC123",
        "date_format": "dd/mm/yyyy",
        "active": true
    }
}

You can see that the user is an owner on this business which has a business_id of 230340 and an account_id of ABC123.

Acting on a Specific Account

For historical reasons, FreshBooks has shifted from an account concept to a business concept, but many resources still make use of accountIds.

Calls to the /accounting endpoints take this form:

• /accounting/account/{accountId}/invoices/invoices

Calls to most non-accounting resources, such as the /timetracking/ and /projects/ endpoints usually require a business_id, for example:

• /timetracking/business/{business_id}/time_entries

All FreshBooks users have an Identity and a Business resource and thus a business_id. Most users have accounts, which represent their own FreshBooks account, but not all. For instance, when a Client receives an invoice, views it, and saves it, they will exist as an Identity in our system with a client Role on a Business, but they do not have an Account of their own. If you know your integration will never need to deal with someone who is just a Client and doesn’t have their own Account, you can ignore this. If you aren’t sure of that, you must gracefully handle the case where you cannot find an account for a user.

Roles

Over time the logical role names that FreshBooks utilizes have diverged slightly from the names they are given in the FreshBooks application. Below are the relationships.

CONCEPTS AND IDEAS

Adding a Logo to your Invoice

In order for you to add a logo to your FreshBooks invoice, you will need to do it in two steps.

1. Upload your logo to your FreshBooks account using the Uploader endpoint
2. Apply your logo to your invoice

Uploading your Logo

Using the Uploader endpoint, add your .png or .jpg file. Your response will contain a jwt value. Take that value and add it to your GET call for your new invoice.

You can now use the POST Single Invoice (or Update Invoice) endpoint to apply your logo to an invoice. You will need to add your jwt token under presentation at img_src_logo.

Note: The presentation payload also allows you to set colours based on hex code, change the style of your invoice and a few other customizable options.

Adding a Receipt to your Expense

This process is similar to adding a logo to an invoice. You will first need to upload the expense image via the uploader endpoint (See the Qodex call for the Uploader). You will then receive back a response with the jwt key and it's associated value.

You will use then add this value in your POST body to add this newly uploaded receipt to an expense. For an example, check out the Expenses folder below.

Adding a Payment Gateway to your Invoice

To add a payment gateway to your invoice you will first need to make sure that you have gone through the Know Your Client process in FreshBooks. This will ensure that you comply to the Terms of Service with either/both of our payment processors, Stripe and FreshBooks Payments. This process will require you to sign up for an account, fill in your business and banking details, tell them what type of business you're managing and how often you would like to have funds deposited into your bank account.

Once you have gone through the KYC process, you can then toggle online payments on an invoice by making a POST call to the payment_options endpoint for the gateway of your choice. For an example of this, look under invoices and choose the POST call for Enable Payment Options On Invoice.

Getting a Shareable Link to your Invoice

To create a shareable link for your invoice, you need to add an share_link?share_method=share_link parameter to the end of your GET call for the invoice you are looking to share. You will need to make sure the invoice has already been marked as sent. If you want to mark an invoice as sent you can simply follow the steps under invoices (Hint: adding "status" as 2 to the body of your PUT call should do the trick.)

Getting all the Includes Parameters

Our Includes parameters allow for additional payloads to be added to your existing call, but are hidden unless explicitly called for.

All the Includes parameters associated with your calls can be found in one of the LIST examples posted below. For example, if you want to see the associated Includes parameters for an invoice, simply click on the List Invoices. You will see a list of available Includes a description related to each of them.

Error Codes

1. Authorization - List User GET https://api.freshbooks.com/auth/api/v1/users/me

2. Authorization - Revoke Refresh Token POST https://api.freshbooks.com/auth/oauth/revoke

3. Clients-Credits - List Credits GET https://api.freshbooks.com/accounting/account/{{accountId}}/credit_notes/credit_notes

4. Clients-Credits - Create Prepayment Credit POST https://api.freshbooks.com/accounting/account/{{accountid}}/credit_notes/credit_notes

5. Clients - Update Client PUT https://api.freshbooks.com/accounting/account/{{accountId}}/users/clients/{{customerId}}

6. Clients-Credits - Update Credit Note PUT https://api.freshbooks.com/accounting/account/{{accountid}}/credit_notes/credit_notes/{{creditnote}}

7. Clients-Credits - Delete Credit PUT https://api.freshbooks.com/accounting/account/{{accountId}}/credit_notes/credit_notes/{{creditId}}

8. Clients - List Clients GET https://api.freshbooks.com/accounting/account/{{accountId}}/users/clients

9. Clients - Single Client GET https://api.freshbooks.com/accounting/account/{{accountId}}/users/clients/{{customerId}}

10. Clients - Delete Secondary Contact ID DELETE https://api.freshbooks.com/accounting/account/{{accountid}}/users/contacts/{{contactid}}