Introduction

The FreshBooks API is an interface for accessing your FreshBooks account data using HTTP and XML. The API makes it easy to create web and desktop applications that integrate with your account.

Some potential application ideas:

• Custom import tools (SalesForce, QuickBooks, CSV, etc.)
• Automatic invoice creation from your web site
• Revenue analysis
• External integration with online payment gateways

To enable API access for your account, login as the administrator and follow these steps:

1. Select “settings” at the upper-right corner of any page.
2. Under “step 3,” choose “enable FreshBooks API.”
3. Read our terms of service, and then select the box indicating you agree.

Service URL

The FreshBooks API has a single point of entry, derived from your account URL:

https://sample.freshbooks.com/api/2.1/xml-in

Please note the use of https:// in the URL above. All FreshBooks API communication is encrypted over HTTPS. Any non-secure requests are automatically rejected, so we recommend establishing a test connection with the secure API entry point before sending sensitive data.

Authentication

After enabling API access for your account, you’ll be given a unique authentication token. For every API request you make, you’ll need to present this token using basic HTTP authentication. The admin user, and each staff member, has an API token. The admin user’s authentication token can be found on the “enable FreshBooks API” page. The staff token can be found on each staff member’s Profile page, or on the Edit Staff page (for admin only). At this time, staff members have limited access to the API (see the individual method pages for details).

Please note your authentication token is based on your account password. If your password changes, so will your authentication token.

HTTP authentication traditionally takes a username/password pair, but since we’re dealing with a single token, you’ll only use the username field. If your HTTP library requires a password as well, just use an arbitrary string — like “X”.

Here’s an example authenticated request made with cURL:

curl -u insert_token_here:X https://sample.freshbooks.com/api/2.1/xml-in -d ‘[xml body here]’

Keep this token secret. It should be guarded just as you would your regular account password. If you feel your token has been compromised, you can reset it by changing your administrative password.

Lastly, we also ask you use a unique User-Agent string to identify your application and/or organization.

Representation Formats

All FreshBooks API requests are composed of light-weight XML delivered as an HTTP POST request to the endpoint URL.

• All XML should be UTF-8 encoded.
• Date and time values are of the form YYYY-MM-DD HH:MM:SS.
• Booleans are either 1 (true) or 0 (false).
• Fields denoting percentages are passed as whole values, not decimals (e.g. 5 for five percent).

Sample request

<?xml version="1.0" encoding="utf-8"?>
<request method="[method name]">
  [method arguments]
</request>

All responses are wrapped in a top-level request element. The status attribute will let you know whether the request succeeded or failed.

Successful response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
    [return value(s) here]
</response>

In the case of a failure response, the response body will contain one or more error messages.

Unsuccessful response

<?xml version="1.0" encoding="utf-8"?>
<response status="fail">
  <error> ... </error>
</response>