FreeAgent.Client 0.1.0-beta.3

This is a prerelease version of FreeAgent.Client.
dotnet add package FreeAgent.Client --version 0.1.0-beta.3
                    
NuGet\Install-Package FreeAgent.Client -Version 0.1.0-beta.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="FreeAgent.Client" Version="0.1.0-beta.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="FreeAgent.Client" Version="0.1.0-beta.3" />
                    
Directory.Packages.props
<PackageReference Include="FreeAgent.Client" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add FreeAgent.Client --version 0.1.0-beta.3
                    
#r "nuget: FreeAgent.Client, 0.1.0-beta.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package FreeAgent.Client@0.1.0-beta.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=FreeAgent.Client&version=0.1.0-beta.3&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=FreeAgent.Client&version=0.1.0-beta.3&prerelease
                    
Install as a Cake Tool

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.
  • CurrencyCode enum 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

Licence

MIT - see LICENSE.

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • 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