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.
Accept: application/json Content-Type: application/json
Accept: application/xml Content-Type: application/xml
There are five characters which must be substituted by XML Entities when creating XML. These are:
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
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).
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.
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.
In addition, the
X-Total-Count header will contain the total number of entries that it is possible to paginate over: