Freshbooks

FreshBooks is a web-based SaaS accounting software operated by 2ndSite Inc. This software is primarily used for small and medium-sized businesses. FreshBooks is designed for helping companies to handle their finances easily and securely. With the help of this software, you can effectively manage all your expenses, invoices, reports, and time-tracking process.

1 Authorization
- 1.1 Basic Auth
- 1.2 OAuth 2.0 and API key Authentication
2 FreshBooks Connections
- 2.1 Basic Auth Connection
- 2.2 API Key Connection
- 2.3 OAuth 2.0 Connection
3 Actions
- 3.1 Get Invoices
- 3.2 Get Clients
- 3.3 Create Invoice

Authorization

Basic Auth

The basic access authentication process is an HTTP-based authentication approach to secure the REST APIs. This process uses a format to encode usernames and passwords, both are stored in the HTTP header. With this basic access authentication manner you will need to provide a username and password while making the API request. When making the API request you will require basic authentication, one of the required components of the request is a header key and value. The examples are mentioned below:

Authorization: Basic X

The header key is the right of the colon : Authorization
The header value is the left of the colon: Basic X

X should be replaced with the Base64 encoded version of the users credentials and it is the only value that needs to be replaced in this header.

Key	Description	Example

Key	Description	Example
Username	The Username would be your customer email address that is required for configuring the Freshbooks.	Sample@sapper.ai
Password	A password security is using in Freshbooks for your customers. A password must contain a minimum of 8 characters and must not contain the username.	*********************************

