FreeAgent API Integration: OAuth Access Levels, Dual API Model, Pagination and UK Tax Context Explained
- Dr. Themo Voswinckel ⎪Co-Founder
- Feb 26
- 7 min read
FreeAgent is a cloud accounting platform built specifically for the UK market, widely used by freelancers, contractors, small businesses, and the accounting firms that serve them. It covers invoicing, expense tracking, bank reconciliation, payroll, and UK-specific tax workflows including Making Tax Digital (MTD) VAT filing, Self Assessment, and Corporation Tax returns — making it one of the most comprehensive UK-focused accounting platforms available.
For software teams building a FreeAgent API integration, the platform has a distinct technical profile: a numeric access level system that controls what data your app can read or write, two structurally separate API products for companies and accounting practices, pagination that defaults to just 25 results per page, and strict rate limits.
In this article, you will learn what each of these challenges means in practice — and why, with Maesn, none of it matters.
Key Takeaways
FreeAgent uses a numeric access level system (0–8) to control which resources your app can access. Each resource specifies a minimum required access level
FreeAgent has two separate API products: the Company API for direct business users, and the Accountancy Practice API for accounting firms managing multiple client accounts. These require different app registrations, different authentication flows, and different header configurations.
OAuth 2.0 access tokens expire after 1 hour. Refresh tokens are long-lived but capped at 15 refreshes per minute — a rate limit that can cause failures in multi-tenant setups.
Pagination defaults to 25 results per page with a hard cap of 100. Without explicit pagination handling, your sync silently returns incomplete data.
Rate limits are 120 requests per minute and 3,600 per hour per user. For the Accountancy Practice API, limits apply per client subdomain.
FreeAgent supports both JSON and XML responses. JSON is the modern default; XML support is a legacy feature but must be explicitly handled if encountered in older integrations.
Maesn handles all of the above. One unified API — access level routing, pagination, token refresh, and rate limit handling are all abstracted in the Maesn backend.
FreeAgent Uses a Numeric Access Level System As Scopes
Most OAuth APIs use named scopes to control access. FreeAgent uses a different model: a numeric access level system where each level grants progressively broader access to different resource groups:
Access Level | Resources |
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 Access |
Each API resource specifies a minimum required access level. If your app's registered access level is below the minimum for a given resource, the API returns an authorization error. This means access level configuration must be planned carefully upfront — not just at the OAuth flow level, but at the app registration level in the FreeAgent Developer Dashboard.
Maesn Configures the Correct Access Level for Your Integration — No Gaps at Runtime
Maesn handles access level configuration as part of the app registration and connection setup for FreeAgent. The correct access level is set based on your integration's requirements — your customers connect once and all required permissions are in place from the start.
FreeAgent Has Two Separate API Products — Company API and Accountancy Practice API
This is one of the most structurally important aspects of the FreeAgent API that many developers miss until they are already mid-integration. FreeAgent serves two distinct user types with two related but different API products:
Company API — for direct FreeAgent users: freelancers, contractors, and small businesses managing their own accounting. Authentication follows the standard OAuth flow.
Accountancy Practice API — for accounting firms and bookkeepers who manage multiple client accounts through FreeAgent's Practice Dashboard. This requires a separate app registration in the Developer Dashboard, a different OAuth flow, and client-specific subdomains in request headers to identify which client's data you are accessing.
For a SaaS product that serves both direct business users and accounting firms with multiple clients, this means building and maintaining two distinct integration paths — not one. The rate limit model also differs: for the Accountancy Practice API, rate limits apply per client subdomain rather than per practice as a whole.
Maesn Currently Supports the Company API — Accountancy Practice API Coming Soon
Maesn currently supports the FreeAgent Company API. If your customers are accounting firms managing multiple client accounts through FreeAgent's Practice Dashboard, reach out to the Maesn team — we will add the Accountancy Practice API. Once available, Maesn will route correctly and manage the client subdomain context per tenant automatically.
OAuth Tokens Expire After 1 Hour — and Token Refresh Is Rate Limited to 15 Per Minute
FreeAgent uses OAuth 2.0 with the authorization code flow. Access tokens expire after 1 hour. This is a standard expiry window, but with an important constraint that matters at scale: FreeAgent enforces a rate limit of 15 token refreshes per minute.
For a single-tenant integration, 15 refreshes per minute is far more than you will ever need. For a multi-tenant SaaS product with many customers, concurrent token refreshes — for example during a scheduled sync that runs across all tenants simultaneously — can easily hit this limit. When the limit is exceeded, the API returns a 429 Too Many Requests response on the token endpoint itself, not just on data endpoints. This means scheduled syncs that run in parallel can fail at the authentication layer before they even reach any data.
Refresh tokens are long-lived (the API response includes refresh_token_expires_in with a value of approximately 20 years in practice).
Maesn Manages Token Refresh With Rate-Limit Awareness For Multi-Tenant Use Cases
Maesn manages the full OAuth token lifecycle for FreeAgent across all your user, including refresh scheduling that respects the 15-per-minute rate limit. Concurrent refresh collisions and 429 responses on the token endpoint are handled in the Maesn backend. You never implement token refresh logic or manage refresh rate limits yourself.
Pagination Defaults to 25 Results — Hard Cap at 100, Navigation via Link Header
FreeAgent collection endpoints default to 25 results per page. The cap is 100 results per page. Without explicit pagination handling, your sync returns only the first 25 records and silently ignores everything else.
Pagination in FreeAgent is navigated via the Link response header, not via a metadata object in the response body:
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"The total record count is available in the X-Total-Count response header, not in the response body. Your pagination logic must parse response headers — not just the JSON body — to determine the total number of pages and whether more data is available.
Maesn Paginates All FreeAgent Endpoints Automatically — Complete Data on Every Request
Maesn handles pagination for all FreeAgent collection endpoints automatically, including Link header parsing and X-Total-Count tracking. When you request a list of invoices or contacts through Maesn, you receive the complete dataset. You never need to implement header-based pagination logic or track page state per tenant.
Rate Limits Are 120 Requests Per Minute and 3,600 Per Hour — Per User
FreeAgent enforces the following rate limits per individual user:
120 requests per minute
3.600 requests per hour
15 token refreshes per minute
When a limit is exceeded, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying. FreeAgent explicitly states it will review and may further restrict apps that continue making high-volume requests while rate limited — making a proper back-off strategy not just good practice but a requirement for maintaining API access.
For the Accountancy Practice API, the per-minute and per-hour limits apply per client subdomain. This means an accounting firm managing 50 client accounts has independent rate limit buckets per client — a different scaling model than the Company API.
Maesn Handles Rate Limiting and Back-Off Across All Tenants — No 429s in Production
Maesn manages rate limit handling for FreeAgent including Retry-After back-off, request queuing, and per-tenant throttling. You never write rate limit logic or handle 429 responses yourself.
FreeAgent Is Built for the UK Market — MTD VAT, Self Assessment, and CIS Are Core Features
FreeAgent is not a generic accounting platform adapted for the UK — it is built from the ground up for UK tax compliance. This has direct implications for what data is available in the API and how it is structured:
Making Tax Digital (MTD) VAT — FreeAgent is HMRC-recognised MTD software. The API exposes VAT return data and submission endpoints, which are relevant for products that need to read or process VAT filing data for UK businesses.
Self Assessment — FreeAgent generates Self Assessment returns for sole traders and directors. The API provides access to income tax return data, which is relevant for products serving UK freelancers and contractors.
Construction Industry Scheme (CIS) — FreeAgent supports CIS deduction tracking and reporting. The API includes CIS-specific endpoints (/v2/cis_bands) that are unique to the UK construction sector.
Corporation Tax — FreeAgent supports Corporation Tax return preparation. The API provides access to corporation tax return data for limited companies.
For SaaS products serving UK SMEs, understanding this tax-first architecture means the FreeAgent API exposes financial data that goes significantly deeper than a standard invoicing or accounting system — and also means that some resources (VAT returns, Self Assessment, Corporation Tax) require access level 7 or higher.
Maesn Maps UK Tax Data to Its Common Data Model — No UK-Specific Logic in Your Codebase
Maesn normalizes FreeAgent's UK-specific tax data structures into its common data model. You access VAT, payroll, and compliance-relevant data through Maesn's unified endpoints — without building UK-specific parsing logic in your codebase.
Why Teams Use Maesn for FreeAgent API Integration
Building a direct FreeAgent API integration means navigating a numeric access level system, managing two separate API products for companies and accounting practices, handling 1-hour token expiry with a 15-refresh-per-minute rate limit, parsing Link headers for pagination, implementing back-off strategies for strict rate limits, and understanding UK-specific tax data structures — all before you ship your first feature.
Maesn abstracts this entire surface into a single unified API. You integrate once to Maesn and your product automatically works with FreeAgent and every other accounting system in the Maesn portfolio, without system-specific branches in your code.
Check the Maesn documentation for FreeAgent or talk to the Maesn team to get started.
