Get Started with FreshBooks API

Learn to sign up for a FreshBooks account and create an application.

We'll cover the following

Overview

In this lesson, we’ll sign up for a FreshBooks account, and learn to create and authenticate an application.

Signing up and creating an application

Let’s visit the sign-up link and create an account on FreshBooks.

Once we sign up for FreshBooks, the next step is to create an application. Visit the developer page and click on the “Create New App” button. We’ll be redirected to the “Create Application” form. Here, we need to fill the following fields:

  1. Application Name: In this field, we need to give a name to our application. This is a required field.
  2. Application Type: There are three options in the dropdown list of this field: “Test App,” “Private App,” and “Public App.” Select the “Test App” option. This is a required field.
  3. Description: We need to describe the purpose of our application. We can also add a logo for our application. This is an optional field.
  4. Website URL: We need to give the URL of our website from where users can learn more about our application. This is an optional field.
  5. Application Settings URL: We need to give the settings link of our application. This is an optional field.
  6. Scope: Here, we need to add scopes to our application so it can access the information in our FreshBooks account. We click on the “Add Scope” button to add permissions. We recommend adding all permissions so that the application can access every detail. This is a required field.
  7. Redirect URIs: Here, we add a URI where we want to redirect users after they select to authenticate our application. This is a required field. We need to add the redirect URI given below:
Press + to interact
{{EDUCATIVE_LIVE_VM_URL}}

After filling these fields, we must follow the steps below:

  1. Click the “Save” button at the top of the form and create the application. After this, we’ll be redirected to the developer page, where we’ll see the created application.
  2. Click the name of our application, and get into the application settings.
  3. Scroll down to the end of the page to find “Client ID” and “Client Secret.” Copy and paste them somewhere safe.

Click the "Edit" button below. Enter the "Client ID" for SECRET_ID and the "Client Secret" for SECRET KEY. Click the "Save" button to use it throughout the course.

Press + to interact
print("Your Secret ID is:  {{SECRET_ID}}");
print("Your Secret Key is:  {{SECRET_KEY}}");
print("Your Base URL is:  https://api.freshbooks.com");
print("Redirect URL is: {{EDUCATIVE_LIVE_VM_URL}}")

Application authentication

The FreshBooks application authenticates the client once so that it can differentiate between actual and fake requests. We need to authenticate our FreshBooks application before executing any endpoint. So, let’s run the Flask server to connect to our FreshBooks application in the widget below.

Note: The bearer token for FreshBooks expires after 12 hours. We can regenerate it using this lesson.

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="refresh" content="10">
    </head>
<body>

<h1>Welcome to Freshbooks!</h1>

<p style="font-size:25px" id="token">
    {% if code is not none %}
        Your code is <strong>{{code}}</strong>.
    {% else %}
        Your code will be displayed here.
    {% endif %}
</p>

</body>
</html>
The Flask server application

We need to wait for the Flask server to start. Once we see the “Welcome to FreshBooks” message in the “Output” tab, we need to open the settings of our FreshBooks application. Then, we click “Go to authentication page.”

A new tab opens where consent for permissions access is taken. We click the “Allow” button to use the application. We only need to do this the first time we access an application. After this, we’ll be redirected to the redirection URL, where an alpha-numeric code is written. Copy this code, paste it into the code widget below against CODE, and click “Save.”

Press + to interact
import requests
from pprint import pprint
import json
data = {"grant_type": "authorization_code",
    "client_id": "{{SECRET_ID}}",
    "code": "{{CODE}}",
    "client_secret": "{{SECRET_KEY}}",
    "redirect_uri": "{{EDUCATIVE_LIVE_VM_URL}}"}
response = requests.post('https://api.freshbooks.com/auth/oauth/token', data=data)
if response.status_code != 200:
    print("Something went wrong.")
pprint(response.json())

The code above is to authenticate our application. Let’s discuss the code line by line:

  • Lines 5–9: We define the data object containing grant_type, client_id, code, client_secret, and redirect_uri.
  • Line 10: This shows the HTTP POST request
  • Line 14: We print the response using pprint.

Testing configuration and getting ACCOUNT_ID

First, let’s get details about the users in our FreshBooks account. We’ll use https://api.freshbooks.com/auth/api/v1/users/me as an endpoint to get an ACCOUNT_ID. The account ID is automatically extracted in the widget. Click the “Save” button to use it throughout the course.

Press + to interact
import requests
import json
url = "https://api.freshbooks.com/auth/api/v1/users/me"
headers = {
    'Authorization': 'Bearer {{AUTH_CODE}}', 
    'Content-Type': 'application/json'}
response = requests.get(url, data=None, headers=headers)
if response.status_code != 200:
    print("Something went wrong.")
print(json.dumps(response.json(), indent=4))