FreeAgent .NET 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 currently in alpha. Public APIs may change between releases. See VERSIONING.md.

Documentation: markheydon.me.uk/freeagent-dotnet - tutorials, how-to guides, and SDK reference (source).

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, Stock items, Price list items, Tasks, Timeslips, Notes, and Email addresses API support
• Targets .NET 8.0 and .NET 10.0
• Fully async/await with XML documentation

Installation

dotnet add package FreeAgent.Client

Quick start

using FreeAgent.Client;

var environment = FreeAgentEnvironment.Sandbox; // or Production - pass the same value to both constructors
var oauthClient = new FreeAgentOAuthClient(clientId, clientSecret, redirectUri, environment);
var authUrl = oauthClient.GetAuthorizationUrl(state: "optional-state");
// Redirect user to authUrl, then exchange the callback code:
var token = await oauthClient.ExchangeCodeForTokenAsync(code);

using var client = new FreeAgentClient(oauthClient, token, environment);
var company = await client.Company.GetCompanyAsync();
Console.WriteLine($"{company.Name} ({company.Currency})");

More detail: Getting started · Pagination · Error handling · API coverage

Building from source

git clone https://github.com/markheydon/freeagent-dotnet.git
cd freeagent-dotnet
dotnet clean FreeAgent.slnx && \
dotnet restore FreeAgent.slnx && \
dotnet build FreeAgent.slnx --no-restore --configuration Release -warnaserror && \
dotnet test FreeAgent.slnx --no-build --configuration Release

Contributor setup (SDK versions, WSL): docs/contributing-setup.md

Contributing

See CONTRIBUTING.md. By participating, you agree to CODE_OF_CONDUCT.md.

Support and security

• SUPPORT.md - questions and issue routing
• SECURITY.md - private vulnerability reporting

Licence

MIT - see LICENSE.

Versioning

VERSIONING.md - prerelease policy and path to stable 1.0.0.

Resources

• FreeAgent API documentation
• Sample app - interactive SDK workbench (contributors)