# Public API overview

> Build a third-party application that integrates with AccountFUN over a secure OAuth 2.0 REST API.

Source: https://www.accountfun.com/docs/api/

AccountFUN exposes a versioned REST API that lets your application read and write accounting data on behalf of an AccountFUN user. The API uses the **OAuth 2.0 Authorization Code grant** (RFC 6749 / RFC 9700) so a user explicitly consents to what your app can access, and every request is scoped to a single organization.

This section is written for developers building integrations — storefront plugins, automation tools, reporting dashboards, or any app that needs to push or pull data from a user’s AccountFUN organization.

## How it works at a glance

1. **Register a client application** inside AccountFUN to receive a `client_id` and `client_secret`.
2. **Send the user through the authorization flow.** They sign in to AccountFUN, pick the organization to connect, and approve the scopes your app requests.
3. **Exchange the authorization code for tokens.** You receive a short-lived access token (and, with `offline_access`, a refresh token).
4. **Call the API.** Send the access token as a `Bearer` credential. Every request operates inside the organization the user authorized — the org boundary is enforced server-side.

```text
Your app            AccountFUN               User's browser
   │                     │                          │
   │  ── redirect ────────────────────────────────▶ │  authorize screen
   │                     │  ◀── sign in + consent ──┤
   │  ◀── code ─────────────────────────────────────│  redirect with ?code=
   │  ── exchange code ─▶│                          │
   │  ◀── access token ──┤                          │
   │  ── GET /invoices ─▶│                          │
   │  ◀── JSON data ─────┤                          │
```

## Base URL

All requests go to your AccountFUN host. For the production service this is:

```text
https://app.accountfun.com
```

The OAuth endpoints live under `/api/v1/oauth/` and the resource endpoints under `/api/v1/`. Full paths are given on each reference page.

## What you can do today

The API is growing. The current v1 surface covers the resources most integrations need first:

