× Freshbooks App Logo
FreshBooks
Official App
Free - Google Play
Get it

FreshBooks API Documentation

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 in your FreshBooks developer page

Introduction

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.

Required Headers

There are three required headers for most calls:

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

We need those two to understand, properly route, and authenticate your call. The black code pane on this page shows an example of a call which sends these headers correctly.

Creating your application on FreshBooks

If you already have a FreshBooks account, login by visiting our log in page or  create an account by visiting our sign up 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.

Before you start

Here’s a quick checklist of some of the things you we require to consider any integration an A+ integration:

  1. Create a dedicated page for the integration on your website
  2. Create a dedicated link/page that can be linked to in our Integrations page which allows for easy App Enablement
  3. An Application Logo that can be used for the integration, both in-app, and in the Integrations page
  4. Create a link back to FreshBooks on your website. This link should include a description of FreshBooks
  5. Provide a description of your support hours and policies to FreshBooks
  6. The application should have easy self-serve on-boarding - meaning that FreshBooks users should be able to turn the integration on without needing to email, or speak with someone
  7. FreshBooks has various account levels which include a limited number of clients for certain users. As such, when you build an integration, you should consider building the integration for supporting all FreshBooks customers, or you should explicitly communicate which customers your integration are built for

Join the FreshBooks Developer Community!

Stay connected to the latest with the FreshBooks API by joining our mailing list

If you would like to list your application on our App Store fill the request form

Follow us on Twitter @ freshbooksdevs

Sending Invoice

curl -X PUT 
  -H "Authorization: Bearer <bearer>"
  -H "Content-Type: application/json"
  -d `{
        "invoice": {
          "email_subject": "Some Subject",
          "email_body": "sample email body",
          "action_email": true
        }
      }` 
"https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<invoiceid>"

Uploading an image into FreshBooks

curl -X POST
-H "Authorization: Bearer <bearer>"
-H "Content-Type: application/json"
--form 'content=<image_path>'
"https://api.freshbooks.com/uploads/images"

Creating a new application on Freshbooks

curl -X POST
-H "Authorization: Bearer <bearer>"
-H "Content-Type: application/json"
-d `{ 
   "name": "<app_name>",
   "redirect_uri":"<app redirect uri>",
   "description":"<app descripttion>",
   "website_url":"<link to app website>",
   "settings_url":"<link to app settings>",
   "logo_public_id":"<jwt returned from post https://api.freshbooks.com/uploads/images>"
}`
"https://api.freshbooks.com/auth/api/v1/partners/applications"

Get all aplications

curl -X GET
-H "Authorization: Bearer <bearer>"
-H "Content-Type: application/json"
"https://api.freshbooks.com/auth/api/v1/partners/applications"

Modify an existing application

curl -X PUT
-H "Authorization: Bearer <bearer>"
-H "Content-Type: application/json"
-d `{ 
   "name": "<app_name>",
   "redirect_uri":"<app redirect uri>",
   "description":"<app descripttion>",
   "website_url":"<link to app website>",
   "settings_url":"<link to app settings>",
   "logo_public_id":"<jwt returned from post https://api.freshbooks.com/uploads/images>"
}`
"https://api.freshbooks.com/auth/api/v1/partners/applications/<app_client_id>"

Sending Invoice 142571


url = "https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices/<invoiceid>"
headers = {'Authorization': 'Bearer &ltBearer Token&gt', 'Content-Type': 'application/json'}
payload = {"invoice": {
              "email_subject": "Some Subject", 
              "email_body": "sample email body", 
              "action_email": true 
              } 
          }
res = requests.put(url, data=json.dumps(payload), headers=headers)