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:
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.
Authentication will need to follow the OAuth 2.0 protocol. Accessing data in an account will require an owner, admin, or 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.
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.
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 should 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:
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:
- Our Postman collection for example API calls
- Review our Python and Node.js SDKs
- Create test accounts (sandboxes) by signing up for a free trial account
- Webhooks set up with the Classic API require no changes, but review our webhooks documentation when creating new ones
- For follow-up questions, contact our API team at api@freshbooks.com