Skip to main content

​
Introduction

FreeAgent is a comprehensive cloud-based accounting software designed primarily for freelancers, small businesses, and accountants in the UK and Europe. It provides a complete suite of financial management tools including invoicing, expense tracking, time tracking, project management, tax calculations, and detailed financial reporting. FreeAgent offers specialized features for UK tax compliance including VAT, Corporation Tax, and Self Assessment integration.

​
Configure FreeAgent

Prerequisite(s)
  • Create an OAuth2 application in your FreeAgent developer account
  • Clarity on whether the integration targets a single company or multiple client folders
  • Activate the FreeAgent integration on the Chift platform
Activation Process 1. Create your FreeAgent application Sign in to the FreeAgent Developer Portal and register a new application. During registration:
  • Choose your connection type:
    • Free Agent (single company) – Direct connection to one specific company account. Suitable for individual businesses or single-company integrations.
      • Practice Dashboard (multi-client) – Designed for accountants managing multiple client folders. Allows centralized access to multiple client companies.
Note:
the chosen mode is exclusive; a Practice Dashboard app cannot connect single-company clients, and vice versa.
  • Configure the OAuth2 redirect URI: https://chift.app/oauth2/redirect
  • Select the environment: Sandbox (for testing) or Production (live data)
  • Copy your Client ID and Client Secret
Once this is complete, your FreeAgent application is ready for use in Chift. 2. Activate the connector on Chift In your Chift back office, open the FreeAgent connector and toggle activation. You will be prompted to:
  • Paste your Client ID and Client Secret
  • Select the Environment (Production or Sandbox)
  • Confirm the Connection Type (single company or Practice Dashboard)
If using Practice Dashboard, you will later be able to select which client folders to grant access to.

​
Test FreeAgent

FreeAgent provides both sandbox and production environments for testing:
  • Sandbox Environment: Full-featured testing environment with sample data
  • Production Environment: Live environment for real business data For accountants using Practice Dashboard, multiple client scenarios can be tested in either environment. Before going live, validate:
    • OAuth authentication
    • Invoice creation
    • Data synchronization

​
Connect FreeAgent

To activate a connection with FreeAgent, users will have to go through the following steps:

​
Technical Limitations

Connection Types To connect to FreeAgent you need to choose between one of those connection modes:
  • Free Agent: Direct connection to a single company
  • Practice Dashboard: Multi-client connection for accountants (requires folder selection)
Invoice Creation Restrictions
  • Customer invoice creation supports both draft and posted statuses
  • Foreign currency invoices with future dates cannot be automatically posted

​
Rate limits

The FreeAgent API enforces the following limits per user:
  • 120 requests per minute
  • 3,600 requests per hour
  • 15 token refreshes per minute
Documentation (FreeAgent dev):
https://dev.freeagent.com/docs/introduction

​
Coverage

​
Troubleshooting

​
Specific errors for FreeAgent:

Error CodeError descriptionResolution
ERROR_INVALID_ANALYTIC_DISTRIBUTIONUsing multiple analytic accounts in a single invoice is not allowed in FreeAgent.Use only one analytic account per invoice.
ERROR_FREEAGENT_BANK_TRANSACTION_ALREADY_EXPLAINEDThe bank transaction has already been explained in FreeAgent (potential duplicate detected).Verify the transaction has not already been processed in FreeAgent.
ERROR_INVALID_BODYFreeAgent does not support invoices dated in the future that use foreign currency.Use the current or past date for foreign currency invoices.
ERROR_CURRENCY_NOT_ALLOWEDFor FreeAgent, a foreign exchange rate must be specified and must not be equal to 0 or 1.Provide a valid exchange rate different from 0 and 1 for foreign currency journal entries.
ERROR_FREEAGENT_MATCHING_MIXED_ENTITY_TYPESCannot mix different document types (invoices, bills, bank transactions) in a single matching request.Use separate matching requests for different document types.
ERROR_FREEAGENT_MATCHING_MULTIPLEFreeAgent doesn’t support matching multiple bank transactions with multiple invoices/bills in a single request.Split the matching into separate requests.
ERROR_FREEAGENT_MATCHING_NO_TRANSACTIONSAt least one bank transaction must be included in the entries to match.Include at least one bank transaction in the matching request.
ERROR_FREEAGENT_MATCHING_UNSUPPORTED_ENTITYOnly sale invoices/refunds, purchase invoices/refunds, and bank transactions are accepted in matching requests.Use only supported document types in matching requests.