| Resource          | Read                                                                         | Write                                                                               | Reference                                                                   |
| ----------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Invoices          | List, fetch                                                                  | Create, edit, submit, approve, void, revert, delete                                 | [Invoices](https://www.accountfun.com/docs/api/invoices/)                   |
| Bills             | List, fetch, list attachments                                                | Create, edit, submit, approve, void, revert, delete, attach receipts                | [Bills](https://www.accountfun.com/docs/api/bills/)                         |
| Expense claims    | List, list attachments                                                       | Create, approve your own, attach receipts                                           | [Expense claims](https://www.accountfun.com/docs/api/expense-claims/)       |
| Payments          | List, fetch                                                                  | Record, reverse, attach files                                                       | [Payments](https://www.accountfun.com/docs/api/payments/)                   |
| Bank transactions | Fetch a transaction                                                          | Spend money, receive money, transfer between accounts                               | [Bank transactions](https://www.accountfun.com/docs/api/bank-transactions/) |
| Credit notes      | List, fetch                                                                  | Create, edit, submit, approve, void, revert, delete, allocate, refund, attach files | [Credit notes](https://www.accountfun.com/docs/api/credit-notes/)           |
| Prepayments       | List, fetch                                                                  | Create, submit, approve, void, allocate, un-allocate, refund, reverse refunds       | [Prepayments](https://www.accountfun.com/docs/api/prepayments/)             |
| Contacts          | List, fetch                                                                  | Create, edit, deactivate, delete                                                    | [Contacts](https://www.accountfun.com/docs/api/contacts/)                   |
| Organization      | Fetch metadata                                                               | —                                                                                   | [Organization](https://www.accountfun.com/docs/api/organisation/)           |
| Chart of accounts | List                                                                         | —                                                                                   | [Chart of accounts](https://www.accountfun.com/docs/api/chart-of-accounts/) |
| Tax rates         | List                                                                         | —                                                                                   | [Tax rates](https://www.accountfun.com/docs/api/tax-rates/)                 |
| Items & inventory | List, fetch                                                                  | —                                                                                   | [Items](https://www.accountfun.com/docs/api/)                               |
| Projects          | List, fetch, money summary                                                   | —                                                                                   | [Projects](https://www.accountfun.com/docs/api/)                            |
| Fixed assets      | List, fetch (with depreciation schedule)                                     | —                                                                                   | [Fixed assets](https://www.accountfun.com/docs/api/)                        |
| Reports           | Trial balance, profit & loss, balance sheet, AR/AP aging, contact statements | —                                                                                   | [AI assistants (MCP)](https://www.accountfun.com/docs/api/mcp/)             |
| AI assistants     | MCP server for AI assistants (chat assistants and coding agents)             | —                                                                                   | [AI assistants (MCP)](https://www.accountfun.com/docs/api/mcp/)             |

## Registering a client application

An AccountFUN administrator registers OAuth clients inside AccountFUN:

1. Sign in to AccountFUN, go to **Settings → API & Developers** and click **New App**.
2. Give the client a **name** (shown to users on the consent screen). It can’t contain invisible or text-direction (bidi) characters.
3. Add one or more **redirect URIs**. These must be exact, HTTPS URLs (`http://localhost` / `127.0.0.1` are allowed for local development).
4. Select the **scopes** the client may request.
5. Save. You’ll be shown the **client secret** once — store it securely, because it cannot be retrieved later (it can only be rotated).

The `client_id` is public and safe to embed in front-end code. The `client_secret` is confidential and must never appear in a browser or mobile app. Keep it on your server.

Which organizations a client can connect to

A client can be connected only to organizations that the person who registered it belongs to. Anyone in those organizations can authorize it with their own sign-in, choosing which of them to connect. Members of any other organization see ”… was set up in another organization, so it can’t be connected here”: an admin of their organization registers the app there, under **Settings → API & Developers**.

## Scopes

Scopes are fixed strings that declare what your app wants to do. The user sees them on the consent screen and approves or denies each request. A token can never carry a scope broader than what its client is registered for, and never broader than what the user granted at consent.

| Scope                                                                   | Grants                                                                           |
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `invoices:read`                                                         | View invoices                                                                    |
| `invoices:write`                                                        | Create draft invoices                                                            |
| `invoices:approve`                                                      | Approve invoices, which posts them to the books. Opt-in.                         |
| `bills:read`                                                            | View bills and their attachments                                                 |
| `bills:write`                                                           | Create draft bills, attach receipts and add notes to them                        |
| `bills:approve`                                                         | Approve bills, which posts them to the books. Opt-in.                            |
| `expense_claims:read`                                                   | View expense claims and their receipts                                           |
| `expense_claims:write`                                                  | Create draft expense claims and attach receipts to them                          |
| `expense_claims:approve`                                                | Approve your own expense claims, which posts them to the books. Opt-in.          |
| `payments:read`                                                         | View payments (customer receipts and supplier payments)                          |
| `payments:write`                                                        | Record and reverse payments, attach remittance files and add notes. Opt-in.      |
| `bank_transactions:read`                                                | View spend money, receive money and transfer transactions                        |
| `bank_transactions:write`                                               | Spend, receive and transfer money between bank accounts. Opt-in.                 |
| `credit_notes:read`                                                     | View credit notes                                                                |
| `credit_notes:write`                                                    | Create draft credit notes, attach files and add notes to them                    |
| `credit_notes:approve`                                                  | Approve and void credit notes, which posts them to the books. Opt-in.            |
| `credit_notes:settle`                                                   | Apply credit notes to invoices/bills and refund them, which moves money. Opt-in. |
| `prepayments:read`                                                      | View prepayments (customer and supplier advances)                                |
| `prepayments:write`                                                     | Create and submit draft prepayments. Opt-in.                                     |
| `prepayments:approve`                                                   | Approve and void prepayments, which posts them to the books. Opt-in.             |
| `prepayments:settle`                                                    | Apply prepayments to invoices/bills, refund them and reverse refunds. Opt-in.    |
| `contacts:read`                                                         | View contacts                                                                    |
| `contacts:write`                                                        | Create and edit contacts                                                         |
| `org:read`                                                              | View organization details                                                        |
| `chart_of_accounts:read`                                                | View the chart of accounts                                                       |
| `tax_rates:read`                                                        | View tax rates                                                                   |
| `items:read` · `tracking:read` · `projects:read` · `bank_accounts:read` | View products, tracking categories, projects and bank accounts                   |
| `reports:read` · `fixed_assets:read`                                    | View financial reports and fixed assets                                          |
| `invoices:delete` · `bills:delete` · `credit_notes:delete`              | Delete documents (a posted one is reversed first). Opt-in.                       |
| `offline_access`                                                        | Request a refresh token for long-lived access                                    |

Except for `offline_access`, every scope also needs the authorizing user’s role in the organization to allow it — a ceiling, not a floor.

**Approving** a document posts it to the ledger, so each document type has its own approve scope — `invoices:approve`, `bills:approve`, `credit_notes:approve` and `prepayments:approve` — that the `*:write` scopes don’t include, and the user’s role must have the **Approve Documents** permission (the built-in Admin, Accountant and Standard roles have it; Purchase and Sales don’t). Each approve scope approves only its own document type: `invoices:approve` can’t approve a bill, and `bills:approve` can’t approve an invoice. Bills additionally need a role that includes purchase documents.

**Expense claims** are filed by staff and only post when their final approval creates a supplier bill. `expense_claims:approve` needs the **Approve Expense Claims** permission (Admin and Accountant by default), and — through the API or an AI assistant — a user can approve only the claims **they filed themselves**; approving another member’s claim stays inside AccountFUN. See [Expense claims](https://www.accountfun.com/docs/api/expense-claims/).

**Moving money** is opt-in too: `payments:write` (record/reverse payments), `bank_transactions:write` (spend, receive and transfer money) and the settle scopes `credit_notes:settle` / `prepayments:settle` (apply, refund, reverse) each need the authorizing role’s **Record Payments** permission. Creating a draft prepayment is itself opt-in (`prepayments:write`), while draft credit notes need only `credit_notes:write` and the **Create Drafts** permission. Documents, payments, credit notes and prepayments follow their side of the books: a receivable record (a customer receipt or credit, a `receive` prepayment) needs the role’s sales access, and a payable record (a supplier payment or credit, a `spend` prepayment) needs its purchase access. See [Authentication](https://www.accountfun.com/docs/api/authentication/) for the role-ceiling model.

**Deleting** a document is its own opt-in scope — `invoices:delete`, `bills:delete`, `credit_notes:delete` — and needs the role’s **Delete Documents** permission. A posted document is reversed first, and deleting is refused while a document has payments, credit notes or prepayments applied.

The consent screen offers every opt-in scope as an unticked checkbox under **Only if you tick it:** — if the user doesn’t tick one, it’s left out of the grant. Access the user’s role can’t grant in the selected organization is left out too. The token response’s `scope` lists exactly what was granted, so read it rather than assuming you got everything you asked for.

Requesting **any money scope** (`payments:write`, `bank_transactions:write`, `credit_notes:approve`, `credit_notes:settle`, `prepayments:write`, `prepayments:approve`, `prepayments:settle`, `bills:approve`, `invoices:approve`, `expense_claims:approve`) makes the consent screen show a red **“This app can move money”** warning, and a connection that holds one is badged **Can Move Money** under **Settings → Account → Connected Apps** — admins see the same badge under **Settings → Authorized Applications**. AI assistants that move money have further guardrails: server-enforced confirmation, an organization **Money Actions** policy and per-connection velocity limits. See [MCP money guardrails](https://www.accountfun.com/docs/api/mcp/#guardrails).

## Authentication

Every resource request must carry a valid access token:

```http
Authorization: Bearer <access_token>
```

Tokens are opaque, 64-hex-character strings. They are valid for **30 minutes**. With the `offline_access` scope, you also receive a **refresh token** valid for **30 days of inactivity** (rolling, with no absolute cap) so your app can keep working when the user is away. See the [Authentication guide](https://www.accountfun.com/docs/api/authentication/) for the complete flow, token refresh, and revocation.

## Versioning

The API is versioned in the URL path (`/api/v1/`). Breaking changes ship under a new version. Within v1 we avoid breaking changes; new fields and endpoints are additive and safe to ignore if your app does not use them.

## Machine-readable docs

For code generators, API clients and AI coding assistants:

| What                                                            | URL                                                                                         |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| OpenAPI 3.1 spec of every v1 endpoint                           | `https://app.accountfun.com/api/v1/openapi.json`                                            |
| Docs index for AI assistants ([llms.txt](https://llmstxt.org/)) | `https://www.accountfun.com/llms.txt`                                                       |
| All docs in one Markdown file                                   | `https://www.accountfun.com/docs/llms-full.txt`                                             |
| Developer docs only (API, OAuth, MCP)                           | `https://www.accountfun.com/docs/_llms-txt/developer-platform.txt`                          |
| Any docs page as Markdown                                       | replace the trailing `/` with `.md`, e.g. `https://www.accountfun.com/docs/api/invoices.md` |

The OpenAPI spec is public (no token needed) and is built from the same code that serves the API. Import it into Postman, Insomnia or an OpenAPI client generator, or hand it to an AI assistant that writes your integration. To let an AI assistant work in AccountFUN directly, use the [MCP server](https://www.accountfun.com/docs/api/mcp/) instead.

## Next steps

* **[API quickstart](https://www.accountfun.com/docs/api/quickstart/)** — make your first API call in ten minutes with `curl`.
* **[Sample app](https://www.accountfun.com/docs/api/sample-app/)** — a runnable Node.js or Python integration you can copy and adapt.
* **[Sandbox](https://www.accountfun.com/docs/api/sandbox/)** — test your integration against a non-live sandbox organization seeded with demo data.
* **[Authentication](https://www.accountfun.com/docs/api/authentication/)** — the full OAuth flow, token refresh, PKCE, and revocation.
* **[Invoices](https://www.accountfun.com/docs/api/invoices/)** — list, create, and fetch invoices.
* **[Expense claims](https://www.accountfun.com/docs/api/expense-claims/)** — file staff expense claims, attach receipts, and approve your own.
* **[Payments](https://www.accountfun.com/docs/api/payments/)** — record and reverse customer receipts and supplier payments.
* **[Credit notes](https://www.accountfun.com/docs/api/credit-notes/)** and **[prepayments](https://www.accountfun.com/docs/api/prepayments/)** — adjust and advance money, then apply or refund it.
* **[Bank transactions](https://www.accountfun.com/docs/api/bank-transactions/)** — spend, receive, and transfer money between bank accounts.
* **[Contacts](https://www.accountfun.com/docs/api/contacts/)** — manage customers and suppliers.
* **[Errors & rate limits](https://www.accountfun.com/docs/api/errors-and-limits/)** — status codes, error shapes, and throttling.