FreeAgent API PHP Wrapper: Download for free

by Paul on August 4, 2011

Recently we launched a new product that has been a hit with freelancers from all over the world!

We called it Agent Toast and it allows you to quickly synchronize time tracking data with billing & accounts software.

Right now Agent Toast is free, and it synchronizes between only FreeAgent Central, and Toggl time tracking.

One of the most challenging aspects to creating a product such as this is the “talking” to each of the services using their public open API. Since custom PHP development is one of our core strengths alongside WordPress website management, we decided to build a PHP wrapper to access the APIs.

And we’re providing this PHP wrapper as a completely free download.

Download a PHP Wrapper for the FreeAgent public API

This PHP implementation of the FreeAgent API is based on latest version 6 (at the time of writing).

A new API release is imminent from FreeAgent which will use OAuth as its authentication layer – an update to this API will be released when this happens.

This implementation takes on a verbose approach. That is, where a specific method or action has been exposed by the API, there is a like-named method available on the wrapper.

This is particularly useful when working in an intellisense capable editor such as Eclipse PDT.  API reflection reduces the ambiguity of what is actually available, meaning less trips over to the API documentation, lowering the learning curve. Unlike other freely available APIs this one is fully tried and tested and is accompanied with any additionally required code.

It’s ready to go!

We are always aiming to provide reliable, simple to use and clearly readable code. If you download this, and you find it doesn’t work as expected, then please get in touch and we’ll update the code where necessary.

Here is an example

$aTimeslipData = array(
'project-id' => 12345,
'user-id' => 112233,
'hours' => '6:00',
'dated-on' => '2011-06-25T00:00:00Z',
'Comment' => 'Imported using API Wrapper',
'new-task' => 'My new task!'

$oFreeAgent = new FreeAgent_Api( 'your_freeagent_subdomain', 'your_freeagent_username', 'your_freeagent_password' );
$oResult = $oFreeAgent->createTimeslip( $aTimeslipData );
if ( $oResult->success ) {
// do something cool!

$oFreeAgent->getProjectTasks( 12345 );

PHP Wrapper for FreeAgent API: free download on the developer channel

We’ve created a channel for developers who want our free give-aways. Each time we release a product, we’ll send out a notification to our member. This includes updates to existing tools.

In order to join this channel you need to sign-up using the form below.

Once you confirm your email address, you’ll receive an email with the API download link. If you’d prefer not to receive notices of updates and other products we release, you can un-subscribe at any time – we’re not even slightly interested in SPAMMING you.

Here at Host Like Toast we like to share the tools we create to help other developers get the most out of their time. We believe in sharing our knowledge where it makes sense and so we’re making the first of our PHP wrappers available for free download.

Sign-up today!

Use the form below to join our Developer Channel

Do you need an automated CPanel web hosting backup script? There is that and more in the Developer Channel

{ 6 comments… read them below or add one }

Lewis September 30, 2011 at 5:35 pm


Thanks for making this available. It’s very nice of you to go to the trouble. Unfortunately I haven’t got a clue how to get started with it, and there are no instructions or examples in the download. Do I include all three files in my document? In any particular order?

Best wishes



Paul October 1, 2011 at 12:02 am

Hi Lewis,

We’ll probably put together some sample documentation, but this code is delivered on the basis that users would dig in and see how it’s done. That said though, we appreciate that that’s time consuming, so here’s a basic bit of code to get you started and including the right files etc.:

// Include the api file. Assuming the files are in the same directory as the PHP file you're working from:
include_once( dirname(__FILE__).'/base_api.php' );
include_once( dirname(__FILE__).'/freeagent_api.php' );
$sFreeAgentSubdomain = 'my_fa_subdomain'; // assuming you login to FA using
$sFreeAgentUsername = 'my_username';
$sFreeAgentPassword = 'my_password';
$oFA = new FreeAgent_Api( $sFreeAgentSubdomain, $sFreeAgentUsername, $sFreeAgentPassword );
var_dump( $oFA->getVerify() );
var_dump( $oFA->getContacts() );

Hopefully this should get you started – you will probably need to refer to the FreeAgent API documentation to learn more about what the api allows for. This PHP wrapper will then cater for whatever the FreeAgent API has and whatever you need to achieve.

Let us know how you get on.



Lewis October 3, 2011 at 8:52 pm

Thanks for your help Paul. Your post was enough to get me on my way, and I have now figured out lots from the source code.

A quick question :

Currently it seems that I can request a single invoice directly using GET /invoices/invoice_id where invoice_id is the ID of the invoice.

However, I’d like to request a single invoice where only the invoice reference is known. Do you know a way this could be done with your code?

Thanks again for sharing this with everybody. I hope it encourages more developers to create useful stuff for Freeagent.


Paul October 3, 2011 at 8:59 pm

Hey Lewis,

Great you hear you got started and it’s working well for you.

Unfortunately the API doesn’t allow for you to pull out an invoice based on the reference alone.

The only way you’re going to be able to do this is to use the function getInvoices() and then check each one and until you find the one with the reference you desire.

It’s just a limitation of the FreeAgent API unfortunately.

Hope that helps!

P.S. Speaking of creating useful stuff for FreeAgent, have you seen our Agent Toast product that lets you sync quickly your timeslips from Toggl into FreeAgent? It’s in beta and free for the moment if you want to give it a try 🙂


Riel December 17, 2011 at 4:32 pm

How can I create an expense? I cannot find this option?


Paul December 18, 2011 at 10:42 pm

Hi Riel,

Your best bet is to consult the API Documentation for Freeagent here:

If you think there is something lacking in the current API implementation, please follow up with us and let us know.


Leave a Comment

Previous post:

Next post: