We now have several new apps that interact with FreshBooks. It’s great to see this kind of work starting to happen!

• Andrew finally had enough of seeing people enjoy the OSX widget and wrote a time-tracking gadget for the Vista Sidebar based off of the OSX widget! Not only does our widget provide a place for others to start, but we’re also going to help Andrew make it look pretty.
• Joel has written GetFresh, a new way for your clients to log into their FreshBooks accounts in order to pay you faster. For a small fee, you can download and configure the app, then send it to your customers. They can fill in their username and password, and with 2 clicks can be logged right into FreshBooks. Joel’s also included a screencast showing how to configure things.

Remember that the above apps are from 3rd parties, and FreshBooks is not responsible for their content or functionality. We’re just happy that people are building useful things for everyone, and want to share the news with everyone.

If you’ve got an idea for a widget, gadget, app, or script that would make your life easier, all I can say is that there is no time like the present. The API is here, it’s alive, and I’ll be kicking it into shape for you.

Once you’ve got your app running, you can count on us to take notice, and let everyone know about the excellent job you’ve done. We’re rooting for you!

We’re happy to announce that we’ve extended the FreshBooks API to allow staff access to time tracking functions! Yes, that includes our OSX Widget, and other time tracker add-ons.

Notable features

• Each staff member receives a unique API token, just like the admin user. This identifies the staff member for any actions he or she takes via the API.
• We speak the same great API for both staff and the admin account! This means that time trackers that work with the admin account should continue to work seamlessly for your staff members.
• We respect the access restrictions you’ve set. Your staff members will be able to view and edit the same information (no more, and no less) through the API as they would be able through the application itself.
• This change shouldn’t affect any API applications you already had running. If it does, let us know!

How to find your staff token

First of all, the admin user has to enable the FreshBooks API. Then any staff member can browse over to his or her Profile page (link at the top, beside Help and Logout). The token and access URL will be displayed at the bottom of the page. The admin user can also find any staff member’s token, by Editing the staff member in question.

Caveats

Of course, there are always caveats. In order to release this feature as soon as possible for your use–while maintaining the same security you expect from FreshBooks–we’ve only implemented the client, project, task, and time_entry API methods. Staff members trying to access unimplemented features will receive an API error response.

And more!

We’ve made a few other updates to the API:

• client.get now returns the client’s current credit balance
• project.list and task.list now only return active, non-archived items, just like you expect when tracking time in your browser.

We’ll be updating the API docs today to reflect these changes. So go forth and track time, and let us know what you think. Enjoy!

You may have noticed that we recently released the FreshBooks Time Tracker widget. What you may not have noticed beneath its shiny exterior, is this fantastic helper library called jQuery. Here are some excellent reasons for using it…

Portability

While the FreshBooks widget is currently only for OSX’s Dashboard, a lot of the HTML element access and glitzy fades are pure jQuery, and should be portable to other widget facilities, and the FreshBooks website itself. It’s also nice to be able to use the same skills in widget creation as webpage creation.

Power

The $() construct is much, much more powerful than it at first appears. Take a closer look at the full power of selectors to see what I mean. And the skills you learn are re-usable, since jQuery implements CSS3-style selectors. When browsers get around to fully supporting them, you’ll already be at home. In addition, jQuery also makes dealing with XML (as returned by the FreshBooks API) and Ajax in general a whole lot easier!

Conciseness

jQuery also leads to shorter, more concise JavaScript. $("#submit") is so much easier to type than document.getElementById("submit"), and infinitely more flexible when you want to, say, operate on all of the images in a page with $("img"). You “chain” together various jQuery commands, such as css() and show() simply by applying them to the returned “wrapped set”, like $("img").css('opacity',0.5).

Peer Pressure

Apparently I’m not the only one who thought this would be a good idea. I just recently noticed an awesome SVN notifier widget which also includes jQuery. Perhaps the idea is catching on…

Howdy folks - a couple of small API changes to announce:

• invoice.get and invoice.list now return <recurring_id/>
• project.list can now be filtered by <task_id/>
• time_entry.create rounds hour values to hundredths of an hour (just like the web interface)
• Raised maximum request limit to 5000 requests/day
• A handful of other bug fixes and tweaks

As always, if you have questions or comments, please let us know on the developer forums.

The other day I was investigating an odd error using our development version of FreshBooks in Safari. Lines in an invoice were being reset in an odd way, and I couldn’t add more lines to an invoice as I was creating it. This worked perfectly in FireFox, but not in Safari.

Of course, the first step was to look at the page source. However, the page source looked entirely correct. All of the form elements were defined in the correct places, with the expected order. This is where fantastic tools like Web Inspector (found in the Safari Debug menu) and Firebug come in handy. On reproducing the bug, I managed to SEE the offending tag in its new location in the Web Inspector view. A whole set of input tags sitting at the start of a table!

