> ## 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 API reference

> API reference for the FreeAgent plugin in Corsair: every `freeagent.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Company

### businessCategories

`company.businessCategories`

List the documented business categories for company profiles

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.company.businessCategories({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `business_categories` | `string[]` | Yes | — |

***

### get

`company.get`

Get the authenticated company profile

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.company.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `company` | `Record<string, JsonValue>` | Yes | — |

***

### taxTimeline

`company.taxTimeline`

List upcoming tax events and due dates for the company

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.company.taxTimeline({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `timeline_items` | `object[]` | Yes | — |

> [accordion] timeline\_items full type
>
> ```ts theme={null}
> {
>   description: string,
>   nature: string,
>   dated_on: string,
>   amount_due?: string | number,
>   is_personal: boolean
> }[]
> ```

***

## Contacts

### create

`contacts.create`

Create a contact using documented contact fields

**Risk:** `write`

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

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `contact` | `object` | Yes | — |

> [accordion] contact full type
>
> ```ts theme={null}
> {
>   first_name?: string,
>   last_name?: string,
>   organisation_name?: string,
>   email?: string,
>   billing_email?: string,
>   phone_number?: string,
>   mobile?: string,
>   address1?: string,
>   address2?: string,
>   address3?: string,
>   town?: string,
>   region?: string,
>   postcode?: string,
>   country?: string,
>   contact_name_on_invoices?: boolean,
>   default_payment_terms_in_days?: number,
>   locale?: string,
>   uses_contact_invoice_sequence?: boolean,
>   charge_sales_tax?: Auto | Always | Never,
>   sales_tax_registration_number?: string,
>   status?: Active | Hidden,
>   is_cis_subcontractor?: boolean,
>   cis_deduction_rate?: cis_gross | cis_standard | cis_higher,
>   unique_tax_reference?: string,
>   subcontractor_verification_number?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contact` | `object` | Yes | — |

> [accordion] contact full type
>
> ```ts theme={null}
> {
>   first_name?: string,
>   last_name?: string,
>   organisation_name?: string,
>   email?: string,
>   billing_email?: string,
>   phone_number?: string,
>   mobile?: string,
>   address1?: string,
>   address2?: string,
>   address3?: string,
>   town?: string,
>   region?: string,
>   postcode?: string,
>   country?: string,
>   contact_name_on_invoices?: boolean,
>   default_payment_terms_in_days?: string | number | null,
>   locale?: string,
>   uses_contact_invoice_sequence?: boolean,
>   charge_sales_tax?: string | null,
>   sales_tax_registration_number?: string,
>   status?: string | null,
>   is_cis_subcontractor?: boolean,
>   cis_deduction_rate?: string | null,
>   unique_tax_reference?: string,
>   subcontractor_verification_number?: string,
>   url?: string,
>   active_projects_count?: number,
>   direct_debit_mandate_state?: string,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### delete

`contacts.delete`

Delete a contact

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.contacts.delete({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### get

`contacts.get`

Get a contact by its FreeAgent ID

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.contacts.get({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contact` | `object` | Yes | — |

> [accordion] contact full type
>
> ```ts theme={null}
> {
>   first_name?: string,
>   last_name?: string,
>   organisation_name?: string,
>   email?: string,
>   billing_email?: string,
>   phone_number?: string,
>   mobile?: string,
>   address1?: string,
>   address2?: string,
>   address3?: string,
>   town?: string,
>   region?: string,
>   postcode?: string,
>   country?: string,
>   contact_name_on_invoices?: boolean,
>   default_payment_terms_in_days?: string | number | null,
>   locale?: string,
>   uses_contact_invoice_sequence?: boolean,
>   charge_sales_tax?: string | null,
>   sales_tax_registration_number?: string,
>   status?: string | null,
>   is_cis_subcontractor?: boolean,
>   cis_deduction_rate?: string | null,
>   unique_tax_reference?: string,
>   subcontractor_verification_number?: string,
>   url?: string,
>   active_projects_count?: number,
>   direct_debit_mandate_state?: string,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### list

`contacts.list`

List contacts with documented filters and pagination

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.contacts.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

FreeAgent paginates collections with a default of 25 records and a maximum per\_page of 100. The result includes pagination.link and pagination.total\_count, preserving the Link header and X-Total-Count header value respectively.

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number,
>   view?: string,
>   sort?: string,
>   updated_since?: string,
>   from_date?: string,
>   to_date?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contacts` | `object[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] contacts full type
>
> ```ts theme={null}
> {
>   first_name?: string,
>   last_name?: string,
>   organisation_name?: string,
>   email?: string,
>   billing_email?: string,
>   phone_number?: string,
>   mobile?: string,
>   address1?: string,
>   address2?: string,
>   address3?: string,
>   town?: string,
>   region?: string,
>   postcode?: string,
>   country?: string,
>   contact_name_on_invoices?: boolean,
>   default_payment_terms_in_days?: string | number | null,
>   locale?: string,
>   uses_contact_invoice_sequence?: boolean,
>   charge_sales_tax?: string | null,
>   sales_tax_registration_number?: string,
>   status?: string | null,
>   is_cis_subcontractor?: boolean,
>   cis_deduction_rate?: string | null,
>   unique_tax_reference?: string,
>   subcontractor_verification_number?: string,
>   url?: string,
>   active_projects_count?: number,
>   direct_debit_mandate_state?: string,
>   created_at?: string,
>   updated_at?: string
> }[]
> ```

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***

### update

`contacts.update`

Update documented fields on a contact

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.contacts.update({
	id: '1',
	contact: { organisation_name: 'Example Ltd' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `contact` | `object` | Yes | — |

> [accordion] contact full type
>
> ```ts theme={null}
> {
>   first_name?: string,
>   last_name?: string,
>   organisation_name?: string,
>   email?: string,
>   billing_email?: string,
>   phone_number?: string,
>   mobile?: string,
>   address1?: string,
>   address2?: string,
>   address3?: string,
>   town?: string,
>   region?: string,
>   postcode?: string,
>   country?: string,
>   contact_name_on_invoices?: boolean,
>   default_payment_terms_in_days?: number,
>   locale?: string,
>   uses_contact_invoice_sequence?: boolean,
>   charge_sales_tax?: Auto | Always | Never,
>   sales_tax_registration_number?: string,
>   status?: Active | Hidden,
>   is_cis_subcontractor?: boolean,
>   cis_deduction_rate?: cis_gross | cis_standard | cis_higher,
>   unique_tax_reference?: string,
>   subcontractor_verification_number?: string
> }
> ```

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

## Email Addresses

### list

`emailAddresses.list`

List verified sender email addresses for the company

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.emailAddresses.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

Returns the company's verified sender email addresses. The result includes pagination.link and pagination.total\_count from FreeAgent's collection headers.

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `email_addresses` | `string[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***

## Invoices

### convertToCreditNote

`invoices.convertToCreditNote`

Convert a draft negative invoice into a credit note

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.convertToCreditNote({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `credit_note` | `object` | Yes | — |

> [accordion] credit\_note full type
>
> ```ts theme={null}
> {
>   url?: string,
>   contact?: string,
>   project?: string,
>   property?: string,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string,
>   payment_terms_in_days?: number,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: string | number,
>   comments?: string,
>   discount_percent?: string | number,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   ec_status?: string,
>   place_of_supply?: string,
>   net_value?: string | number,
>   exchange_rate?: string | number,
>   involves_sales_tax?: boolean,
>   sales_tax_value?: string | number,
>   second_sales_tax_value?: string | number,
>   total_value?: string | number,
>   refunded_value?: string | number,
>   due_value?: string | number,
>   is_interim_uk_vat?: boolean,
>   refunded_on?: string,
>   written_off_date?: string,
>   status?: Draft | Open | Overdue | Refunded | Written-off,
>   long_status?: string,
>   contact_name?: string,
>   credit_note_items?: {
>     url?: string,
>     position?: string | number,
>     description?: string,
>     item_type?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     second_sales_tax_rate?: string | number,
>     suffers_cis_deduction?: boolean,
>     sales_tax_status?: string,
>     second_sales_tax_status?: string,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[],
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### create

`invoices.create`

Create an invoice in Draft status

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.invoices.create({
	invoice: { contact: 'https://api.freeagent.com/v2/contacts/1', dated_on: '2025-01-15', payment_terms_in_days: 30 },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoice` | `object` | Yes | — |

FreeAgent creates new invoices in Draft status. Use an explicit status-transition operation to mark an invoice sent; this plugin currently exposes markSent.

> [accordion] invoice full type
>
> ```ts theme={null}
> {
>   contact: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on: string,
>   due_on?: string,
>   payment_terms_in_days: number,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: number,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: number,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: UK/Non-EC | EC Goods | EC Services | Reverse Charge | EC VAT MOSS,
>   place_of_supply?: string,
>   invoice_items?: {
>     position?: number,
>     item_type?: Hours | Days | Weeks | Months | Years | Products | Services | Training | Expenses | Comment | Bills | Discount | Credit | VAT | Stock,
>     quantity?: number,
>     description: string,
>     price?: number,
>     sales_tax_rate?: number,
>     second_sales_tax_rate?: number,
>     sales_tax_status?: TAXABLE | EXEMPT,
>     second_sales_tax_status?: string,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoice` | `object` | Yes | — |

> [accordion] invoice full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string | null,
>   payment_terms_in_days?: string | number | null,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: string | number | null,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: string | number | null,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: string | null,
>   place_of_supply?: string,
>   invoice_items?: {
>     url?: string,
>     position?: string | number,
>     item_type?: string,
>     description?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     second_sales_tax_rate?: string | number,
>     sales_tax_status?: string,
>     second_sales_tax_status?: string,
>     suffers_cis_deduction?: boolean,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[],
>   url?: string,
>   status?: string,
>   long_status?: string,
>   net_value?: string,
>   total_value?: string,
>   paid_value?: string,
>   due_value?: string,
>   paid_on?: string,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### delete

`invoices.delete`

Delete an invoice

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.delete({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### deleteDefaultAdditionalText

`invoices.deleteDefaultAdditionalText`

Remove the default additional text from company invoices

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.invoices.deleteDefaultAdditionalText({});
```

**Input:** *empty object*

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### directDebit

`invoices.directDebit`

Take payment using an eligible GoCardless mandate

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.directDebit({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

This requests a real GoCardless payment and is available only for sent invoices with an enabled pre-authorised mandate and no previous payment.

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### duplicate

`invoices.duplicate`

Duplicate an invoice as a new draft using the next reference

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.invoices.duplicate({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoice` | `object` | Yes | — |

> [accordion] invoice full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string | null,
>   payment_terms_in_days?: string | number | null,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: string | number | null,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: string | number | null,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: string | null,
>   place_of_supply?: string,
>   invoice_items?: {
>     url?: string,
>     position?: string | number,
>     item_type?: string,
>     description?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     second_sales_tax_rate?: string | number,
>     sales_tax_status?: string,
>     second_sales_tax_status?: string,
>     suffers_cis_deduction?: boolean,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[],
>   url?: string,
>   status?: string,
>   long_status?: string,
>   net_value?: string,
>   total_value?: string,
>   paid_value?: string,
>   due_value?: string,
>   paid_on?: string,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### get

`invoices.get`

Get an invoice by its FreeAgent ID

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.invoices.get({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoice` | `object` | Yes | — |

> [accordion] invoice full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string | null,
>   payment_terms_in_days?: string | number | null,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: string | number | null,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: string | number | null,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: string | null,
>   place_of_supply?: string,
>   invoice_items?: {
>     url?: string,
>     position?: string | number,
>     item_type?: string,
>     description?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     second_sales_tax_rate?: string | number,
>     sales_tax_status?: string,
>     second_sales_tax_status?: string,
>     suffers_cis_deduction?: boolean,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[],
>   url?: string,
>   status?: string,
>   long_status?: string,
>   net_value?: string,
>   total_value?: string,
>   paid_value?: string,
>   due_value?: string,
>   paid_on?: string,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### getDefaultAdditionalText

`invoices.getDefaultAdditionalText`

Get the default additional text for company invoices

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.invoices.getDefaultAdditionalText({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `default_additional_text` | `string` | No | — |

***

### list

`invoices.list`

List invoices with documented filters and pagination

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.invoices.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number,
>   view?: string,
>   sort?: string,
>   updated_since?: string,
>   from_date?: string,
>   to_date?: string,
>   contact?: string,
>   project?: string,
>   nested_invoice_items?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoices` | `object[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] invoices full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string | null,
>   payment_terms_in_days?: string | number | null,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: string | number | null,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: string | number | null,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: string | null,
>   place_of_supply?: string,
>   invoice_items?: {
>     url?: string,
>     position?: string | number,
>     item_type?: string,
>     description?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     second_sales_tax_rate?: string | number,
>     sales_tax_status?: string,
>     second_sales_tax_status?: string,
>     suffers_cis_deduction?: boolean,
>     stock_item?: string,
>     category?: string,
>     project?: string
>   }[],
>   url?: string,
>   status?: string,
>   long_status?: string,
>   net_value?: string,
>   total_value?: string,
>   paid_value?: string,
>   due_value?: string,
>   paid_on?: string,
>   created_at?: string,
>   updated_at?: string
> }[]
> ```

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***

### markCancelled

`invoices.markCancelled`

Cancel and write off an eligible sent invoice

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.markCancelled({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### markDraft

`invoices.markDraft`

Return an invoice to Draft status

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.markDraft({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### markScheduled

`invoices.markScheduled`

Schedule an invoice to be emailed

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.markScheduled({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### markSent

`invoices.markSent`

Mark an invoice as sent or reopen a cancelled invoice

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.markSent({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### pdf

`invoices.pdf`

Get the invoice PDF as base64 encoded JSON content

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.invoices.pdf({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

FreeAgent returns PDF bytes as base64 in pdf.content; decode that value to obtain the PDF file.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `pdf` | `object` | Yes | — |

> [accordion] pdf full type
>
> ```ts theme={null}
> {
>   content: string
> }
> ```

***

### sendEmail

`invoices.sendEmail`

Send an invoice email to its recipient

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.invoices.sendEmail({
	id: '1',
	email: { use_template: true },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `email` | `object` | Yes | — |

Sending an invoice email is a separate action from marking the invoice sent. The operation accepts the documented template flag, message fields, and base64 attachments up to 5 MiB each.

> [accordion] email full type
>
> ```ts theme={null}
> {
>   to?: string,
>   from?: string,
>   subject?: string,
>   body?: string,
>   email_to_sender?: boolean,
>   attach_expense_receipts?: boolean,
>   use_template?: boolean,
>   attachments?: {
>     content_type: string,
>     data: string,
>     file_name: string
>   }[]
> }
> ```

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### timeline

`invoices.timeline`

List invoice timeline entries

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.invoices.timeline({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invoice_timeline_items` | `object[]` | Yes | — |

> [accordion] invoice\_timeline\_items full type
>
> ```ts theme={null}
> {
>   reference: string,
>   summary: string,
>   description: string,
>   dated_on: string,
>   amount: string
> }[]
> ```

***

### update

`invoices.update`

Update an invoice without changing its status

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.invoices.update({
	id: '1',
	invoice: { comments: 'Example update' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `invoice` | `object` | Yes | — |

> [accordion] invoice full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   project?: string,
>   property?: string,
>   include_timeslips?: string | null,
>   include_expenses?: string | null,
>   include_estimates?: string | null,
>   reference?: string,
>   dated_on?: string,
>   due_on?: string,
>   payment_terms_in_days?: number,
>   currency?: string,
>   cis_rate?: string | null,
>   cis_deduction_rate?: number,
>   comments?: string,
>   send_new_invoice_emails?: boolean,
>   send_reminder_emails?: boolean,
>   send_thank_you_emails?: boolean,
>   discount_percent?: number,
>   client_contact_name?: string,
>   payment_terms?: string,
>   po_reference?: string,
>   bank_account?: string,
>   omit_header?: boolean,
>   show_project_name?: boolean,
>   always_show_bic_and_iban?: boolean,
>   ec_status?: UK/Non-EC | EC Goods | EC Services | Reverse Charge | EC VAT MOSS,
>   place_of_supply?: string,
>   invoice_items?: (
>     {
>       position?: number,
>       item_type?: Hours | Days | Weeks | Months | Years | Products | Services | Training | Expenses | Comment | Bills | Discount | Credit | VAT | Stock,
>       quantity?: number,
>       description?: string,
>       price?: number,
>       sales_tax_rate?: number,
>       second_sales_tax_rate?: number,
>       sales_tax_status?: TAXABLE | EXEMPT,
>       second_sales_tax_status?: string,
>       stock_item?: string,
>       category?: string,
>       project?: string,
>       id: string | number
>     } | {
>       id: string | number,
>       _destroy: 1
>     } | {
>       position?: number,
>       item_type?: Hours | Days | Weeks | Months | Years | Products | Services | Training | Expenses | Comment | Bills | Discount | Credit | VAT | Stock,
>       quantity?: number,
>       description: string,
>       price?: number,
>       sales_tax_rate?: number,
>       second_sales_tax_rate?: number,
>       sales_tax_status?: TAXABLE | EXEMPT,
>       second_sales_tax_status?: string,
>       stock_item?: string,
>       category?: string,
>       project?: string
>     }
>   )[]
> }
> ```

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### updateDefaultAdditionalText

`invoices.updateDefaultAdditionalText`

Update the default additional text for company invoices

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.invoices.updateDefaultAdditionalText({ default_additional_text: 'Pay within 7 days' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `default_additional_text` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `default_additional_text` | `string` | Yes | — |

***

## Projects

### create

`projects.create`

Create a project with documented project fields

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.projects.create({
	project: {
		contact: 'https://api.freeagent.com/v2/contacts/1',
		name: 'Example Project',
		status: 'Active',
		currency: 'GBP',
		budget_units: 'Hours',
	},
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | `object` | Yes | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
>   contact: string,
>   name: string,
>   status: Active | Completed | Cancelled | Hidden,
>   contract_po_reference?: string,
>   uses_project_invoice_sequence?: boolean,
>   currency: string,
>   budget?: number,
>   budget_units: Hours | Days | Monetary,
>   hours_per_day?: number,
>   normal_billing_rate?: number,
>   billing_period?: hour | day,
>   is_ir35?: boolean,
>   starts_on?: string,
>   ends_on?: string,
>   include_unbilled_time_in_profitability?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | `object` | Yes | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
>   contact?: string | {
>   },
>   name?: string,
>   status?: string,
>   contract_po_reference?: string,
>   uses_project_invoice_sequence?: boolean,
>   currency?: string,
>   budget?: string | number | null,
>   budget_units?: string,
>   hours_per_day?: string | number | null,
>   normal_billing_rate?: string | number | null,
>   billing_period?: string | null,
>   is_ir35?: boolean,
>   starts_on?: string | null,
>   ends_on?: string | null,
>   include_unbilled_time_in_profitability?: boolean,
>   url?: string,
>   contact_name?: string,
>   is_deletable?: boolean,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### delete

`projects.delete`

Delete a project

**Risk:** `destructive`

```ts theme={null}
await corsair.freeagent.api.projects.delete({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

### get

`projects.get`

Get a project by its FreeAgent ID

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.projects.get({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `project` | `object` | Yes | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
>   contact?: string | {
>   },
>   name?: string,
>   status?: string,
>   contract_po_reference?: string,
>   uses_project_invoice_sequence?: boolean,
>   currency?: string,
>   budget?: string | number | null,
>   budget_units?: string,
>   hours_per_day?: string | number | null,
>   normal_billing_rate?: string | number | null,
>   billing_period?: string | null,
>   is_ir35?: boolean,
>   starts_on?: string | null,
>   ends_on?: string | null,
>   include_unbilled_time_in_profitability?: boolean,
>   url?: string,
>   contact_name?: string,
>   is_deletable?: boolean,
>   created_at?: string,
>   updated_at?: string
> }
> ```

***

### list

`projects.list`

List projects with documented filters and pagination

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.projects.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number,
>   view?: string,
>   sort?: string,
>   updated_since?: string,
>   from_date?: string,
>   to_date?: string,
>   contact?: string,
>   nested?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `projects` | `object[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] projects full type
>
> ```ts theme={null}
> {
>   contact?: string | {
>   },
>   name?: string,
>   status?: string,
>   contract_po_reference?: string,
>   uses_project_invoice_sequence?: boolean,
>   currency?: string,
>   budget?: string | number | null,
>   budget_units?: string,
>   hours_per_day?: string | number | null,
>   normal_billing_rate?: string | number | null,
>   billing_period?: string | null,
>   is_ir35?: boolean,
>   starts_on?: string | null,
>   ends_on?: string | null,
>   include_unbilled_time_in_profitability?: boolean,
>   url?: string,
>   contact_name?: string,
>   is_deletable?: boolean,
>   created_at?: string,
>   updated_at?: string
> }[]
> ```

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***

### update

`projects.update`

Update documented fields on a project

**Risk:** `write`

```ts theme={null}
await corsair.freeagent.api.projects.update({
	id: '1',
	project: { name: 'Example Project' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `project` | `object` | Yes | — |

> [accordion] project full type
>
> ```ts theme={null}
> {
>   contact?: string,
>   name?: string,
>   status?: Active | Completed | Cancelled | Hidden,
>   contract_po_reference?: string,
>   uses_project_invoice_sequence?: boolean,
>   currency?: string,
>   budget?: number,
>   budget_units?: Hours | Days | Monetary,
>   hours_per_day?: number,
>   normal_billing_rate?: number,
>   billing_period?: hour | day,
>   is_ir35?: boolean,
>   starts_on?: string,
>   ends_on?: string,
>   include_unbilled_time_in_profitability?: boolean
> }
> ```

**Output:** `object \| undefined`

> [accordion] Output full type
>
> ```ts theme={null}
> {
> } | undefined
> ```

***

## Recurring Invoices

### get

`recurringInvoices.get`

Get a recurring invoice by its FreeAgent ID

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.recurringInvoices.get({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `recurring_invoice` | `object` | Yes | — |

> [accordion] recurring\_invoice full type
>
> ```ts theme={null}
> {
>   url: string,
>   contact: string,
>   contact_name?: string,
>   reference?: string,
>   dated_on: string,
>   frequency: Weekly | Two Weekly | Four Weekly | Monthly | Two Monthly | Quarterly | Biannually | Annually | 2-Yearly,
>   next_recurs_on: string,
>   recurring_end_date?: string | "",
>   recurring_status: Draft | Active,
>   currency?: string,
>   exchange_rate?: string,
>   net_value?: string,
>   sales_tax_value?: string,
>   total_value?: string,
>   omit_header?: boolean,
>   always_show_bic_and_iban?: boolean,
>   payment_terms_in_days?: number,
>   invoice_items?: {
>     url?: string,
>     position?: number,
>     description?: string,
>     item_type?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     sales_tax_status?: TAXABLE | EXEMPT,
>     category?: string
>   }[],
>   payment_methods?: Record<string, boolean>
> }
> ```

***

### list

`recurringInvoices.list`

List recurring invoices with documented filters and pagination

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.recurringInvoices.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

Supports the documented draft, active, or inactive view filter and a contact URL filter. Collection pagination uses the standard page and per\_page parameters.

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number,
>   view?: draft | active | inactive,
>   contact?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `recurring_invoices` | `object[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] recurring\_invoices full type
>
> ```ts theme={null}
> {
>   url: string,
>   contact: string,
>   contact_name?: string,
>   reference?: string,
>   dated_on: string,
>   frequency: Weekly | Two Weekly | Four Weekly | Monthly | Two Monthly | Quarterly | Biannually | Annually | 2-Yearly,
>   next_recurs_on: string,
>   recurring_end_date?: string | "",
>   recurring_status: Draft | Active,
>   currency?: string,
>   exchange_rate?: string,
>   net_value?: string,
>   sales_tax_value?: string,
>   total_value?: string,
>   omit_header?: boolean,
>   always_show_bic_and_iban?: boolean,
>   payment_terms_in_days?: number,
>   invoice_items?: {
>     url?: string,
>     position?: number,
>     description?: string,
>     item_type?: string,
>     price?: string | number,
>     quantity?: string | number,
>     sales_tax_rate?: string | number,
>     sales_tax_status?: TAXABLE | EXEMPT,
>     category?: string
>   }[],
>   payment_methods?: Record<string, boolean>
> }[]
> ```

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***

## Tracking Groups

### get

`trackingGroups.get`

Get a tracking group and its labels by FreeAgent ID

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.trackingGroups.get({ id: '1' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tracking_group` | `object` | Yes | — |

> [accordion] tracking\_group full type
>
> ```ts theme={null}
> {
>   url: string,
>   name: string,
>   status: active | hidden,
>   labels: {
>     url: string,
>     name: string,
>     status: active | hidden
>   }[],
>   created_at: string,
>   updated_at: string
> }
> ```

***

### list

`trackingGroups.list`

List tracking groups with documented filters and pagination

**Risk:** `read`

```ts theme={null}
await corsair.freeagent.api.trackingGroups.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `query` | `object` | No | — |

Hidden groups and labels are omitted by default. Use include\_hidden, order\_by, and reverse as documented; collection pagination uses page and per\_page.

> [accordion] query full type
>
> ```ts theme={null}
> {
>   page?: number,
>   per_page?: number,
>   include_hidden?: boolean,
>   order_by?: name | status | labels_count,
>   reverse?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tracking_groups` | `object[]` | Yes | — |
| `pagination` | `object` | Yes | — |

> [accordion] tracking\_groups full type
>
> ```ts theme={null}
> {
>   url: string,
>   name: string,
>   status: active | hidden,
>   labels: {
>     url: string,
>     name: string,
>     status: active | hidden
>   }[],
>   created_at: string,
>   updated_at: string
> }[]
> ```

> [accordion] pagination full type
>
> ```ts theme={null}
> {
>   link: string | null,
>   total_count: string | null
> }
> ```

***


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