> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# FreeAgent plugin

> Manage FreeAgent company records, verified sender addresses, contacts, projects, invoices, and tracking groups through its OAuth 2.0 REST API.

Use **FreeAgent** through Corsair: one client, typed API calls.

Connect a FreeAgent OAuth 2.0 app (client ID and secret from dev.freeagent.com). Access tokens last an hour and refresh automatically. Pass sandbox: true to use api.sandbox.freeagent.com for both OAuth and the API. This plugin exposes company profile, verified sender addresses, contacts, projects, selected invoice and recurring invoice operations, and tracking groups. Many other official company API routes remain unimplemented; see the linked route inventory in the package README. The Accountancy Practice API requires practice-enabled OAuth and X-Subdomain client scoping and is excluded.

**What you get:**

* 36 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/freeagent better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/freeagent better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/freeagent better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/freeagent better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { freeagent } from '@corsair-dev/freeagent';

export const corsair = createCorsair({
	plugins: [
		freeagent(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] OAuth 2.0 (Recommended)
>
> Open [hub.corsair.dev](https://hub.corsair.dev/dashboard), navigate to your project, and enter the **client ID** and **client secret** from your FreeAgent OAuth app.
>
> ```ts theme={null}
> freeagent()
> ```
>
> More: [OAuth 2.0](https://docs.corsair.dev/concepts/oauth)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'freeagent',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List contacts**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.freeagent.api.contacts.list({});
```

**Create a contact**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.freeagent.api.contacts.create({
	contact: { organisation_name: 'Example Ltd' },
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/freeagent/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/freeagent/api.md)
>
> Every `freeagent.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.