curl -L -X GET 'https://api.freshbooks.com/accounting/account//users/clients/' \
-H 'Authorization: Bearer <insert-bearer-token>' 
#Response:
{
    "response": {
        "result": {
            "client": {
                "accounting_systemid": "LJArJ4",
                "allow_email_include_pdf": false,
                "allow_late_fees": true,
                "allow_late_notifications": true,
                "email": "email1@freshbooks.com",
                "fname": "first1",
                "id": 238951,
                "language": "en",
                "signup_date": "2022-01-05 12:17:11",
                "updated": "2022-01-05 07:17:12",
                "userid": 238951,
                "username": "first1last13",
                "uuid": "366f3657-38ed-4cc1-832b-c3a8de9c8c16",
              }

For more information visit : Basic Auth Documentation

OAuth 2.0 and API key Authentication

The FreshBooks application use OAuth 2.0 authorization code grant flow for the authentication purpose. This authorization framework is required for enabling applications to obtain limited access to the customers or users over the HTTP. To conduct this authentication process you will need Scope, Redirect token, Refresh token and Credentials.

The scope of OAuth 2.0 can limit the FreshBooks application’s access to a user’s account. FreshBooks can request for one or more scopes, the access token issued to the application will have a limited granted scope. In FreshBooks, we use scopes for ensuring your application only access to the specific resources that are allowed by the FreshBooks user. The scope is a major part of the API calls, as when you make an API call without a sufficient scope, you will get an HTTP errors with the Status Code 403. If you get this error, you need to check for the two things mentioned below:

The scopes you provided
The scopes needed for the API call

We suggest you to create a duplicate app from the developer portal for making successfully API calls based on the requirement of the production app. You need to make a note of all the scope that is required to run your application successfully. Once the required scope is identified, you can edit your application to add the scopes. Now you need to test it for final confirmation. After the successful verification, you will be able to make the required API calls to successfully run your app. It will allow you to edit the production app to add the necessary scopes.

To authenticate you will get an Authorization URL generated by FreshBooks. This will link you to a custom Authorization page that FreshBooks hosts with the Client ID of your app associated with it. FreshBooks will ask you to enter their FreshBooks credentials in order to give you access to connect your app to their account.

Once you logs in and clicks "Authorize Access", the authorization server will redirect the user back to your page/app (using the Redirect URI you entered in the App creation) with this code attached to it. As you own that site, you can query the request parameters, take the code of the user (which is always changing depending on the user), attach the Client ID and Client Secret of the app and redirect URI (all static and unchanging in your app) and exchange it for an Access Token and Refresh Token in FreshBooks. Your app can now use the Access Token and Account ID to identify the user and prove you have been given permission make changes on the user's behalf. The Access Token will expires in 12 hours , so you can use your Refresh Token (which never expires, but can only be used once) to get a new Access Token and keep going.

Key	Description	Example

Key	Description	Example
Client ID	A Client ID is an identifier associated with FreshBooks that assists with client / server OAuth 2.0 authentication.	Wg186378Qhklc990
Client Secret	A client secret is a secret known only to your application and the authorization server. It protects your resources by only granting tokens to authorized requestors.	***************
Access Token	A credential that can be used by an application to access an API. Access Tokens can be either an opaque string or a JSON Web Token (JWT)
Refresh Token	A refresh token is a special token that is used to obtain additional access tokens. This allows you to have short-lived access tokens without having to collect credentials every time one expires.
Authorization URL	An authentication token allows internet users to access applications, services, websites, and application programming interfaces (APIs) without having to enter their login credentials each time they visit.	The authorization URL is usually in a format https://authorization-server.com/oauth/authorize .

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. As soon as your app receives the authorization code, you must request a access token using the code parameter retrieved above along with your client_id, client_secret, redirect_uri. The authorization code will expires in 5 minutes. You will receive an access(bearer) token and a refresh token in the response below. Make sure to store the refresh token securely to be retrieved later.

To access the FreshBooks you need to use the access token, it’s also known as a bearer token to make FreshBooks API call on behalf of the user. When making API calls you can pass the authorization by including a header in your api calls with the format Authorization : Bearer <YOUR_ACCESS_TOKEN>

#Response:
{
    "access_token": "some letters and numbers",
    "token_type": "Bearer",
    "expires_in": 43199,
    "refresh_token": "some letters and numbers",
    "scope": "user:profile:read user:bills:read user:bills:write user:bill_payments:read user:bill_payments:write",
    "created_at": 1643894208
}
curl -L -X POST 'https://api.freshbooks.com/auth/oauth/token' \
--data-raw '{
  "grant_type": "refresh_token", 
  "client_id": "YOUR_APP_CLIENT_ID",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "client_secret": "YOUR_APP_CLIENT_SECRET",
  "redirect_uri": "YOUR_APP_HTTPS_REDIRECT_URI"
} '

You can continue to keep making API calls with the access token until it expires. When the access token expires and you make an API call, you will get an http error status 401 unauthorized. This means that you need a new access token. If you receive the error message you will use the refresh token you stored earlier and request for a new pair of access & refresh tokens.

When you see the response below, you will have a new pair of access and refresh tokens. You can replace the previous refresh token with the new one. When you received the token, it will continue creating API calls with the new access token. As you see in the response below, you now have a new pair of access & refresh tokens. Replace the previous refresh token with the new one you just received and continue making API calls with the new access token.

For more information please visit OAuth 2.0 FreshBooks Document

FreshBooks Connections

Basic Auth Connection

Input	Key	Description	Example
Select application	application	Select FreshBooks application	FreshBooks
Connection type	connection type	Select the type of connection.	REST
Rest connection type	Rest Connection Type	Select the Basic connection type	Basic
Connection name	name	Provide a name for the connection.	FreshBooks
Connection description	description	Provide a description for the connection.
Host name	host	Provide a string value for the URL of the user's FreshBooks account.
Username	username	Provide a valid username for the given FreshBooks account.	exampleUser
Password	password	Provide a password to authenticate all requests with. Cloud users need to generate an API token for this value.	exampleSecurePassword
Header field	header	Provide the path of the endpoint for authentication.	Authorization
Header prefix header	header prefix	Select the header prefix - Basic, Bearer, Token, None

API Key Connection

Input	Key	Description	Example
Select application	application	Select FreshBooks application	FreshBooks
Connection Mode	mode	Select custom connection mode	Custom
Connection type	connection type	Select the type of connection.	REST
REST connection type	rest connection type	Select the type of REST connection.	API Key
Connection name	name	Provide a name for the connection.	FreshBooks connection
Connection description	description	Provide a description for the connection.
Host name	host	Provide a string value for the URL of the user's FreshBooks account.
Key	key	Provide the key for the connection.
Value	value	Add the value for the connection
Header Parameter	header	Header parameters are used for user-defined custom HTTP headers for a request.
Query Parameter	query	Query parameters are a defined set of parameters attached to the end of a URL.

OAuth 2.0 Connection

Input	Key	Description	Example
Select application	application	Select FreshBooks application	FreshBooks
Connection type	connection type	Select the type of connection.	REST
REST connection type	rest connection type	Select the type of REST connection.	OAuth2.0
Connection name	name	Provide a name for the connection.	FreshBooks connection
Connection description	description	Provide a description for the connection.
Host name	host	Provide a string value for the URL of the user's FreshBooks account.
Grant type	grant type	Provide the grant type - authorization code, password, client credentials.

Actions

Get Invoices

Get invoice details | key: getInvoices

Key	Description	Example

Key	Description	Example
Account ID	Provide the account id for processing the invoices.	Qvhd89g2vh79jdvy570

Get Clients

Get client details | key: getClients

Key	Description	Example

Key	Description	Example
Account ID	Provide the account id associated with a specific client.	Qvhd89g2vh79jdvy570

Create Invoice

Create invoice| key: createInvoice

Key	Description	Example

Key	Description	Example
Account ID	Provide the account id for processing the invoices.	Qvhd89g2vh79jdvy570
Create Date	Mention the date of invoice creation.	12/09/2022
Customer ID	Provide the customer id associate with the particular client.	`712052`