It turns out that if you replace a table inside a div tag, Safari does some reparsing of your provided HTML. Say, you put a hidden input tag within a tr, but outside of a td. Normally this works fine, and document.forms[0].elements[] shows up in the way you’d expect. But when replacing the table via something like innerHTML, it barfs because the ONLY things allowed in a tr tag are th or td. Thus speaks the XHTML 1.0 transitional DTD:

<!ELEMENT tr (th|td)+>

What appears to happen, is that any input elements outside of a td get bubbled up the DOM until they find a place where they are allowed…in this case, immediately before the enclosing table.

Hence, you get strange results with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'></td>" +
" <input type='text' value='Second'></tr>" +
"</tbody></table>";

But not with:

myDiv.innerHTML = "<table border='1'><tbody>" +
"<tr><td><input type='text' value='First'>" +
" <input type='text' value='Second'></td></tr>" +
"</tbody></table>";

Hence, when adding form elements improperly, programmatically, and referencing them with document.forms[].elements[], you get Very Strange results.

So please, for your own sanity’s sake, nest your elements properly!

Afternoon gang! We’ve got a couple new API feature announcements to kick off 2008 - just 3 weeks after our last release.

Paging Metadata

Now when you submit an API request that returns more than one object (i.e. all *.list methods), you’ll also be returned paging metadata that describes the result set. This should help you better navigate large data sets returned by the API.

Here’s a sample new response from invoice.list:

<?xml version="1.0" encoding="utf-8"?>
<response status="ok">
  <invoices page="2" per_page="5" pages="8" total="37">
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
    <invoice>...</invoice>
  </invoices>
</response>

Now, we think this is a swell improvement, and our users have been pining for it. But it comes at a small cost – the introduction of these new top-level paging nodes could break existing integration code. This issue leads into our next announcement:

API Version Numbers

Now when you submit your API requests, you can optionally specify a version number as part of the request URL.

Old URL:

http://mycompany.freshbooks.com/api/xml-in

New URL:

http://mycompany.freshbooks.com/api/2.1/xml-in

To take advantage of these new response formats, you must specify version 2.1 as part of the request URL. If you do not specify a version number, the API will return the old, less-descriptive response format (version 2.0).

Deprecation Warning!

We will support both versions (2.1 and 2.0) until March 1st, 2008. This will give you nearly 8 weeks to migrate your applications to the new schema.

If you have questions, comments or concerns, please contact us.

Hey everyone – long time no see!

After almost three months of silence on this blog, I’m proud to announce that Timesheets (including Projects and Tasks) and Estimates have been added to the FreshBooks API, along with a slew of other features and minor tweaks. Below is a quick summary of the big ones:

Timesheets

Timesheets exposes three new data types – projects, tasks and time entries. Between the three of these, you’ll be able to create new time entries remotely, query for all time entries between a given date, filter down by project or task, and more.

Estimates

Finally, you can interact with estimates just like their older big brother (read: invoices). You can perform basic CRUD operations, poll for estimate URLs, and send them off via e-mail.

Editable invoice and estimate numbers

As of version 4.2, invoice and estimate numbers are now editable. The API is no exception – the <number> parameter will now hold the invoice/estimate number, as opposed to to <invoice/estimate_id>.

Start and stop recurring profiles

You can now start/stop recurring profiles via the API using the <stopped> parameter. Deleting would have the same effect, but you couldn’t get the profile back - now you’re golden.

Version 4.0 of FreshBooks is here, and along with it comes a number of changes/additions to the FreshBooks API.

Recurring Profiles

It’s been a long time coming – you can finally create and manage recurring profiles via the API.

Bigger Search Results

You can now pull up to 100 records from an individual list request, using a per_page value of 100. If left unsupplied, per_page will default to 25.

New Filters

You can now retrieve any invoices generated from a recurring profile using the invoice.list method.

Furthermore, invoice.list will now let you filter search results by status – i.e. ‘draft’, ‘paid’ and so on.

Misc Bug Fixes

If you create a new client via the API, and supply that client’s username and password, they won’t be prompted again for their account details after they’ve logged in. This should help FreshBooks users who are trying to synchronize client account data.

Interested in viewing your invoices and collected revenue in a nice looking graph? Now you can with our new graph generator.

A few months ago, we released our redesigned API which gave you the ability to access and update your FreshBooks information for your custom solutions.
At that time, I release a nice little tool to import your items to your FreshBooks account from comma delimited text. This month, I made this easy to use graph generator with the help of the LastXgraph PHP library and the FreshBooks API.

All you have to do is enable your API for your system and enter your API credentials. Next, click the large submit button and, presto!, a nice graphical representation of your invoices and collected revenue.

The source code is written in PHP is available in the sample code section of our developers section.

Symfony users rejoice: there’s now an easy-to-use plugin for integrating your Symfony applications with the FreshBooks API. In case you’re not familiar, Symfony is a web development framework for PHP:

… symfony aims to speed up the creation and maintenance of web applications, and to replace the repetitive coding tasks by power, control and pleasure.

Much appreciation to the author, Ian Ricketson, for sharing his work. In case you missed it, users have also contributed Ruby and Perl libraries.