How to migrate from the Classic XML API

When moving from FreshBooks Classic to the new FreshBooks, we recommend reviewing this to ensure your custom integration can be migrated over as well. Before you start, review the list of existing integrations that already work with our API in case your custom Classic integration can be replaced with one that’s already built.

When moving to the newer API, all aspects that communicate with FreshBooks will need to be updated including:

1. Authentication Methods
2. URL Endpoints
3. Payload Format

Authentication Methods:

Classic FreshBooks supports authentication via the API token as well as OAUTH 1.0.

The newer FreshBooks only supports authentication via OAUTH 2.0.

1. Authentication will need to follow the OAUTH 2.0 protocol. Accessing data in an account will require an owner/admin/manager to  ‘allow’ access to your application within a web browser. This process only needs to be completed one time where you will gain access to an access_token and refresh_token
   
2. If your existing program relies on a static API token, the access_token can expire at any time. In the event your access_token no longer functions, your program will need provisions to use the single-use refresh_token to return a new access_token and refresh_token.
   
   For example, your custom API integration may be designed to work in this manner:
   1. Attempt an API Call with the access_token
   2. If the access_token is invalid then
      1. Use the refresh_token to fetch a new access_token and refresh_token pair
      2. Discard the old access_token and store the new access_token
      3. Discard the old refresh_token and store the new refresh_token
   3. Return to the first step and attempt the API call with the new access_token

Please see the step-by-step documentation for authentication with the FreshBooks API via OAuth 2.0

URL Endpoints:

The URL Endpoints are formatted differently in the new FreshBooks API.

Classic FreshBooks API uses:

A fixed URL for all API calls
https://yourcompanyname.freshbooks.com/api/2.1/xml-in
Part of the payload to determine the action
<request method="invoice.create">

Whereas the new FreshBooks API uses a different URL for different API actions:

The following URL can be used to return a list of invoices.
https://api.freshbooks.com/accounting/account/<accountid>/invoices/invoices

The following URL can be used to return a list of Time Entries.
https://api.freshbooks.com/timetracking/business/<business_id>/time_entries
https://api.freshbooks.com/timetracking/business/<business_id>/time_entries
To retrieve your account_id and business_id, please see The Identity Model

Payload:

The Classic FreshBooks API uses an XML payload while the new FreshBooks API uses a JSON payload. While many payloads will contain similar required fields, you will want to compare the API documentation carefully to ensure your payloads continue to work

Example: The payload for creating a client using the Classic API vs the new FreshBooks API is:

Classic Request: POST https://yourcompanyname.freshbooks.com/api/2.1/xml-in <?xml version="1.0" encoding="utf-8"?><request method="client.create"><client><email>john.doe@abcorp.com</email></client></request>

Newer API Request: POST https://api.freshbooks.com/accounting/account/<accountid>/users/clients {"client": { "email": "john.doe@abcorp.com"}}

Additional Resources

To help you check your integration, we recommend checking out the following:

1. Our postman collection for an excellent resource to see example API calls
2. Review our Python and Node.js SDKs
3. Create test accounts (also known as sandboxes), by using your developer email to sign up for a free trial account
4. Webhooks set up with the Classic API require no changes, but review our webhooks documentation when creating new ones
5. For follow-up questions, please reach out to our API team by email at api@freshbooks.com