The FreeAgent API

All API access is over HTTPS and accessed from api.freeagent.com. JSON and XML formats are supported. A user-agent must be specified to allow the FreeAgent API to identify your app. Users can authenticate Apps using OAuth 2.0

Four HTTP verbs are used to access resources:

GET - Use when requesting an existing resource

POST - Use when creating a new resource

PUT - Use when updating an existing resource

DELETE - Use when deleting a resource

Use these verbs with the paths provided by the API.

About Request and Response Formats

Requests and responses can be provided in either JSON or XML. Set the HTTP Accept header to specify the response format and the HTTP Content-Type header to specify the request format.

JSON

Accept: application/json
Content-Type: application/json

XML

Accept: application/xml
Content-Type: application/xml

Formatting XML

There are five characters which must be substituted by XML Entities when creating XML. These are:

CharacterXML Entity
&&
<&lt;
>&gt;
"&quot;
'&apos;

About Access Levels

Access to FreeAgent resources is limited by user permissions. The minimum required access level is specified for each resource. The access levels are as follows:

0 : No Access
1 : Time
2 : My Money
3 : Contacts & Projects
4 : Invoices, Estimates & Files
5 : Bills
6 : Banking
7 : Tax, Accounting & Users
8 : Full

Pagination

API requests that returns multiple items, such as listing one of the resources, will be paginated (default to 25 items per page). A client can retrieve a specific page by providing the page param. In order to alter the number of records returned per page, a client can provide the per_page param (limited to 100 items per page).

GET https://api.freeagent.com/v2/invoices?page=5&per_page=50

The pagination info is included in the Link header:

Link: <https://api.freeagent.com/v2/invoices?page=4&per_page=50>; rel="prev", 
<https://api.freeagent.com/v2/invoices?page=6&per_page=50>; rel="next",
<https://api.freeagent.com/v2/invoices?page=1&per_page=50>; rel="first",
<https://api.freeagent.com/v2/invoices?page=10&per_page=50>; rel="last"

line breaks are for display purposes only.

The possible rel values are:

  • prev: The URL of the previous page of results.
  • next: The URI of the next page of results.
  • first: The URI of the first page of results.
  • last: The URI of the last page of results.