FreeAgent.Client
0.1.0-beta.3
dotnet add package FreeAgent.Client --version 0.1.0-beta.3
NuGet\Install-Package FreeAgent.Client -Version 0.1.0-beta.3
<PackageReference Include="FreeAgent.Client" Version="0.1.0-beta.3" />
<PackageVersion Include="FreeAgent.Client" Version="0.1.0-beta.3" />
<PackageReference Include="FreeAgent.Client" />
paket add FreeAgent.Client --version 0.1.0-beta.3
#r "nuget: FreeAgent.Client, 0.1.0-beta.3"
#:package FreeAgent.Client@0.1.0-beta.3
#addin nuget:?package=FreeAgent.Client&version=0.1.0-beta.3&prerelease
#tool nuget:?package=FreeAgent.Client&version=0.1.0-beta.3&prerelease
FreeAgent.Client
A .NET client library for the FreeAgent API with OAuth 2.0 support, rate limiting, retries, typed transport errors, and pagination.
Prerelease software. This package is in beta. Company FreeAgent API resources documented at dev.freeagent.com/docs are implemented in the SDK (excluding the separate Accountancy Practice API). See versioning policy.
Features
- OAuth 2.0 protocol helpers with automatic token refresh.
- Rate limiting and bounded retries for transient failures.
- Typed exception model (
FreeAgentApiException,FreeAgentRateLimitException, …). - Pagination (single-page and auto-pagination).
- Company, Contacts, Categories, Users, Projects, Invoices, Estimates, Recurring invoices, Credit notes, Credit note reconciliations, Bills, Bank accounts, Bank feeds, Bank transaction explanations, Bank transactions, Hire purchases, Expenses, Attachments, Stock items, Price list items, Capital assets, Capital asset types, Journal sets, Payroll, Payroll profiles, Properties, CIS bands, CIS settings, Profit and loss, Balance sheet, Trial balance, Cashflow, Transactions, VAT returns, Corporation tax returns, Sales tax periods, EC VAT MOSS sales tax rates, Tasks, Timeslips, Notes, and Email addresses API support.
CurrencyCodeenum for documented ISO 4217 codes (reference type; not a REST resource).- Targets .NET 8.0 and .NET 10.0.
- Fully async/await with XML documentation.
Installation
dotnet add package FreeAgent.Client
Compatibility
| Host | Status |
|---|---|
SDK-style .csproj apps (web, worker, console) |
Supported — recommended path |
File-based apps (#:package, .NET 10+) |
Supported — source-generated JSON metadata |
PublishTrimmed / aggressive trimming |
Not supported yet |
Native AOT publish (PublishAot) |
Not supported yet |
API and OAuth traffic use System.Text.Json with source-generated metadata. File-based apps do not need JsonSerializerIsReflectionEnabledByDefault. Trim and Native AOT publish are tracked under #173. See getting started — host compatibility.
Quick start
Once you have an OAuth access token, calling the API is a few lines:
using FreeAgent.Client;
// Access token from your OAuth authorisation flow (do not commit real tokens).
var accessToken = "paste-your-access-token";
// Must match where the token was issued (sandbox app → Sandbox, production app → Production).
var environment = FreeAgentEnvironment.Sandbox;
using var client = new FreeAgentClient(accessToken, environment);
var company = await client.Company.GetCompanyAsync();
Console.WriteLine($"{company.Name} ({company.Currency})");
First run from scratch? Copy-paste runnable scripts (get a sandbox token, then call the API) are in the repository README Quick start. The same files live under samples/FileBasedQuickStart/ (use #:project instead of #:package when building from a clone).
The SDK provides protocol-level OAuth utilities (FreeAgentOAuthClient); your application owns browser redirects and callback endpoints. See Getting started.
Linked resources
FreeAgent links resources with URI strings on the wire. For writes, set *Id properties on models (or CategoryNominalCode for categories) — the SDK builds environment-correct URIs internally. For reads, use flat properties such as ContactId, ContactName, and optional hydration.
The following flow chains ids from each response into the next create call:
// 1. Contact id from a prior list or create call
const long contactId = 42;
// 2. Create a project for that contact
var project = await client.Projects.CreateProjectAsync(new Project
{
Name = "Website redesign",
ContactId = contactId,
Status = ProjectStatus.Active
});
var projectId = project.ResourceId;
// Display name from one GET — no extra HTTP call
var summary = await client.Projects.GetProjectAsync(projectId);
var label = summary.ContactName;
// Full contact fields when you need them
var withContact = await client.Projects.GetProjectAsync(
projectId,
new ProjectGetOptions { IncludeContact = true });
var organisation = withContact.Contact!.OrganisationName;
// 3. Create a task under the project (parent scoped via query param)
var task = await client.ProjectTasks.CreateProjectTaskAsync(projectId, new ProjectTask
{
Name = "Planning",
IsBillable = true,
Status = ProjectTaskStatus.Active
});
var taskId = task.ResourceId;
// 4. Log time against the task
await client.Timeslips.CreateTimeslipAsync(new Timeslip
{
ProjectTaskId = taskId,
ProjectId = projectId,
UserId = 1,
DatedOn = DateOnly.FromDateTime(DateTime.UtcNow),
Hours = 1.5m
});
// 5. Raise a draft invoice for the contact
await client.Invoices.CreateInvoiceAsync(new Invoice
{
ContactId = contactId,
DatedOn = DateOnly.FromDateTime(DateTime.UtcNow),
PaymentTermsInDays = 14,
InvoiceItems =
[
new InvoiceItem
{
Description = "Consulting",
ItemType = InvoiceItemType.Hours,
Quantity = 2,
Price = 100,
CategoryNominalCode = "001"
}
]
});
Further resources that link to contacts and projects include recurring invoices, credit notes, credit note reconciliations, bank accounts (optional remittance on invoices and credit notes via BankAccountId), bank feeds (read-only feeds linked to a bank account via BankAccountId), bank transactions (list and statement upload scoped to a bank account), and notes.
See linked resources for the full pattern, including list filters, webhook URL parsing, and update options.
Replicating data? Use incremental sync for ListAutoPagingAsync watermarks, nested line-item flags (nestedInvoiceItems, and similar), and per-resource parameter notes.
Documentation
Published documentation: markheydon.me.uk/freeagent-dotnet
- Getting started
- Pagination
- Incremental sync
- Error handling
- API coverage - SDK reference for every implemented resource
Licence
MIT - see LICENSE.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- No dependencies.
-
net8.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-beta.3 | 100 | 10/28/2026 |
| 0.1.0-beta.2 | 254 | 10/26/2026 |
| 0.1.0-beta.1 | 173 | 10/22/2026 |
| 0.1.0-alpha.5 | 208 | 10/20/2026 |
| 0.1.0-alpha.4 | 148 | 9/25/2026 |
| 0.1.0-alpha.3 | 123 | 9/21/2026 |
| 0.1.0-alpha.2 | 128 | 9/4/2026 |
| 0.1.0-alpha.1 | 106 | 9/3/2026 |