<!-- / -->
# Bookkeeping and tax filing inside your platform

Create companies and users from your backend, then show FinBaze components in your product or call the API headless.

FinBaze for Platforms lets your customers do their bookkeeping and file their taxes without leaving your product. You keep the relationship and the look; FinBaze keeps the books, the ledger and the filings.

## How it fits together

1. **Your backend** creates a *company* and a hidden *user* in FinBaze with a secret key, and creates an *embed session* when a user opens a page.
2. **Your page** loads `@finbaze/embed-js` (or `@finbaze/embed-react`) with a publishable key. The SDK asks your backend for a client secret and mounts FinBaze components in iframes.
3. **FinBaze** runs the components, holds the user's token inside its own iframe and files with the tax authority.

Prefer your own UI? Use the [headless hooks](/sdks/headless) or the [GraphQL API](/reference/graphql) from your backend.

## Where to start

- [Quickstart](/quickstart): a VAT overview in your app in about an hour.
- [Concepts](/concepts/platforms-and-companies): the model, in five short pages.
- [Component gallery](/components/gallery): try every component on seeded sandbox companies.
- [`llms.txt`](/llms.txt): this site as plain text for your coding assistant.

> **Sandbox first**
>
> Everything here works in the sandbox with test keys (`fb_sk_test_…`, `fb_pk_test_…`). Companies there are fake and nothing is filed with a real tax authority.


---

<!-- /quickstart -->
# Quickstart

From a test key to a working embedded component, in ten steps.

You will create a company and a user, mint an embed session on your server and show the tax calendar in a React page. All steps use the **sandbox**.

## 1. Get test keys

In the developer portal open **Keys** and create a secret key and copy the publishable key. Test keys start with `fb_sk_test_` and `fb_pk_test_`. The secret key stays on your server.

## 2. Allow your origin

Under **Embedding → Allowed origins** add the origin of the page that will show the components, for example `http://localhost:3000`. Components refuse to load anywhere else.

## 3. Get a server token

Exchange the secret key for a short-lived token:

```bash
curl https://sandbox.api.platform.finbaze.com/v2/oauth2/token \
  -H 'content-type: application/json' \
  -d '{"grant_type":"client_credentials","client_secret":"fb_sk_test_…"}'
```

Send the `access_token` as `Authorization: Bearer …` on every GraphQL request to `https://sandbox.api.platform.finbaze.com/graphql`.

## 4. Create a company

```graphql
mutation {
  createPlatformCompany(input: {
    externalId: "acme-1"
    registrationCountry: NL
    registrationNumber: "12345678"
  }) {
    company { id name }
    created
  }
}
```

`externalId` is *your* id; calling this again with the same id returns the same company. The returned `company.id` is the profile id the rest of the API uses.

## 5. Create a user and give them access

```graphql
mutation {
  upsertPlatformUser(input: { externalUserId: "user-42", firstName: "Sam", lastName: "Jansen" }) { id }
  setPlatformUserAccess(input: { externalUserId: "user-42", profileId: "<company id>", role: admin }) { role }
}
```

Users are hidden: they never get a FinBaze login or email. See [platforms and companies](/concepts/platforms-and-companies).

## 6. Add an endpoint that creates embed sessions

Your page cannot hold the secret key, so it asks *your* backend. The backend authenticates your user and creates a session:

```ts
app.post("/finbaze/session", requireLogin, async (req, res) => {
  const { data } = await finbaze(`
    mutation($input: CreateEmbedSessionInput!) {
      createEmbedSession(input: $input) { clientSecret }
    }`, {
    input: {
      companyId: req.user.finbazeCompanyId,
      user: { externalUserId: req.user.id },
      components: { taxCalendar: { enabled: true } },
      previousSessionId: req.body.previousSessionId,
    },
  });
  res.json({ clientSecret: data.createEmbedSession.clientSecret });
});
```

Each client secret works **once** and for 15 minutes. Do not cache it. Pass `previousSessionId` through; it links refreshes into one chain.

## 7. Install the SDK

```bash
npm install @finbaze/embed-react
```

## 8. Show a component

```tsx
import { FinBazeProvider, FinBazeTaxCalendar } from "@finbaze/embed-react";

export function Taxes() {
  return (
    <FinBazeProvider
      publishableKey="fb_pk_test_…"
      fetchClientSecret={async ({ previousSessionId }) => {
        const res = await fetch("/finbaze/session", {
          method: "POST",
          headers: { "content-type": "application/json" },
          body: JSON.stringify({ previousSessionId }),
        });
        return (await res.json()).clientSecret;
      }}
    >
      <FinBazeTaxCalendar onError={(e) => console.error(e)} />
    </FinBazeProvider>
  );
}
```

The SDK calls `fetchClientSecret` again before the token expires, so the component keeps working.

## 9. Match your look

```tsx
<FinBazeProvider appearance={{ theme: "auto", variables: { colorPrimary: "#0a7d5a", borderRadius: "10px" } }} …>
```

See the [appearance reference](/components/appearance).

## 10. Next steps

- Listen to [events](/components/events) such as `filing.submitted`.
- Read the [embed security model](/concepts/embed-security-model) before going live.
- Handle [errors](/reference/errors).


---

<!-- /guides -->
# Guides

How to build the integration for your kind of platform, and how to use each part of FinBaze.

Concepts explain how one part of FinBaze works. Guides put the parts together for a kind of product. Every guide ends with how to try it in the sandbox: a seeded demo company, a test clock and a webhook receiver you can run locally.

## By partner type

| You are | Start here | You will use |
| --- | --- | --- |
| A bank or neobank | [Banks](/guides/banks) | Bank feed push, `booking-chip`, receipts from the camera, VAT paid from the account, tax reservation |
| A point-of-sale vendor | [Point of sale](/guides/pos) | Z-report as a custom record, a flow template, tips and cash differences, VAT return |
| A logistics or TMS vendor | [Logistics](/guides/logistics) | Shipment record, invoice from a flow template, carrier invoices, ICP and OSS, reverse charge |
| An e-commerce platform | [E-commerce](/guides/ecommerce) | Orders to invoices, OSS, refunds as credit notes |
| A scheduling or workforce product | [Scheduling and hours](/guides/scheduling) | Worked hours feed, employees and employments |

## By part of FinBaze

| Part | Guide |
| --- | --- |
| Bank data, statements, feed health | [Data sources](/guides/data-sources) |
| What FinBaze says to your users | [Messages and routing](/guides/messages-and-routing) |
| Invoices and payslips in your branding | [Documents](/guides/documents) |
| Hiding parts of FinBaze for some companies | [Features and limits](/guides/features-and-limits) |
| Accounting firms on your companies | [Firms](/guides/firms) |
| Closing, moving and exporting a company | [Lifecycle and migration](/guides/lifecycle-and-migration) |
| iOS, Android and React Native | [Mobile](/guides/mobile) |

## Runnable examples

[Sample apps](/guides/sample-apps) lists the six sample repositories, each with a deploy button, a README and an end-to-end script that runs against the sandbox every night.

## How these guides were checked

Every GraphQL block in these pages is validated against the current schema in CI, and every operation name they mention must exist in it. Flow templates in the guides are the same files that live in the sample apps, and those are parsed by the API's own template parser in the API test suite. Where a guide depends on something that is not released yet, it says so in a note.


---

<!-- /guides/banks -->
# Banks and neobanks

Push the bank feed, show bookings next to your own transactions, capture receipts, pay the VAT from the account and set money aside for tax.

A bank or neobank already has the account and the transactions. FinBaze adds the books and the tax filings on top of them. This guide follows one business customer from "connect" to "VAT paid from the account". The [neobank demo](/guides/sample-apps) is the same flow as running code.

## What you build

| Step | Your side | FinBaze side |
| --- | --- | --- |
| 1. A business signs up | `createPlatformCompany`, `upsertPlatformUser`, `setPlatformUserAccess` | The company and its books exist. |
| 2. Booked transactions flow in | `ingestBankTransactions`, `reportBankBalances`, `reportFeedWatermark` | Transactions are categorised and matched with receipts; balances are checked. |
| 3. Bookings show in your app | `booking-chip` next to each transaction | Chip shows how the transaction is booked. |
| 4. Receipts from the camera | `receipt-button`, `onCameraCapture` | The photo is attached and read. |
| 5. VAT return, paid from the account | `vat-return`, `onPaymentRequested` | Return is filed with the company's consent; a payment request carries the amount and the Belastingdienst reference. |
| 6. Tax money set aside | `tax_reservation` provider, `reportTaxReservation` | Advice says how much to reserve now. |

## 1. Company and user

```graphql
mutation {
  createPlatformCompany(input: { externalId: "biz-1001", registrationCountry: NL, registrationNumber: "12345678" }) {
    company { id name }
    created
  }
}
```

`externalId` is your customer id; calling again with the same id returns the same company. Create the user the same way (`upsertPlatformUser`) and give it a role on the company with `setPlatformUserAccess`. See [Platforms and companies](/concepts/platforms-and-companies).

## 2. The bank feed

Register one data source for your feed, attach it to every new company, then deliver. Everything you push keeps your ids, so sending a line twice is harmless.

```graphql
mutation {
  registerDataSource(input: {
    key: "acme-bank"
    type: bank_feed
    name: "Acme Bank accounts"
    cadence: realtime
    balanceAssertions: true
    autoAttach: true
  }) { id key }
}
```

```graphql
mutation Account($company: CompanyRef!) {
  upsertFeedBankAccount(source: "acme-bank", company: $company, account: {
    externalId: "acc-77"
    iban: "NL91ABNA0417164300"
    name: "Business account"
    currency: EUR
  }) { id health }
}
```

```graphql
mutation Push($company: CompanyRef!, $lines: [BankTransactionFeedInput!]!) {
  ingestBankTransactions(source: "acme-bank", company: $company, account: "acc-77", transactions: $lines) {
    line status externalId error { code message }
  }
}
```

A line looks like `{ externalId: "tx-90210", bookingDate: "2026-03-02", amountMinor: -12500, currency: EUR, counterparty: { name: "Office Supply BV", iban: "NL02ABNA0123456789" }, description: "Invoice 2026-114", endToEndId: "..." }`. Amounts are in minor units: negative is money out.

- **Booked only.** Lines with `status: pending` are skipped. Push a line when the bank has booked it.
- **A booked line never changes.** Changing it fails with `IMMUTABLE_TRANSACTION`. Send a reversal (`reverses: "<externalId>"`) and a new transaction.
- **Send balances.** `reportBankBalances` with the closing balance per day lets FinBaze check that the transactions add up. A mismatch changes nothing in the books and raises `feed.balance_mismatch`.
- **Send the heartbeat.** `reportFeedWatermark(completeThrough: "2026-03-02")` says "everything up to this date is delivered". A quiet account needs it to count as healthy, not as a gap.

[Data sources](/guides/data-sources) covers statement files, backfill and feed health in detail.

## 3. A booking chip next to each transaction

In your transaction list, mount `booking-chip` with your own transaction id. No FinBaze id needed.

```tsx
import { FinBazeProvider, FinBazeBookingChip } from "@finbaze/embed-react";

function Row({ accountId, tx }: { accountId: string; tx: { id: string } }) {
  return <FinBazeBookingChip bankAccountId={accountId} externalId={tx.id} size="sm" onBookingChanged={() => refresh()} />;
}
```

Create the session with `components: { bookingChip: { enabled: true } }`. See the [`booking-chip` page](/components/booking-chip) for its options and events.

## 4. Receipts from the camera

`receipt-button` attaches a photo to a transaction. In a web page it opens the phone's own camera through a file input. In an app, pass `onCameraCapture` to `loadFinBaze` (or `FinBazeProvider`) and open your scanner; resolve with `{ name, mime, data }` or `null` when the user cancels.

```ts
onCameraCapture: async ({ purpose, accept, maxBytes }) => {
  const photo = await myScanner.capture({ accept, maxBytes });
  return photo ? { name: photo.name, mime: photo.mime, data: photo.bytes } : null;
},
```

Mobile wrappers are covered in [Mobile](/guides/mobile).

## 5. VAT, paid from the account

The VAT return is filed only with the company's authorisation, which its admin gives in the `onboarding` or `tax-authorisation` component. See [Filing consent](/concepts/filing-consent). A submit without it fails with `TAX_AUTHORISATION_REQUIRED`.

Register your payment provider once:

```graphql
mutation {
  upsertPlatformProvider(input: { action: payments, mode: both, config: { kinds: ["tax"], includePain001: false } }) { id enabled }
}
```

This needs the `delegated.payment_requests` feature in your allowance (`FEATURE_NOT_ALLOWED` otherwise). Then show the return and handle the Pay button:

```tsx
<FinBazeProvider
  publishableKey={pk}
  fetchClientSecret={fetchClientSecret}
  onPaymentRequested={async (request) => {
    // request.lines: creditor, IBAN, amountMinor, structuredReference, endToEndId
    const transfer = await openTransferScreen(request.lines, request.endToEndId);
    return { status: transfer.confirmed ? "accepted" : "cancelled", partnerReference: transfer.id };
  }}
>
  <FinBazeVatReturn period="current" />
</FinBazeProvider>
```

- Pay exactly the lines in the request. The creditor and the reference are fixed by FinBaze.
- Put the line's `endToEndId` in the SEPA `EndToEndId`. That is what matches the payment later.
- You never report "paid". The request becomes `paid` when the transaction arrives in the feed (step 2) and matches by end-to-end id, or for tax by the reference, the Belastingdienst IBAN and the exact amount.
- Without `onPaymentRequested` there is no Pay button.

If the user must confirm with biometrics or SCA, add a `step_up` provider and `onStepUp`. See [Delegated actions](/concepts/delegated-actions#step-up).

## 6. Money set aside for tax

```graphql
mutation {
  upsertPlatformProvider(input: { action: tax_reservation, mode: webhook, config: { taxes: ["nl_vat"], cadence: "weekly" } }) { id enabled }
}
```

FinBaze sends `tax_reservation.advised` with the amount to hold back for the open period. Move the money, then tell FinBaze:

```graphql
mutation { reportTaxReservation(adviceId: "…", reservedMinor: 42000, accountRef: "savings-tax") { id status } }
```

`taxReservationAdvice(company: …)` lists the advices. See [Delegated actions](/concepts/delegated-actions#tax-reservation).

## 7. Annual accounts

Annual accounts follow the same consent: the company authorises `nl_annual_accounts` in `tax-authorisation`. A dedicated annual-accounts view arrives with the extended component catalogue; the [component list](/components) shows what your build of the registry contains today, and nothing in your integration changes when it goes live.

## Try it in the sandbox

1. `seedTestCompany(input: { template: nl_eenmanszaak_services })` gives a sole trader with history ([Demo companies](/concepts/demo-companies)).
2. `createTestClock` and `advanceTestClock` run the quarter, with the simulated bank feed posting through the same path your feed uses ([Test clocks](/concepts/test-clocks)).
3. Run the [webhook receiver](/guides/sample-apps) locally and subscribe it, so you see `bank_transaction.booked`, `feed.balance_mismatch` and `payment_request.created`.

## Pitfalls

- Pushing `pending` lines: they are skipped, so the first booked version must come from you.
- Editing a booked line instead of reversing it.
- Forgetting `endToEndId` on the transaction that paid the request, so the request never becomes `paid`.
- Caching client secrets. Each secret is single use; return a new one from `fetchClientSecret` every time.


---

<!-- /guides/pos -->
# Point of sale

Turn the Z-report into bookings: sales per VAT rate, tips, cash differences, and a VAT return that follows.

A point-of-sale system produces one number set per till per day: the Z-report. FinBaze books it. You push the Z-report as a **custom record**; a **flow template** turns its state change into an invoice and a journal entry, with the same rules as the data API. The [POS demo](/guides/sample-apps) contains the code of this page.

> **Shipped Z-report type and template**
>
> FinBaze ships a `z_report` record type (the schema below, states `open` and `closed`) and a `pos-z-report` template with the `customer` and `sales` steps of section 2. To use them as they are, skip section 1 and call `activateFlowTemplate(key: "pos-z-report", version: 1)`: it copies the shipped template into your platform and activates the copy. Define your own type and template, as below, when you need more (tips, cash differences). The chart template policy can name your platform's tips, cash difference and deposit ledgers once (`tipsLedger`, `cashDifferenceLedger`, `depositLedger`); a template reads them as `{{ ledgers.tips }}`, `{{ ledgers.cash_difference }}` and `{{ ledgers.deposit }}`.

## 1. Define the record type

```graphql
mutation {
  definePlatformRecordType(input: {
    key: "z_report"
    name: "Z-report"
    schema: {
      type: "object"
      required: ["till", "closedAt", "sales"]
      properties: {
        till: { type: "string" }
        closedAt: { type: "string" }
        sales: { type: "array" }
        tipsMinor: { type: "integer" }
        cashDifferenceMinor: { type: "integer" }
      }
    }
    states: ["open", "closed"]
    initialState: "open"
    displayTemplate: "Z-report {{data.till}} {{data.closedAt}}"
  }) { version }
}
```

Changing the schema or states creates a new version; an identical call returns the current one.

## 2. The template

The template has two steps. The invoice is a daily sales invoice to a walk-in customer, one line per VAT rate. VAT comes from the tax code, never from the line, so the VAT return picks it up like any other invoice. The journal entry books tips and the cash difference on ledgers (a journal entry line is a ledger line; lines on a relation or an invoice are not supported yet).

```yaml
apiVersion: finbaze.com/flows/v1
kind: FlowTemplate
metadata: { key: pos-z-report, version: 1, recordType: z_report }
chart: rgs
ledgers:
  till_cash: "<ledger code of the till cash account>"
on:
  - transition: { to: closed }
    onDataChange: rebook
    steps:
      - id: customer
        upsert_relation:
          externalId: pos-walk-in
          legalName: Walk-in customers
      - id: sales
        create_sales_invoice:
          relation: "= steps.customer.id"
          date: "= $date(record.data.closedAt, 'Europe/Amsterdam')"
          currency: EUR
          reference: "= 'Z ' & record.data.till"
          finalise: true
          lines:
            - forEach: "= record.data.sales"
              as: row
              name: "= row.name"
              quantity: 1
              priceMinor: "= $net(row.grossMinor, row.taxCode)"
              taxCode: "= row.taxCode"
      - id: cash_difference
        when: "= record.data.cashDifferenceMinor != 0"
        create_journal_entry:
          description: "= 'Cash difference ' & record.data.till"
          date: "= $date(record.data.closedAt, 'Europe/Amsterdam')"
          lines:
            - { ledger: "{{ ledgers.cash_difference }}", amountMinor: "= -record.data.cashDifferenceMinor" }
            - { ledger: "{{ ledgers.till_cash }}", amountMinor: "= record.data.cashDifferenceMinor" }
```

`$net(grossMinor, taxCode)` turns a gross amount into net with the tax code's rate. `onDataChange: rebook` reverses the earlier bookings and books again when a closed report is corrected. Test it without writing anything:

```graphql
mutation Test($source: String!, $records: [JSON!]!) {
  testFlowTemplate(source: $source, format: yaml, records: $records) {
    valid
    errors { code message path }
    runs { recordExternalId trigger plannedObjects { stepId objectType action externalId } error { code message } }
  }
}
```

Then `saveFlowTemplate` (saving the same text again returns the same version) and `activateFlowTemplate(key: "pos-z-report", version: <the version it returned>)`. Activation checks that the ledgers named in `ledgers` exist in the companies' charts.

The [POS demo](/guides/sample-apps) ships the first two steps (`customer` and `sales`); add `cash_difference` once you know your ledger codes.

## 3. Push the Z-report

```graphql
mutation Z($company: JSON!, $data: JSON!) {
  upsertCustomRecord(input: { company: $company, type: "z_report", externalId: "till-1-2026-03-02", status: "closed", data: $data }) {
    status
    record { id revision effects { stepId objectType } }
  }
}
```

with `data` like `{ "till": "1", "closedAt": "2026-03-02T22:40:00Z", "sales": [{ "name": "Food", "grossMinor": 52500, "taxCode": "NL_2019_LOW" }, { "name": "Drinks", "grossMinor": 31000, "taxCode": "NL_2012_HIGH" }], "cashDifferenceMinor": -250 }`. The record id is yours, so pushing again changes nothing; a changed `data` bumps `revision`.

- Tips are not revenue. Book them in a separate journal entry step on `{{ ledgers.tips }}` if your policy names one; do not add them to a sales line.
- One run is one transaction: if a step fails nothing is kept and the run is `failed`. Runs of one record go in order, so fix the template or data and `retryFlowRun`. Events: `flow_run.succeeded`, `flow_run.failed`.

## 4. Settlements and the VAT return

The card settlement shows up in the bank. Push it with the [data source](/guides/data-sources) flow, or let the company connect its bank. Mount `vat-return` and `purchase-inbox` for the VAT return and incoming purchase invoices:

```tsx
<FinBazeVatReturn period="current" />
<FinBazePurchaseInbox tab="inbox" />
```

Create the session with `components: { vatReturn: { enabled: true }, purchaseInbox: { enabled: true } }`. The VAT return needs the company's filing consent ([Filing consent](/concepts/filing-consent)).

## Try it in the sandbox

`seedTestCompany(input: { template: nl_horeca_pos })` gives a hospitality sole trader with food at the low rate, drinks at the high rate and daily card settlements. Push a Z-report, check `plannedObjects` with `testFlowTemplate`, then advance a [test clock](/concepts/test-clocks) to the end of the quarter and open `vat-return`.

## Pitfalls

- Sending VAT amounts on lines: tax is derived from the tax code.
- Correcting a closed report by pushing a new report: update the same `externalId` instead, so the flow rebooks.
- Using a ledger code the company's chart does not have: activation fails; run `activateFlowTemplate` before go-live.


---

<!-- /guides/logistics -->
# Logistics and transport

Shipments to invoices from a flow template, carrier invoices, ICP and OSS, multiple currencies and reverse charge.

A transport management system knows when a shipment was delivered, what it cost and who pays. FinBaze books that. You push **shipments** as custom records; a **flow template** creates the sales invoice when a shipment is delivered and reverses it when it is cancelled. Carrier invoices go in as purchase invoices. The [TMS demo](/guides/sample-apps) contains the code of this page.

## 1. The shipment record

```graphql
mutation {
  definePlatformRecordType(input: {
    key: "shipment"
    name: "Shipment"
    schema: {
      type: "object"
      required: ["reference", "customer", "currency", "lanes"]
      properties: {
        reference: { type: "string" }
        customer: { type: "object" }
        currency: { type: "string" }
        deliveredAt: { type: "string" }
        lanes: { type: "array" }
      }
    }
    states: ["booked", "delivered", "cancelled"]
    initialState: "booked"
    transitions: { booked: ["delivered", "cancelled"], delivered: ["cancelled"] }
    displayTemplate: "Shipment {{data.reference}}"
  }) { version }
}
```

## 2. The template

```yaml
apiVersion: finbaze.com/flows/v1
kind: FlowTemplate
metadata: { key: shipment-invoicing, version: 1, recordType: shipment }
chart: rgs
on:
  - transition: { to: delivered }
    onDataChange: rebook
    steps:
      - id: customer
        upsert_relation:
          externalId: "= record.data.customer.id"
          legalName: "= record.data.customer.name"
          vatNumber: "= record.data.customer.vatNumber"
          registrationCountry: "= record.data.customer.country"
      - id: invoice
        create_sales_invoice:
          relation: "= steps.customer.id"
          date: "= $date(record.data.deliveredAt, 'Europe/Amsterdam')"
          currency: "= record.data.currency"
          reference: "= record.data.reference"
          finalise: true
          lines:
            - forEach: "= record.data.lanes"
              as: lane
              name: "Transport {{ lane.from }} - {{ lane.to }}"
              priceMinor: "= lane.revenueMinor"
              taxCode: "= lane.taxCode"
  - transition: { to: cancelled }
    steps:
      - id: credit
        reverse: { step: invoice }
```

Each lane carries its own `taxCode` (see [Reverse charge and the EU](#reverse-charge-and-the-eu)). A `reverse` step credits what an earlier run of the record created, using what that run recorded, so editing the template later never changes what is reversed. Test with `testFlowTemplate`, then `saveFlowTemplate` and `activateFlowTemplate` with the version it returned. The syntax is in [Records and flow templates](/concepts/records-and-flows).

Push the shipment and move it through its states with `upsertCustomRecord`:

```graphql
mutation Ship($company: JSON!, $data: JSON!) {
  upsertCustomRecord(input: { company: $company, type: "shipment", externalId: "SHP-2026-0042", status: "delivered", data: $data }) {
    status
    record { id revision effects { stepId objectType } runs { id status } }
  }
}
```

If a run fails (`flow_run.failed`), nothing of that run is kept and later runs of the record wait. Fix the data or template and call `retryFlowRun`.

> **Invoice editor in your shipment page**
>
> Showing FinBaze's invoice editor inside your shipment page needs the `invoice-editor` component of the extended catalogue. It is not in the registry of every environment yet. Check the [component list](/components) of the sandbox you use; until it is there, create invoices through the template as above and show the result with `transactions` and your own links.

## 3. Carrier invoices

A carrier invoice is a purchase invoice. Push it when it arrives and let the company approve it in `purchase-inbox`, or create it with `upsertPurchaseInvoice`:

```graphql
mutation Carrier($company: CompanyRef!) {
  upsertPurchaseInvoice(input: {
    company: $company
    externalId: "carrier-4411"
    purchaseInvoice: {
      relation: { externalId: "carrier-dhl" }
      currency: EUR
      date: "2026-03-04"
      number: "INV-4411"
      lines: [{ name: "Linehaul NL-DE", priceMinor: 84000, taxCode: "NL_2024_TRANSFER" }]
    }
  }) { status id }
}
```

Hidden modules still accept data, and a module that is switched off answers `FEATURE_DISABLED`. See [Sending data](/concepts/sending-data).

## Reverse charge and the EU

Tax is derived from the tax code on the line. These are the codes this guide uses:

| Situation | Tax code |
| --- | --- |
| Dutch customer, high rate | `NL_2012_HIGH` |
| Dutch customer, low rate | `NL_2019_LOW` |
| Dutch reverse charge (verlegd) | `NL_2024_TRANSFER` |
| Intra-community supply to a business in another EU country (reverse charge) | `EU_Directive_2006/112/EC_Article_40` |
| Consumer in another EU country (OSS) | the country's own code, for example `DE_2025_HIGH` |

Which codes a company may use depends on its tax obligations: `nl_vat` allows the Dutch and EU transfer codes, `nl_oss` the EU country codes. Add the obligation when you create the company (`taxObligations`) or the `onboarding` component asks for it.

- **ICP.** Supplies with the EU transfer code appear in the ICP return. Mount `icp-return` for the quarter.
- **OSS.** Sales to consumers with a country code appear in the OSS return. Mount `oss-return`.
- Both returns are filed with the company's consent for `nl_icp` and `nl_oss` ([Filing consent](/concepts/filing-consent)). The components show the period and status; see their pages for what is available per environment.

## Multiple currencies

Set `currency` per invoice. Amounts are minor units of that currency (`priceMinor: 12000` is 120.00 EUR or 120.00 USD; for a currency without decimals it is the whole number). The books stay in the company's currency, so FinBaze converts with its own exchange rates. Use `expectedTotalMinor` on upserts to fail with `TOTAL_MISMATCH` if your prices and tax codes do not add up to what you expect.

## Try it in the sandbox

`seedTestCompany(input: { template: nl_bv_logistics_oss })` gives a Dutch B.V. with EU customers and VAT, ICP and OSS obligations. Attach a [test clock](/concepts/test-clocks) to run the quarter, then open `icp-return` and `oss-return`. The nightly sandbox benchmark runs the same company through 365 days.

## Pitfalls

- A lane without a tax code: the invoice step is rejected and the whole run is rolled back (`flow_run.failed`).
- Cancelling a shipment that has no invoice: the `reverse` step fails with `NOTHING_TO_REVERSE`. Guard it with `when`.
- Changing a finalised invoice: correct it with a credit note (`creditOf`), not an edit.


---

<!-- /guides/ecommerce -->
# E-commerce

Orders become invoices, EU sales fall under OSS, refunds become credit notes, payouts reconcile.

A shop platform sends the merchant's orders to FinBaze as sales invoices, and payouts from the payment provider as bank transactions. FinBaze does the VAT, including OSS for sales to consumers elsewhere in the EU.

## 1. Orders to invoices

One order is one invoice, keyed by your order id. Sending it again changes nothing, and `unchanged` in the answer tells you so.

```graphql
mutation Order($company: CompanyRef!) {
  upsertSalesInvoice(input: {
    company: $company
    externalId: "order-10442"
    metadata: { channel: "web", orderNumber: "10442" }
    salesInvoice: {
      relation: { externalId: "cust-8812" }
      currency: EUR
      date: "2026-03-05"
      reference: "Order 10442"
      finalise: true
      expectedTotalMinor: 4840
      lines: [
        { name: "Linen shirt", quantity: 2, priceMinor: 1900, taxCode: "DE_2025_HIGH" }
        { name: "Shipping", priceMinor: 420, taxCode: "DE_2025_HIGH" }
      ]
    }
  }) { status id externalId }
}
```

Before the first order, send the customer with `upsertRelation` (a consumer needs no VAT number). Prices are net minor units; tax is derived from the tax code, never taken from the line. `finalise: true` numbers and books the invoice; after that only `metadata` can change.

## 2. Which tax code

Choose the tax code from the destination, as your checkout already does:

| Sale | Tax code |
| --- | --- |
| Consumer in the Netherlands | `NL_2012_HIGH` or `NL_2019_LOW` |
| Consumer in another EU country, OSS | that country's code, for example `DE_2025_HIGH`, `BE_2025_HIGH` |
| Business in another EU country with a valid VAT number | `EU_Directive_2006/112/EC_Article_40` (appears in ICP) |

The company needs the matching tax obligation: `nl_vat` for the Dutch and EU transfer codes, `nl_oss` for the EU country codes. Use only codes the company's obligations allow. Mount `oss-return` to show the quarter's OSS return and let the merchant file it. Filing needs the merchant's consent for `nl_oss` ([Filing consent](/concepts/filing-consent)).

## 3. Refunds are credit notes

A finalised invoice cannot be edited. Refund by sending an invoice that credits it, with no lines:

```graphql
mutation Refund($company: CompanyRef!) {
  upsertSalesInvoice(input: {
    company: $company
    externalId: "refund-10442-1"
    salesInvoice: { relation: { externalId: "cust-8812" }, currency: EUR, date: "2026-03-09", creditOf: { externalId: "order-10442" }, finalise: true }
  }) { status id }
}
```

## 4. Payouts

The payment provider pays out a lump sum per day. Register a `payout_feed` data source, create the PSP account (`upsertFeedBankAccount` with `type: psp`) and push each payout with `ingestPayoutTransactions`, with the reference the bank statement will show:

```graphql
mutation Payout($company: CompanyRef!) {
  ingestPayoutTransactions(source: "shop-payouts", company: $company, account: "psp-main", payouts: [
    { externalId: "po_1NbxYZ", payoutDate: "2026-03-05", arrivalDate: "2026-03-07", amountMinor: 48700, currency: EUR,
      feesMinor: 300, reference: "SHOPPAY po_1NbxYZ", destination: { iban: "NL91ABNA0417164300" } }
  ]) { line status error { code } }
}
```

FinBaze pairs the payout with the credit on the merchant's bank account when it arrives (by amount, arrival day, reference and IBAN) and books both on the suspense ledger, so the books reconcile with the bank. `payoutTransferMatches` shows the pairs. The mechanics are in [Data sources](/guides/data-sources).

## 5. Events to listen for

`sales_invoice.created`, `bank_transaction.booked`, `bank_transaction.needs_review` and `company.requirements.updated` cover most integrations. See the [webhook catalogue](/reference/webhook-events) for the payloads and [Events and webhooks](/concepts/events-and-webhooks) for retries and signatures.

## Many orders at once

For a backfill use a bulk job: `POST /v2/platform/bulk-jobs?object=sales_invoices` with an `Idempotency-Key` header and an NDJSON body. Every line is applied on its own; read results with `platformBulkJob(id)`. See [Sending data](/concepts/sending-data#many-objects-bulk-jobs).

## Try it in the sandbox

Seed `nl_eenmanszaak_services` or `nl_bv_logistics_oss` (the latter has the OSS obligation), push a day of orders, then advance a [test clock](/concepts/test-clocks) past the quarter end and open `oss-return`.

## Pitfalls

- Using a code for a country the company is not registered to sell to under OSS.
- Expecting to edit a finalised invoice. Credit it.
- Sending one invoice per cart line. One order is one invoice.


---

<!-- /guides/scheduling -->
# Scheduling and hours

Send worked hours from your scheduling product to payroll: employees, employments, hours with breaks, approval.

A scheduling product knows who worked when. FinBaze payroll turns approved hours into pay. You push **employees**, their **employments** (the contract), and **worked hours**; FinBaze keeps the books and the payroll. Plnnrr, a shift planner, is the worked example: its shifts become worked-hours entries one for one.

> **What you need**
>
> The `payroll` feature in your allowance and the `payroll:write` scope on your key. Hidden modules still accept data; a module that is off answers `FEATURE_DISABLED`.

## 1. Employees and employments

```graphql
mutation Employee($company: CompanyRef!) {
  upsertEmployee(input: {
    company: $company
    externalId: "plnnrr-emp-31"
    employee: { firstName: "Sam", lastName: "Jansen", email: "sam@example.com", employeeNumber: "31" }
  }) { status id }
}
```

```graphql
mutation Employment($company: CompanyRef!) {
  upsertEmployment(input: {
    company: $company
    externalId: "plnnrr-emp-31-c1"
    employment: {
      employee: { externalId: "plnnrr-emp-31" }
      startDate: "2026-01-01"
      contractType: indefinite
      callType: min_max
      hoursPerWeek: 24
    }
  }) { status id }
}
```

The employment is what hours attach to; hours cannot move to another contract. Wage, tax numbers and the pay run setup stay with the company in FinBaze; your product does not send them.

## 2. A hours feed

Register a data source of type `hours_feed` and attach it:

```graphql
mutation {
  registerDataSource(input: { key: "plnnrr-hours", type: hours_feed, name: "Plnnrr hours", cadence: hourly, autoAttach: true }) { id key }
}
```

## 3. Push the hours

```graphql
mutation Hours($company: CompanyRef!) {
  ingestWorkedHours(source: "plnnrr-hours", company: $company, entries: [
    { externalId: "shift-9001", employment: { externalId: "plnnrr-emp-31-c1" }, workDate: "2026-03-02", startAt: "2026-03-02T08:00:00Z", endAt: "2026-03-02T16:30:00Z", breakMinutes: 30, status: "draft" }
  ]) { line status externalId error { code message path } }
}
```

- One entry per shift. `externalId` is yours, so sending a shift again updates it.
- `endAt` must be after `startAt`, and the break must be shorter than the shift.
- `hourType` is an opaque id from the collective agreement's hour-type catalogue (night, weekend, overtime). Send it only if the company's agreement uses types.
- `status: draft` can be corrected; `status: approved` is **final** because payroll may already have used it. Correct hours before you approve them. An approved entry cannot be changed or deleted (`OBJECT_FINALISED`).
- Results are per entry (`line`, `status`, `error`), so one bad shift does not block the rest.

Send corrections for draft hours by calling `ingestWorkedHours` again with the same `externalId`.

## 4. After the hours

The company runs and approves its pay runs in FinBaze. Wage tax filings follow the usual consent ([Filing consent](/concepts/filing-consent), tax `nl_wage_tax`), and payment of wages can be handed to your platform with a `payments` provider and `kinds: ["wages"]` ([Delegated actions](/concepts/delegated-actions)).

## Try it in the sandbox

`seedTestCompany(input: { template: nl_bv_payroll })` gives a Dutch B.V. with the wage tax obligation. The template does not create employees or pay runs yet, so create them with the calls above, push a week of hours, and read the results.

## Pitfalls

- Approving hours too early.
- Sending a timestamp without a zone: use ISO 8601 with `Z` or an offset.
- Putting personal identifiers such as a BSN in `metadata`. Metadata is plain strings and visible to the company's users.


---

<!-- /guides/data-sources -->
# Data sources

Register a feed, attach companies, deliver transactions, balances and statement files, and watch feed health.

A **data source** is one of your feeds into FinBaze: a bank feed, a card or payout feed, a sales or purchase feed, an hours feed or custom records. You register it once, attach it to companies, and deliver. FinBaze tells you whether each account is healthy.

## Register and attach

```graphql
mutation {
  registerDataSource(input: {
    key: "acme-bank"
    type: bank_feed
    name: "Acme Bank"
    cadence: daily
    expectedBy: "07:00"
    gapThresholdMinutes: 1500
    historyMonths: 12
    balanceAssertions: true
  }) { id key status cadence gapThresholdMinutes }
}
```

`cadence` is `realtime`, `hourly`, `daily` or `business_daily`; with `daily` and `business_daily`, `expectedBy` (`HH:MM`, Amsterdam time) is when the day's data should have arrived. Together with `gapThresholdMinutes` it decides when an account counts as delayed or in a gap.

```graphql
mutation Attach($company: CompanyRef!) {
  attachDataSource(key: "acme-bank", company: $company, backfillFrom: "2025-04-01") { id status backfillStatus }
}
```

Use `autoAttach: true` on the source to attach every new company automatically. `pauseDataSourceAttachment` and `detachDataSource` stop deliveries for one company. Attaching with `backfillFrom` tells FinBaze how far back you will deliver history.

## Deliver

| Call | What it does |
| --- | --- |
| `upsertFeedBankAccount` | A bank, card or PSP account. An existing Lunch Flow account with the same IBAN is taken over with its history. |
| `ingestBankTransactions` | Up to 500 booked transactions per call. Result per line. |
| `reportBankBalances` | Daily balances (`closing_booked`, `opening_booked`, `closing_available`, `interim_booked`); FinBaze checks them against the transactions. |
| `reportFeedWatermark` | "Everything up to `completeThrough` is delivered", also the heartbeat of a quiet account. |
| `ingestPayoutTransactions` | Payouts of a `payout_feed` onto a PSP account; each is paired with its bank credit (see [E-commerce](/guides/ecommerce#4-payouts)). |
| `ingestSalesInvoices`, `ingestPurchaseInvoices` | Invoices of a `sales_feed` or `purchase_feed`, same fields as `upsertSalesInvoice` / `upsertPurchaseInvoice`. |
| `ingestWorkedHours` | Hours of an `hours_feed`. |

```graphql
mutation Balances($company: CompanyRef!) {
  reportBankBalances(source: "acme-bank", company: $company, account: "acc-77", balances: [
    { date: "2026-03-02", type: closing_booked, amountMinor: 1254300, currency: EUR }
  ]) { date status differenceMinor }
}
```

- The result of `ingestBankTransactions` is one entry per line (`line`, `status`, `error`). A bad line fails alone.
- Errors worth handling: `PENDING_NOT_BOOKED` (you sent `pending`), `IMMUTABLE_TRANSACTION` (a booked line changed: send a reversal), `UNKNOWN_ACCOUNT`, `NOT_ATTACHED` (the company is not attached to the source), `SOURCE_INACTIVE`, `CURRENCY_MISMATCH`.
- The first closing balance after attaching sets the opening balance. Later balances are assertions.
- Delivered bank rows, feed invoices and feed hours are read-only for the company's users (`PARTNER_SOURCED_READ_ONLY`); they can still process, split and book them.

## Statement files

If your core system exports files, not an API, upload them:

```bash
curl -X POST "https://sandbox.api.platform.finbaze.com/v2/platform/data-sources/acme-bank/files?format=camt053" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/xml" \
  --data-binary @statement.xml
```

`format` is `camt053`, `camt052` or `mt940`. The answer is 202 with the file id; parsing is in the background. One file can hold accounts of many companies: FinBaze routes by account IBAN to the attached companies, and lists accounts it could not route in `unroutedAccounts`. The same booking arriving as camt.052, camt.053 and MT940 is stored once. Follow a file with `dataSourceFiles` and the events `data_source_file.processed` and `data_source_file.failed`.

### Over SFTP

Register the source with `delivery: { sftp: true }` and ask FinBaze for an SFTP account for your platform. Put each file in the folder of its source, `<source key>/` in your SFTP home. FinBaze picks a file up within a minute once it has stopped changing (upload under a `.part` name and rename it when done), imports it like an upload (`receivedVia: sftp`) and moves it to `processed/<date>/`. A file it cannot take moves to `failed/`, with the reason in `<file>.error.txt`.

## Feed health

```graphql
query { feedHealth(status: [delayed, gap, balance_mismatch], first: 50) { nodes { externalId health statusSince lastDeliveryAt completeThrough } nextCursor } }
```

| Health | Meaning |
| --- | --- |
| `healthy` | A delivery or heartbeat arrived when expected and balances match. |
| `delayed` | Nothing arrived when expected, but the silence is shorter than `gapThresholdMinutes`: past `expectedBy` for daily feeds, more than 7.5 minutes (real-time) or 90 minutes (hourly) for the others. |
| `gap` | Silence longer than `gapThresholdMinutes`, or a statement number is missing. Send the missing days, or a watermark if there was nothing to send. |
| `balance_mismatch` | Transactions and the reported balance disagree; nothing in the books changed. |
| `stopped` | The attachment or source is paused or retired. |

A delivery or a watermark counts as a sign of life.

Events: `feed.delayed`, `feed.gap_detected`, `feed.balance_mismatch`, `feed.recovered`. Real-time and hourly feeds should send `reportFeedWatermark` at least once per gap threshold, otherwise a quiet account looks like a gap.

## Try it in the sandbox

A seeded company already has a simulated bank account with a feed scenario (`steady`, `retail_cards`, and so on) that advances with a [test clock](/concepts/test-clocks). To exercise your own feed, create a second company without a clock, register a source and push to it.

## Pitfalls

- Sending the same data under a new `externalId`: it becomes a second transaction.
- Not sending balances: the books cannot be checked, and `balance_mismatch` never fires.
- Forgetting to attach: deliveries answer `NOT_ATTACHED`.


---

<!-- /guides/messages-and-routing -->
# Messages and routing

Receive what FinBaze would email your users, deliver it in your channels, acknowledge it and change who sends what.

FinBaze never emails your users on its own for a company on your platform. It creates a **message**, routes it by who should deliver it, and tells you. This guide is the working path; [Messages](/concepts/messages) has the full rules and the [message catalogue](/reference/message-catalogue) lists every type.

## 1. Subscribe

Create a webhook endpoint with `message.created` and `message.unacknowledged` (see [Events and webhooks](/concepts/events-and-webhooks)):

```graphql
mutation {
  createPlatformWebhookEndpoint(input: {
    url: "https://example.com/finbaze"
    eventTypes: ["message.created", "message.unacknowledged"]
  }) { endpoint { id } signingSecret }
}
```

`signingSecret` is shown once. Verify every delivery with it (receivers in Node, Python and PHP are in the [sample apps](/guides/sample-apps)).

## 2. Deliver

`data.object` of `message.created` is the message. It already has the text for each channel (`content.push`, `content.in_app`, `content.email`, `content.sms`) and a `deep_link` your app routes to. Deliver in your own channel, then acknowledge:

```graphql
mutation Ack($id: ID!) {
  acknowledgeMessage(input: { id: $id, channel: "push", outcome: "delivered" }) { id status acknowledgedAt }
}
```

Dedupe on `dedupe_key`; do not deliver after `expires_at`. Acknowledge at least the messages with `ack_required`: critical messages and those that serve as evidence (invoices and reminders you deliver). Use `acknowledgeMessages` for up to 100. `outcome: "failed"` tells FinBaze you could not deliver; the message stays unacknowledged and you get `message.unacknowledged` after `ack_deadline`.

## 3. Choose who sends what

```graphql
mutation {
  setPlatformMessageRouting(input: { scope: "category", category: "tax_deadline", routing: "partner_delivers" }) { id routing }
}
```

`routing` is `partner_delivers` (the default for notifications), `finbaze_sends`, `both` or `suppress`. A rule applies to everything (`scope: "all"`), one category or one type, for the platform or for one company (`profileId`). The most specific rule wins. `finbaze_sends` needs a verified sender domain for your platform; without one the message falls back to `partner_delivers`. `platformMessageRouting` lists your rules, and `clearPlatformMessageRouting` removes one.

Lifecycle, billing and FinBaze account-security messages are never delivered for platform companies and cannot be changed (`ROUTING_NOT_CHANGEABLE`).

## 4. Settings

```graphql
mutation {
  updatePlatformMessageSettings(input: { quietHoursStart: "22:00", quietHoursEnd: "07:30", quietHoursTimezone: "Europe/Amsterdam", digestHourLocal: 8, brandName: "Acme Books" }) {
    digestHourLocal quietHoursStart brandName
  }
}
```

Critical messages ignore quiet hours and limits. More than 20 messages per person per hour, or 3 of one type, fold into an hourly digest.

## 5. Read the log

```graphql
query { platformMessages(filter: { unacknowledgedOnly: true, limit: 50 }) { id type priority status routing routingReason ackDeadline } }
```

`routingReason` tells you why: `catalogue_default`, `platform_category`, `company_override`, `hard_rule`, `feature_hidden`. `resendPlatformMessage` queues a message again.

## Push notifications

FinBaze sends push only to its own mobile app, for companies that are not on a platform. For a platform company you send the push yourself from `message.created`. On mobile, the push can carry an intent that opens the right component; see [Mobile](/guides/mobile).

## Pitfalls

- Treating a webhook delivery as unique: deliveries are at least once.
- Forgetting to acknowledge critical messages: after the deadline FinBaze raises `message.unacknowledged`, and with `criticalEmailFallback` on it may email the user itself.
- Routing to `finbaze_sends` without a verified sender domain.


---

<!-- /guides/documents -->
# Documents

Put your branding on invoices, quotes, reminders and payslips: presets, templates, or render the PDF yourself.

FinBaze keeps the official copy of every invoice, quote, reminder, payslip and year document. You choose how it looks, per document type, at one of three levels. [Documents and rendering](/concepts/documents-and-rendering) explains each; this guide is the order to do things in.

## Pick a level

| Level | When to choose it | Effort |
| --- | --- | --- |
| `finbaze_layout` | Your colours, fonts and logo are enough. | Small |
| `template` | You want your own HTML for the page, rendered by FinBaze. | Medium |
| `partner` | You already render PDFs and want one look everywhere. | Highest |

```graphql
mutation { setPlatformDocumentRenderSetting(documentType: invoice, mode: finbaze_layout) { documentType mode timeoutSeconds } }
```

Whatever the level, required content (VAT number, address, invoice number, reverse-charge text) is checked. A rule the tax adviser has not confirmed gives a warning; others refuse activation, or reject your PDF, and FinBaze then falls back to its own layout.

## 1. A preset

```graphql
mutation Preset($layout: JSONObject!) {
  upsertPlatformDocumentLayout(input: { documentType: invoice, name: "Acme classic", layout: $layout, companyEditable: unlocked_blocks }) {
    id version status warnings { ruleId field message severity }
  }
}
```

Check a layout before you save it with `validateDocumentLayout(documentType: invoice, layout: …)`, then `activatePlatformDocumentLayout(id: …, makeDefault: true)`. `platformDocumentLayoutPreview(id: …)` returns the HTML. A company can choose among your presets (`chooseDocumentLayout`) or edit the blocks you unlock.

## 2. A template

```graphql
mutation Template($source: String!, $css: String) {
  upsertDocumentTemplate(input: { documentType: invoice, name: "Acme", source: $source, css: $css }) { id status version }
}
```

Then `validateDocumentTemplate(id: …)` renders twelve fixtures and checks the required content, and `activateDocumentTemplate(id: …, makeDefault: true)` works only after a pass. Templates are logic-less: placeholders, loops and conditions over the document data; scripts, iframes, remote images, `@import` and SVG with script are refused. `documentTemplatePreview(id: …, fixture: "default")` shows a render.

## 3. Render it yourself

Set the mode to `partner` and subscribe to `document.render_requested`:

```graphql
mutation { setPlatformDocumentRenderSetting(documentType: invoice, mode: partner, timeoutSeconds: 60) { mode timeoutSeconds } }
```

The event carries the job, the data model (never a BSN), a deadline and signed links to attachments such as the invoice UBL. Render the PDF and answer before the deadline:

```graphql
mutation Attach($job: ID!, $pdf: String!) {
  attachRenderedDocument(jobId: $job, pdfBase64: $pdf) { id status }
}
```

For larger files upload first (up to 10 MB, valid for an hour) and pass `uploadId` instead of `pdfBase64`. FinBaze scans the PDF (no scripts, no embedded files) and checks its text against the document's facts. Emails and payment pages wait for the job; after a rejection, a timeout or no answer FinBaze renders its own layout. Events: `document.render_requested`, `document.render_rejected`, `document.render_failed`, `document.official_copy_created`. `documentRenderJob(id: …)` shows a job.

## 4. Your own domain

```graphql
mutation { addPlatformCustomDomain(hostname: "pay.acme.nl") { id status } }
```

Create the DNS records the answer lists, then `checkPlatformCustomDomain(id: …)`. FinBaze issues the certificate; `custom_domain.status_changed` follows the status. A company is served only on its own platform's domains.

## Promote from the sandbox

Presets and templates travel with the `documents` policy when you promote your configuration from the sandbox (`previewPlatformPromotion`, `applyPlatformPromotion`).

## Try it in the sandbox

Seed a company, finalise an invoice with `upsertSalesInvoice(… finalise: true)` and fetch it with `companyDocument(company, kind: sales_invoice_pdf, …)`; the link works for 15 minutes without a token.

## Pitfalls

- Activating without validating: activation fails if the report has failures.
- Answering a `partner` render after the deadline: the job has already fallen back.
- Putting personal data you do not need in a template fixture.


---

<!-- /guides/features-and-limits -->
# Features and limits

Hide parts of FinBaze for your platform or one company, see what is effective, and know what hiding removes.

FinBaze decides what a company can use in two layers. The **allowance** is what FinBaze puts in your contract. **Limits** are yours: you can only narrow what the allowance gives you. There is exactly one limit: **hidden**. There are no upsell states and no segments. See [Feature allowance and limits](/concepts/feature-allowance-and-limits).

## See what you have

```graphql
query { platformFeatureAllowance { version features { key } } }
```

```graphql
query Effective($company: ID!) { platformCompanyFeatures(profileId: $company) { key enabled source blockedBy } }
```

`source` and `blockedBy` tell you why a key is off for a company: not in the allowance, hidden by you, or blocked by a key it requires.

## Hide something

```graphql
mutation { setPlatformFeatureLimit(input: { key: "banking", hidden: true }) { key level hidden } }
```

Add `profileId` to hide it for one company only. `clearPlatformFeatureLimit(key: "banking")` shows it again, and `platformFeatureLimits` lists what you set. Changes reach every API server within about 30 seconds.

## What hiding removes

A hidden module is gone, not locked:

- Its operations fail with `FEATURE_DISABLED`; its data is absent from nested results.
- Components that need it cannot be added to a session (`createEmbedSession` fails with `FEATURE_DISABLED`), and mounted ones lose its parts.
- Events of the module are not published for the company.
- Data you send to a hidden module is still accepted (you may show the module later). A module that is **off** (not in the allowance) answers `FEATURE_DISABLED` instead.
- Accounting firms working on the company see the same: a hidden module is hidden for them too.

## Feature keys you may limit

Keys such as `banking`, `sales_invoices`, `purchase_invoices`, `tax_filings`, `submit_tax_filings`, `one_stop_shop_filing`, `icp_filing`, `payroll`, `forecasts`, `budgets`, `annual_accounts`, `automations`, `ai_assistant`, `custom_records` and `firm_access` are limitable. A key that is `beta` is available only where FinBaze has switched it on for you. Your allowance shows exactly what applies to you.

## Component features are separate

A component's own features (for example `submit` on `vat-return`) are chosen per session in `createEmbedSession` and never override a hidden module:

```graphql
mutation {
  createEmbedSession(input: { companyId: "…", user: { externalUserId: "user-42" }, components: { vatReturn: { enabled: true, features: { submit: false } } } }) { clientSecret }
}
```

## Try it in the sandbox

Hide `banking` for one seeded company, call `platformCompanyFeatures` and watch `transactions` refuse to join a new session. Show it again and retry within a minute.

## Pitfalls

- Expecting hidden to mean "visible but locked": there is no locked state.
- Hiding `firm_access`: companies with a connected firm get a notice period before it ends; see [Firms](/guides/firms).


---

<!-- /guides/firms -->
# Accounting firms

Let a company on your platform connect its accountant: invite, approve, what the firm can do, and how to end it.

A company on your platform can connect one accounting firm that uses FinBaze. The firm works the company in its normal FinBaze dashboard, inside the features effective for that company. There are no firm services, no reselling and no marketplace, and **no firm billing**: you keep paying for the company, the firm pays nothing for it. [Working with accountants](/concepts/working-with-accountants) has the full rules.

## 1. Show the connect component

```graphql
mutation {
  createEmbedSession(input: { companyId: "…", user: { externalUserId: "user-42" }, components: { accountantConnect: { enabled: true } } }) { clientSecret }
}
```

```tsx
<FinBazeAccountantConnect onFirmConnected={({ firmId }) => refresh()} onFirmDisconnected={({ firmId }) => refresh()} />
```

The company admin does the rest: find the firm by KvK number or connect code, choose the taxes the firm may file, confirm the statement. The component features are `invite`, `approve` and `end`. Consent needs an `embed` or `headless` token of a company **admin**; your server token cannot consent for a company (`FORBIDDEN_TOKEN_TYPE`).

## 2. Know when a firm asks

A firm can also ask for access using the company's KvK number. You hear about it as `firm.access_requested` (webhook and message). The company approves or declines it in `accountant-connect`, shown through the `notification-banner`.

## 3. Read the state

```graphql
query { companyFirmEngagements(companyId: "…", includeEnded: false) { id status origin taxes filingAuthority expiresAt endsAt firm { id name hasBecon } } }
```

A server key needs the scope `platform_firms:read`. Events: `firm.connection_requested`, `firm.connected`, `firm.connection_declined`, `firm.connection_expired`, `firm.disconnect_scheduled`, `firm.disconnected`, `firm.authority_changed`.

## 4. What the firm files

Nothing, unless the company hands taxes to it. For those taxes the firm files with its BECON number and FinBaze stops filing them. Other taxes stay with FinBaze under the company's own [consent](/concepts/filing-consent). Requests only an intermediary may make, such as the corporate income tax extension, need a connected firm with a BECON number; for a company without one the request is refused with `FILER_MUST_BE_INTERMEDIARY`.

## 5. `firm_access` and ending a connection

Accountant connections are the feature key `firm_access`. Hide it ([Features and limits](/guides/features-and-limits)) and no new connections or requests are possible; companies with an active firm get a notice (30 days by default) and `firm.disconnect_scheduled`. Show it again before then to cancel the notice.

You can end an engagement yourself:

```graphql
mutation { endFirmEngagement(input: { engagementId: "…", reason: "platform_request" }) { id status endedAt endedBySide endReason } }
```

A platform may use the reasons `firm_access_hidden`, `company_closed`, `company_transferred` and `platform_request`; the last is logged and both sides are told. The scope is `platform_firms:write`.

Ending is one transaction: the firm loses access on the next request, its BECON is no longer used for the company, its HMRC client authorisations for the company are cancelled, its open document requests are closed. The company's drafts and books stay, and FinBaze files the taxes the firm used to file once the company's consent exists.

## Try it in the sandbox

Create two companies, connect a test firm from the FinBaze sandbox dashboard to one, and compare `companyFirmEngagements`. End it with `endFirmEngagement` and watch `firm.disconnected` arrive at your receiver.

## Pitfalls

- Trying to connect a platform company through a firm's invite link, onboarding or client creation: refused with `PLATFORM_COMPANY_USE_ENGAGEMENT`.
- Planning on billing the firm: there is no firm billing.
- Expecting your server key to give consent: only the company's admin can.


---

<!-- /guides/lifecycle-and-migration -->
# Lifecycle and migration

Suspend, close, archive, transfer and export a company, and bring books in from another system.

Companies on your platform move through `active`, `suspended`, `closed` and `archived`, and can move to another platform or to direct FinBaze. Books, filings, documents and Digipoort or HMRC history are never deleted by any of this. [Company lifecycle](/concepts/company-lifecycle) has the state rules; this guide is the runbook.

## Customer stops paying: suspend

```graphql
mutation { suspendPlatformCompany(companyId: "…", reason: "non-payment", displayMessage: "Your account is on hold.") { id lifecycle { state } } }
```

The company becomes read-only (`COMPANY_SUSPENDED` on changes); cron work such as reminders and bank sync skips it. Reactivate with `reactivatePlatformCompany`. A company FinBaze suspended cannot be reactivated by you (`SUSPENDED_BY_FINBAZE`).

## Customer stops trading: close, then archive

```graphql
query { companyClosingChecklist(companyId: "…", effectiveDate: "2026-10-31") { key label blocking done filingId } }
```

Close with `closePlatformCompany(companyId: "…", effectiveDate: "2026-10-31")`. Final returns can still be filed and exported. `reopenPlatformCompany` works within the reopen window (90 days by default). When every blocking checklist item is done, `archivePlatformCompany` detaches the company from your platform. Only exports work after that, and the books are kept until `retentionUntil` (7 years in the Netherlands by default). An open blocking item gives `ARCHIVE_BLOCKED`.

Events: `company.suspended`, `company.reactivated`, `company.closed`, `company.reopened`, `company.archived`.

## Customer moves platform or to FinBaze

The company's admin consents in the `company-transfer` element (it shows a versioned statement). Mount it with `components: { companyTransfer: { enabled: true } }`.

- **To another platform:** the element shows a one-time code, once. The receiving platform's backend calls `acceptCompanyTransfer(code: "…", externalId: "their-id")`.
- **To direct FinBaze:** the admin enters an email and FinBaze emails a claim link; a FinBaze account claims the company and picks a plan.

On completion your platform loses access (users, limits, data sources, sessions) and you receive `company.transferred_out`; the receiving side gets `company.transferred_in`. You never see the new owner's id. `cancelCompanyTransfer(transferId: …)` cancels a pending one. Errors: `TRANSFER_CODE_INVALID`, `TRANSFER_CODE_EXPIRED`, `TRANSFER_ALREADY_PENDING`, `TRANSFER_STATEMENT_OUTDATED`.

## Getting the books out

Before a company leaves, give it its data.

```graphql
mutation { requestXafExport(company: { externalId: "biz-1001" }, financialYear: 2025) { id status } }
```

Poll `platformExportRun(id: …)`; when ready its `document` carries a `downloadUrl` (valid 15 minutes), and `export.ready` is sent. The audit file is Auditfile Financieel 4.0 (validated against the official XSD, VAT per line); pass `version: "3.2"` for a receiving system that still needs 3.2. Reports (`platformReport`), documents (`companyDocument`) and scheduled exports to your own bucket are in [Getting data out](/concepts/getting-data-out).

> **XAF in**
>
> There is no XAF import. To bring books in from another system, load the opening position as a journal entry and history as invoices and relations, with `upsertJournalEntry`, `upsertSalesInvoice`, `upsertPurchaseInvoice` and `upsertRelation`, or as a bulk job (`journal_entries`, `sales_invoices`, `purchase_invoices`, `relations`). Everything keeps your ids, so a failed load can run again. See [Sending data](/concepts/sending-data).

## Ending a user

`deprovisionPlatformUser(userId: …)` revokes every token and session of the user at once and removes the user from all companies. A later `upsertPlatformUser` with the same `externalUserId` brings the user back with a new identity; old tokens stay dead.

## Audit

```graphql
query { platformAuditLogs(first: 50) { edges { id at action actorKind requestId } nextCursor } }
```

Needs the `audit:read` scope and an admin role, and shows only your own companies. `requestAuditLogExport` starts an NDJSON export.

## Try it in the sandbox

Seed a company, `suspendPlatformCompany`, try a write and see `COMPANY_SUSPENDED`, reactivate, then close it with the checklist. The sandbox reset removes companies not marked `preserve` every night ([Sandbox reset](/concepts/sandbox-reset)).

## Pitfalls

- Archiving too early: blocking checklist items are the final returns.
- Telling the company its books are deleted: they are kept until the retention date.
- Handing a transfer code over by email: it works once and shows once; deliver it inside your product.


---

<!-- /guides/mobile -->
# Mobile

FinBaze in iOS, Android and React Native apps: the WebView host, camera, step-up with your own biometrics, and opening a component from a push.

> **Beta, planned for Wave 6.2**
>
> The mobile SDKs are `0.x` betas that ship with Wave 6.2. This page describes the design they follow. The packages (`@finbaze/embed-react-native`, `finbaze-ios`, `finbaze-android`) and the API pieces named below (`registerPlatformMobileApp`, `mobileAppId` on `createEmbedSession`, `resolveEmbedIntent`) are **not in the schema or registry this version of the docs is generated from**. Code blocks marked `text` are the planned shapes, not calls you can run today. The [API changelog](/changelog) announces each when it ships.

## How it works

All three SDKs host the same embed app in a WebView, as a top-level page at `https://embed.finbaze.com/m/<tag>` (sandbox: `https://sandbox.embed.finbaze.com`), not in an iframe. Native code adds what a WebView cannot do: camera and files, biometric step-up through your app, native sheets, and deep-link hand-off. The embed token stays in WebView memory and the SDK never stores it.

```text
Your app                       SDK                              WebView  embed.finbaze.com/m/<tag>
fetchClientSecret()  <------   FinBaze(publishableKey, appId)   loads /m/<tag>?pk=...&app=...
onStepUpRequired()   <------   stepup.required                  component needs approval
camera / scanner     <------   capture.request                  file bytes go back via the bridge
handle(notification) ------>   open the component's sheet
```

## Register the app

In the portal you register each app (`ios` or `android`, bundle id or package name, URL scheme). A session created for a mobile app can only be exchanged through the `/m/*` shell with that app id; a session without one only inside an allowed web origin. Use the publishable key of the same platform on the device.

## Camera and files

The component asks for a photo or file; the SDK opens the native camera or document scanner (VisionKit, CameraX or ML Kit, or the libraries already in your React Native app) and sends the bytes back. Files over 10 MB are rejected natively. If you need your own scanner, the SDKs expose a capture callback, the same idea as `onCameraCapture` in the [browser SDK](/sdks/embed-js).

## Step-up with your own biometrics

FinBaze does not implement biometrics. Banks own strong customer authentication. When a component needs approval (filing a VAT return, approving a payment request) the API answers `STEP_UP_REQUIRED` with a challenge and the SDK calls your `onStepUpRequired`. You run Face ID, BiometricPrompt or your SCA server, and complete the challenge from your backend with your own assertion, the same server-side contract as [Delegated actions: step-up](/concepts/delegated-actions#step-up). Platforms that are not banks can opt into a device-local confirmation in the portal; it is a weaker signal and is labelled as such in the audit log.

## Open a component from a push

FinBaze holds no APNs or FCM credentials for partners. A message routed `partner_delivers` reaches your webhook ([Messages and routing](/guides/messages-and-routing)); for mobile it carries an action that names the component and a signed, opaque `intent` valid for 7 days. You send your own push with the intent in the payload. On tap you pass the payload to the SDK, which asks your backend for a client secret for that component and opens it. Your backend can verify an intent with `resolveEmbedIntent` before minting the session.

```text
// Planned shape, iOS
let finbaze = FinBaze(publishableKey: "fb_pk_test_...", mobileAppId: "fb_app_...") { request in
  try await api.finbazeClientSecret(component: request.component, company: request.company)
}
finbaze.onStepUpRequired = { challenge in try await bank.performSCA(challenge) }
if finbaze.canHandle(userInfo) { finbaze.handle(userInfo, presentingFrom: rootVC) }
```

## WebView security

The SDKs only load the FinBaze embed origins in the WebView and open everything else in the system browser. They disable file access and mixed content, allow the bridge only from the FinBaze origin, turn WebView debugging off in release builds, offer screen protection for payroll components, and bundle no analytics.

## What works today

The same components run in the browser through [`@finbaze/embed-js`](/sdks/embed-js), including the camera, payment and step-up callbacks. The [neobank demo](/guides/sample-apps) has a web part you can deploy now; its Expo app ships with the mobile SDKs.

## Pitfalls

- Treating a leaked client secret as harmless: without app attestation it can be exchanged by any app within 15 minutes, once. Mint it only for a signed-in user, and return a new one each time.
- Persisting the embed token: do not; the WebView holds it.


---

<!-- /guides/sample-apps -->
# Sample apps

Six runnable examples with a deploy button, a README and an end-to-end script that runs against the sandbox every night.

Each sample is a public repository under `github.com/FinBaze/`. Each has a deploy configuration, a README and an end-to-end script that sets up the demo company, does what the app does, and checks the result against the sandbox. The scripts run **every night** in CI; a failure opens an issue.

| Repository | Stack | Shows | Deploy |
| --- | --- | --- | --- |
| `neobank-demo` | Next.js | Bank feed push, `booking-chip`, camera receipts, VAT paid from the account (`onPaymentRequested`), step-up mock. See [Banks](/guides/banks). | Vercel button, Docker |
| `pos-demo` | Next.js | Z-report to bookings with a flow template, VAT return, purchase inbox. See [Point of sale](/guides/pos). | Vercel button, Docker |
| `tms-demo` | Next.js, Node | Shipment to invoice with a flow template, carrier invoices, ICP and OSS. See [Logistics](/guides/logistics). | Render blueprint, Docker |
| `headless-demo` | Node, React | A headless session and hooks with your own UI. See [Headless hooks](/sdks/headless). | Render blueprint, Docker |
| `webhook-receivers` | Node, Python, PHP | Signature verification, idempotent handling, replay. See [Webhook events](/reference/webhook-events). | Docker per language, Render |
| `finbaze-embed-examples` | Vanilla, React, Vue, Svelte | Every component with appearance variants. | StackBlitz links |

> **What is not in the repositories yet**
>
> The Expo (mobile) part of the neobank demo, push hand-off and the Kotlin webhook receiver ship with the mobile and server SDKs of Wave 6. The READMEs say so where it matters. The samples install `@finbaze/embed-react` and `@finbaze/embed-js` from npm.

## One click

1. Open `https://developers.finbaze.com/keys/new?sample=<repository>` (for example `?sample=pos-demo`) and sign in. The page sets up your sandbox for that sample with one call, `bootstrapSampleApp`.
2. Click the deploy button in the README and paste the keys it asks for.
3. Add your deployment's URL under **Embedding → Allowed origins** in the portal.
4. Run the sample's setup script once (`npm run setup:sandbox`).

## What `bootstrapSampleApp` does

```graphql
mutation Bootstrap($webhookUrl: String) {
  bootstrapSampleApp(sample: "pos-demo", webhookUrl: $webhookUrl) {
    secretKey
    publishableKey
    webhookSecret
    companyId
  }
}
```

- **Sandbox only.** Anywhere else it answers `SANDBOX_ONLY`. Portal sign-in only: a key cannot call it, so a leaked key cannot mint more keys.
- **What it creates.** A restricted test key (`fb_rk_test_…`) with the scopes the sample needs, the publishable key, a webhook endpoint at `webhookUrl` subscribed to every event (when you give a URL; otherwise `webhookSecret` is `null`), and the sample's demo company ([Demo companies](/concepts/demo-companies)): the hospitality sole trader for `pos-demo`, the logistics B.V. for `tms-demo`, a services sole trader for the others. Seeding is idempotent, so the same company comes back.
- **Shown once.** `secretKey` and `webhookSecret` are not shown again; run it again for new ones. A new bootstrap of the same sample revokes that sample's earlier keys and endpoint, so keys and endpoints do not pile up.
- **Limit.** At most 5 a day per developer (`RATE_LIMITED`).

Samples: `neobank-demo`, `pos-demo`, `tms-demo`, `headless-demo`, `webhook-receivers`, `finbaze-embed-examples`. Any other name is refused with a 400 that lists them.

## Run them against your own sandbox

Every e2e script reads `FINBAZE_SECRET_KEY` and `FINBAZE_COMPANY_ID` (and optionally `FINBAZE_API_URL`). They use a 40-line GraphQL client and no SDK, so you can read each call. Each README shows the file layout and which file shows what.

## Offline

In the FinBaze repository, `node samples/scripts/run-offline.mjs` runs every sample's e2e against a mock sandbox that validates each operation against the real schema. It proves the samples send valid operations; the nightly run against the sandbox proves the behaviour.


---

<!-- /guides/upgrading -->
# Upgrading

What changes in your integration between releases, how versions work, and what to do about each change.

The [changelog](/changelog) lists everything. This page lists what asks something of **your code**, newest first, and how to read versions. The current versions are on [Versions](/reference/versions).

## How versions work today

- **API version.** Every webhook delivery carries `apiVersion` in its body and `X-FinBaze-Api-Version` in its headers. Until a second version exists, every endpoint gets the current one; pinning a version per platform is not available yet. Branch on fields you know, ignore fields you do not.
- **GraphQL.** One schema. A change to it needs an entry in the changelog. Fields and operations are added; read the changelog before you rely on removed or renamed ones.
- **Browser SDKs** (`@finbaze/embed-js`, `@finbaze/embed-react`) are `0.x` and follow semver. The controller loads from FinBaze's origin, so a component is always current; the SDK is the thin part that mounts it. Pin the SDK version in your lockfile and update it deliberately.
- **Server SDK** (`@finbaze/platform-sdk`) is 1.0 and not on npm yet; the plain GraphQL calls on its page do the same work.
- **Mobile SDKs** are planned as `0.x` betas with Wave 6.2; they will follow semver, and the protocol between the SDK and the embed app carries a version so that old SDK versions keep working for at least 12 months. See [Mobile](/guides/mobile).

## What asks something of you

### Filing consent (Wave 5.1)

A platform company's returns are filed only with its admin's authorisation. A submit without it fails with `TAX_AUTHORISATION_REQUIRED`. What to do: mount `tax-authorisation` or `onboarding` where the company's admin sets up filing, and hide your own submit button for companies without consent (read `taxAuthorisationStatus`). See [Filing consent](/concepts/filing-consent).

### Webhook secrets and rotation

When you rotate a secret (`rotatePlatformWebhookSecret`), both secrets sign for the period you choose, so the header carries two `v1` values. What to do: make your verifier accept a list of secrets and any matching `v1` ([receivers in three languages](/guides/sample-apps)), deploy the new secret, then let the old one expire.

### Sandbox resets

Companies that are not marked `preserve` are removed in a nightly reset when you switch it on. What to do: seed fixtures with stable `externalId`s (`seedTestCompany` does) and make your tests idempotent. See [Sandbox reset](/concepts/sandbox-reset).

### Client secrets

A secret is single use and valid for 15 minutes. If you cached one, you will see `EMBED_SECRET_USED`. What to do: return a new secret from every `fetchClientSecret` call.

## Planned: stricter operation checks for embed and headless tokens

Embed and headless tokens already run only allowlisted operations. The check is moving to identify operations by the hash of their normalised document, rolled out in the sandbox first in a mode that only logs, then enforced after the gallery and the sample apps pass for a week. What to do: nothing, as long as you use FinBaze's components and hooks. If you run your own documents with a headless token, they will be refused once the check is enforced: use the server API for those. The changelog announces each step.

## When something does not work after an upgrade

1. Read the [error codes](/reference/errors) for the code you see.
2. Check the changelog entry of the release.
3. Send the `X-Request-Id` of the failing request to support.


---

<!-- /concepts/platforms-and-companies -->
# Platforms and companies

The objects you work with: your platform, its companies, and the hidden users who act on them.

## Platform

A *platform* is you: the product that embeds FinBaze. It owns keys, allowed origins, embed settings and the list of companies. Sandbox and live are separate platforms with separate data.

## Company

A *company* is one of your customers' businesses. It has its own ledger, tax obligations and documents. You create it with `createPlatformCompany` and your own `externalId`:

- The same `externalId` always returns the same company, so the call is safe to retry.
- `company.id` is the profile id used by every other operation.
- A company belongs to exactly one platform. It cannot be seen by FinBaze accounts outside that platform.

## Users

A *platform user* is a person in your product who works on one or more companies. You identify them with your own `externalUserId`. Users are **hidden**: FinBaze never sends them email, never shows a login page and they cannot sign in to FinBaze directly. Their only way in is a token that your backend mints for them.

Access is per company, with a role:

| Role | Can |
| --- | --- |
| `admin` | Everything, including submitting filings and managing access |
| `member` | Day-to-day bookkeeping |
| `viewer` | Read only |

Disable a user (`upsertPlatformUser(disabled: true)`) or remove their access and every embed session of theirs is revoked within seconds.

## Isolation

A user token only sees the companies the user has access to, and only inside your platform. A secret key only sees your platform's companies. Neither can reach another platform's data.


---

<!-- /concepts/identity-and-tokens -->
# Identity and tokens

Keys, server tokens, client secrets and embed tokens: what each is for and how long it lives.

| Credential | Looks like | Lives | Where | Use |
| --- | --- | --- | --- | --- |
| Secret key | `fb_sk_live_…` / `fb_sk_test_…` | until you roll it | your server only | exchange for a server token |
| Restricted key | `fb_rk_…` | until you roll it | your server only | like a secret key, limited to chosen scopes |
| Publishable key | `fb_pk_live_…` / `fb_pk_test_…` | until you roll it | browsers | identifies your platform to the SDK; grants nothing |
| Server token | JWT | short | your server | call the GraphQL API |
| Client secret | `es_…_secret_…` | 15 minutes, **single use** | your server → browser, once | start an embed session |
| Embed token | JWT, `typ: embed` | 1 hour by default | inside FinBaze's iframe only | run the component's operations |
| Headless token | JWT, `typ: headless` | 1 hour by default | your page | run the headless hooks |

## From secret key to server token

`POST /v2/oauth2/token` with `grant_type=client_credentials` and `client_secret=<key>`. A restricted key can ask for a subset of its scopes with `scope`.

## From client secret to embed token

1. Your backend calls `createEmbedSession` and returns `clientSecret` to the page.
2. The SDK's hidden controller iframe (on FinBaze's origin) calls `exchangeEmbedSession`. The exchange consumes the secret atomically: a second use fails with `EMBED_SECRET_USED`.
3. The embed token is held in memory in that iframe and handed to component iframes over a private channel. It never reaches your page, local storage or cookies.
4. Before the token expires the SDK asks `fetchClientSecret` for a **new** secret and repeats. There are no refresh tokens: your backend decides, every time, whether the user may continue.

A chain of refreshes ends after `embed.max_chain_hours` (12 by default); the user then needs a session minted without `previousSessionId`.

## What a token can do

An embed token is pinned to one company, one user and the components in the session. It can only run FinBaze's own operations for those components, and only the features you left on. Everything else is refused (`EMBED_OPERATION_NOT_ALLOWED`). See [embed security model](/concepts/embed-security-model).

## Revoking keys

Revoking or rolling a secret, restricted or publishable key refuses new token exchanges at once. Server and user tokens already minted with that key stop working on the next request: immediately on the API server that handled the revocation and normally within a second on the others. When the internal message between servers is lost, a server's cache still expires after **10 seconds**, so plan for up to 10 s in which an old token may still be accepted. The same applies to suspending your platform, disabling a platform user and removing a user's access to a company.

## Rate limits

Limits count requests per rolling minute and are shared by all API servers. Over a limit the API answers HTTP `429` with code `RATE_LIMITED`; wait for the next minute and retry with backoff.

| What | Counted per | Limit per minute |
| --- | --- | --- |
| GraphQL requests with a server or user token | key the token was minted with | 600 |
| GraphQL requests with an embed or headless token | platform user | 600 |
| `POST /v2/oauth2/token` with a platform key | key (by its lookup id), failed attempts included | 60 |
| `createPlatformUserToken` | key | 300 |
| `createPlatformCompany` | key | 30 (it calls the company registers) |
| `createEmbedSession` | key | 600 |
| `exchangeEmbedSession` | publishable key | 600 |
| `exchangeEmbedSession` | IP address | 30 |

The same limits apply in the sandbox and in live. If you need more for a key, ask FinBaze: a key can carry its own request limit.

## Revoking embed sessions

`revokeEmbedSession(id)` ends one session; `revokeEmbedSessionsForUser(platformUserId)` ends all of a user's. Disabling a user or removing their access does this for you. Revocation takes effect within 15 seconds.


---

<!-- /concepts/feature-allowance-and-limits -->
# Feature allowance and limits

Which parts of FinBaze a company can see, and how you narrow them further.

Two layers decide what a company can use:

1. **Allowance** is set by FinBaze for your platform: the modules your contract includes (banking, purchase documents, tax filings, headless sessions, …).
2. **Limits** are set by you, as a platform default and per company. A limit can only *narrow* the allowance, never widen it.

A module that is not effective is **hidden**: its operations fail with `FEATURE_DISABLED`, its data is absent from nested results and components that require it cannot be added to a session (`FEATURE_DISABLED`). Read `platformCompanyFeatures(profileId)` to see what is effective for a company.

Set a limit with `setPlatformFeatureLimit`. Changes reach all servers within about 30 seconds.

## Component features

Separate from modules, each component has *features* (for example `submit` on `vat-return`). You choose them per session in `createEmbedSession`. They narrow what the component's UI offers and what its token may do; they never override a hidden module.

See each [component](/components) for its requirements and features.


---

<!-- /concepts/sandbox -->
# Sandbox

Test everything with fake companies and test keys; nothing is filed.

|  | Sandbox | Live |
| --- | --- | --- |
| API | `https://sandbox.api.platform.finbaze.com/graphql` | `https://api.platform.finbaze.com/graphql` |
| Embed | `https://sandbox.embed.finbaze.com` | `https://embed.finbaze.com` |
| Keys | `fb_sk_test_…`, `fb_pk_test_…` | `fb_sk_live_…`, `fb_pk_live_…` |
| Data | fake, may be reset | real |

The SDK picks the right embed host from the publishable key. A test key can never reach live data and the other way round.

Filings, bank connections and email in the sandbox use test endpoints or are captured; nothing reaches a real tax authority, bank or customer.

Allowed origins are kept per environment: add `http://localhost:3000` to the sandbox list and your production origin to the live list.

## Limits

The sandbox is for building and testing, not for load.

|  | Sandbox |
| --- | --- |
| Rate limits | the same as live, see [rate limits](/concepts/identity-and-tokens#rate-limits) |
| Key revocation | effective within 10 seconds, as in live |
| Test clocks | at most 10 per platform; a clock moves at most 400 days ahead |
| Reset | optional nightly reset at 02:00 Europe/Amsterdam (see [sandbox reset](/concepts/sandbox-reset)) |
| Bulk imports | at most 100 000 lines per job |
| Embed tokens | 1 hour; client secrets 15 minutes; a refresh chain ends after 12 hours |
| Request log | kept 30 days |
| Email | captured, never delivered |
| Filings | Digipoort conformance (or a simulated delivery for companies on a test clock); HMRC sandbox |
| AI | the smallest model only |
| Billing | none: sandbox companies are not counted or invoiced |
| Availability | one database instance with daily backups and no SLA; expect short outages for maintenance |

## Going live

Promote your platform from the portal. After that, create live keys and add your production origins. The code stays the same; only the keys and hostnames change.


---

<!-- /concepts/embed-security-model -->
# Embed security model

What stops a malicious page, a stolen secret or a curious user, and what does not.

## The token never reaches your page

Components run in iframes on FinBaze's origin. The embed token lives in memory in a hidden controller iframe and is handed to component iframes over private `MessagePort`s. Your page can only send options and receive events, so a script injected into your page cannot read a token. The iframes use no cookies or browser storage.

## Where components can run

FinBaze serves components with a `frame-ancestors` policy built from your **allowed origins**, so a browser refuses to render them on any other site. The session can additionally be bound to one origin (`origin` in `createEmbedSession`), which the exchange enforces.

## Single-use secrets

A client secret works once, for 15 minutes. If it leaks after the legitimate iframe used it, it is worthless; if it leaks before, whoever exchanges first wins and the other fails with `EMBED_SECRET_USED`, which you can see in the audit log.

## An allowlist of operations

Embed tokens can only run GraphQL documents that FinBaze ships in its **operations manifest**, identified by a hash of the normalised document. Introspection and arbitrary queries are refused. The manifest also ties each operation to the components and component features that may use it, and to the company the session was created for.

## Least privilege

Every write an embed can perform is a deliberate entry in the registry. Sessions list the components they need; features such as `submit` are off unless you turn them on. Viewers cannot write.

## Revocation and audit

Revocation reaches every server within 15 seconds. Every change made through an embed is recorded in the company's audit log as "*user* via *platform*", with the session id.

## Residual risks

- **XSS on your page.** An attacker running script on your page can call *your* session endpoint as the logged-in user, take the fresh secret to their own server and exchange it there, faking the `Origin` header (only browsers enforce it). Mitigations: the legitimate iframe usually exchanges first, secrets are single use and short lived, `origin` binding, the operation allowlist, audit and revocation. This is the same class of risk as other embedded-component products; keep your own session endpoint behind your normal authentication and CSRF protection.
- **Headless sessions** hand a token to your page, by design. Enable them only if you need them; they are off by default and limited to origins you list separately.


---

<!-- /concepts/test-clocks -->
# Test clocks

Move a sandbox company through months in minutes: invoices, reminders, filings and bank feeds follow the clock.

Test clocks exist in the sandbox only. A test clock holds a frozen time; companies attached to it see that time instead of the wall clock. Advancing the clock runs one simulated day after the other, in order, and then the clock is ready again.

```graphql
mutation { createTestClock(name: "Q1 run", frozenTime: "2026-01-02T08:00:00Z") { id status } }
mutation { advanceTestClock(id: "…", to: "2026-04-05T08:00:00Z", options: { submitFilings: true }) { status advanceTarget } }
query { testClocks { id name frozenTime status advanceTarget companies } }
mutation { deleteTestClock(id: "…") }
```

Attach a company when you create it (`createPlatformCompany(testClockId: …)`) or seed one (`seedTestCompany(input: { template, testClockId })`, see [Demo companies](/concepts/demo-companies)). A company is on at most one clock.

Scopes: `platform_companies:read` for `testClocks`, `platform_companies:write` for the rest.

## What a day runs

For each day, in this order, for every company on the clock:

1. The bank-feed simulator posts that day's transactions through the normal bank-feed ingestion path.
2. The scheduled jobs that normally run by wall time run once, at the clock's time: recurring invoices, payment matching, paid status, reminders, payment batches, depreciation, loan schedules, automations, filing policy, tax signals (Mondays), the tax advisor (first of the month), document requests.
3. With `submitFilings`, drafts that are ready are submitted, and the simulated Digipoort answers.
4. With `closeFinancialYear`, a financial year that has ended is closed.

A step that fails for one company is recorded as a warning (at most 20 are kept) and the day goes on. A failure of the loop itself marks the clock `failed` with `lastError`.

Only one clock advances at a time per platform. A second `advanceTestClock` on a busy platform queues behind the first; on a clock that is already advancing it answers `TEST_CLOCK_BUSY`.

## Simulated Digipoort

A clocked company's filings go to a simulated Digipoort, not to conformance. A delivery is accepted (status 500) unless the amount due ends in `.13`, which is rejected (status 510), so you can test both outcomes. The simulator follows the statuses of the Digipoort Happyflow tests; the real status codes and messages of your own company's live filings may differ.

Filing for a seeded company needs the same consent as any other: a company has to grant the tax authorisation before `submitFilings` submits for it.

## Events

`test_clock.ready` and `test_clock.failed` are platform-level events. Both carry `testClockTime`, the clock's time when the event was written. Events about a clocked company also carry `testClockTime`, next to the real `created`. Their JSON schemas are published with the event catalogue.

| Event | Data |
| --- | --- |
| `test_clock.ready` | the clock, `advancedFrom`, `days`, `warnings` |
| `test_clock.failed` | the clock and `error.message` |

## Errors

| Code | When |
| --- | --- |
| `SANDBOX_ONLY` | the call is made outside the sandbox |
| `TEST_CLOCK_NOT_FOUND` | no such clock on your platform (also for another platform's clock) |
| `TEST_CLOCK_LIMIT` | more than 10 clocks on the platform |
| `TEST_CLOCK_BACKWARDS` | `to` is not after the clock's time |
| `TEST_CLOCK_RANGE_TOO_LARGE` | one advance covers more than 400 days |
| `TEST_CLOCK_BUSY` | the clock is already advancing |

## Limits

- Deleting a clock deletes the companies on it.
- Rows keep their real `created` timestamp. Only business logic (due dates, periods, reminders, filings) follows the clock.
- Some jobs still use wall time. The following are converted: recurring invoices, reminders, payment batches, depreciation, loan schedules, automations, document requests, paid status, payment matching, tax filings, filing policy, tax signals and the tax advisor. Anything else runs on the real date.
- A 365-day run of the logistics template is measured nightly against a 60 minute budget.


---

<!-- /concepts/demo-companies -->
# Demo companies

Seed realistic test companies in the sandbox, with history, from seven templates.

`seedTestCompany` creates a platform company and fills it with demo data: customers, invoices, bank transactions, a filing history. Sandbox only.

```graphql
mutation {
  seedTestCompany(input: { template: nl_bv_logistics_oss, testClockId: "…", users: ["<platform user id>"] }) {
    id externalId legalName
  }
}
```

| Template | Company |
| --- | --- |
| `nl_eenmanszaak_services` | Dutch sole trader, services, quarterly VAT |
| `nl_bv_logistics_oss` | Dutch BV, EU customers (OSS and ICP returns) |
| `nl_bv_payroll` | Dutch BV with loonheffingen (5 employees and a year of monthly pay runs are the target data set; the seeder creates the wage-tax obligation today) |
| `nl_horeca_pos` | Dutch hospitality business with point-of-sale takings |
| `uk_ltd_vat` | UK limited company, VAT |
| `uk_ltd_itsa` | UK sole trader in Making Tax Digital for Income Tax (ITSA) |
| `us_corp_1120` | US C-corporation filing Form 1120 (company, obligation and bank account; no bookkeeping data yet) |

Options: `externalId` (default `seed-<template>`; seeding the same id again returns the existing company), `testClockId` (the history is anchored at the clock's time), `preserve` (keep it through the nightly reset), `users`.

## Magic registry numbers

Company lookups in the sandbox answer fixed results for these numbers (KvK and Companies House):

| Number | Result |
| --- | --- |
| `00000001` | an active company |
| `00000002` | a company that is dissolved |
| `99999999` | not found |

## Bank-feed scenarios

A clocked company's bank feed runs a scenario while the clock advances: customers who pay on time, pay late (20 days), and pay in part; supplier invoices to pay within 40 days. They arrive through the same ingestion path as a real bank connection.


---

<!-- /concepts/sandbox-reset -->
# Sandbox reset

Wipe your sandbox companies every night and seed a fresh set, or do it on demand.

Set how your sandbox is reset:

```graphql
mutation {
  updatePlatformSandboxSettings(input: { sandboxReset: nightly, sandboxSeedTemplates: [nl_eenmanszaak_services, nl_bv_logistics_oss] }) {
    sandboxReset sandboxSeedTemplates lastResetAt
  }
}
mutation { resetPlatformSandbox { companiesDeleted companiesKept clocksDeleted companiesSeeded { template companyId } errors } }
```

`sandboxReset` is `none` (default) or `nightly` (02:00 Europe/Amsterdam). A reset deletes every company on your platform and its data, test clocks included, then seeds one company per template in `sandboxSeedTemplates`. Companies created with `preserve: true` are kept. Reads use `platformSandboxSettings`.

The delete is permanent and covers everything that belongs to the company (hard delete, children first). A platform's reset never touches another platform. It runs only in the sandbox, and fails with `SANDBOX_ONLY` anywhere else.

When a reset finishes, the platform event `sandbox.reset.completed` is sent with `trigger` (`nightly` or `manual`), the counts of companies deleted, kept and seeded, and any `errors`. Only one reset runs at a time across the cluster.

Scopes: `platform_companies:write` to change the setting or reset.


---

<!-- /concepts/sending-data -->
# Sending data to FinBaze

Upserts, bulk jobs, bank feeds and statement files: how your data gets into a company's books.

Your backend pushes data with a **server key** and the scope of what it touches (`relations:write`, `sales_invoices:write`, `monetary_accounts:write`, …). Every object you create keeps your own id.

## Your ids and metadata

Relations, products, projects, cost centers, sales and purchase invoices, journal entries, employees and employments carry an `externalId` (unique per company and type) and up to 50 string `metadata` values. Find an object again with `platformObjectByExternalId`.

## One object: `upsert*`

`upsertRelation`, `upsertSalesInvoice`, … create the object or update it. The answer is `created`, `updated`, `unchanged` (the same data was already stored; nothing was written and no event is sent) or `deleted` (you deleted it earlier; add `restore: true` to bring it back).

- A **finalised** invoice (`finalise: true` numbers and books it) accepts `metadata` only. Correct it with a credit note: send an invoice with `creditOf: { externalId: … }` and no lines.
- `expectedTotalMinor` makes the call fail with `TOTAL_MISMATCH` if your prices and tax codes do not add up to what you expect. Tax is derived from the tax code, never taken from the line.
- Hidden modules still accept data (you may show the module later); a module that is **off** for the company answers `FEATURE_DISABLED`.

## Many objects: bulk jobs

`POST /v2/platform/bulk-jobs?object=relations` with an `Idempotency-Key` header and an NDJSON body (optionally gzip). The job is answered with 202 and applied in the background; every line is applied on its own, so one bad line fails alone. Read progress and per-line results with `platformBulkJob(id)`; the same file with the same key is the same job.

```ts
const job = await finbaze.platform.bulk.create({ object: "relations", company: { externalId: "acme-1" }, lines });
const done = await finbaze.platform.bulk.wait(job.id);
```

## Bank data: data sources

Register a **data source** (`registerDataSource`) per feed, attach it to companies (`attachDataSource`, or `autoAttach` for every new company), then deliver:

| Call |  |
| --- | --- |
| `upsertFeedBankAccount` | A bank, card or PSP account. An existing Lunch Flow account with the same IBAN is taken over with its history and processing. |
| `ingestBankTransactions` | Up to 500 booked transactions. `pending` lines are skipped. A line that changes after it was booked fails with `IMMUTABLE_TRANSACTION`; send a reversal (`reverses`) and a new transaction instead. |
| `reportBankBalances` | Balances are checked against the transactions. A mismatch changes nothing in the books and raises `feed.balance_mismatch`. The first closing balance after attaching sets the opening balance. |
| `reportFeedWatermark` | "Everything up to this date is delivered." Also the heartbeat of a quiet account; real-time and hourly feeds should send it at least once per gap threshold. |

Bank rows you deliver are read-only for the company's users (`PARTNER_SOURCED_READ_ONLY`); they can still process and split them.

### Statement files

`POST /v2/platform/data-sources/{key}/files?format=camt053|camt052|mt940` accepts one file for many companies, routed by account IBAN to the attached companies. Accounts that are not routed are listed in `unroutedAccounts`. The same booking arriving as camt.052, camt.053 or MT940 is stored once. Follow a file with `dataSourceFiles` and the events `data_source_file.processed` / `.failed`.

### Feed health

`feedHealth` shows `healthy`, `delayed`, `gap`, `balance_mismatch` or `stopped` per account, and the events `feed.delayed`, `feed.gap_detected`, `feed.balance_mismatch` and `feed.recovered` announce changes.

## Your own objects

`definePlatformRecordType` describes a shipment, a job or a Z-report; `upsertCustomRecord` pushes one. A **flow template** turns a state change into bookings (invoice, journal entry, reversal) with the same rules as the calls above. See [Records and flow templates](/concepts/records-and-flows).


---

<!-- /concepts/records-and-flows -->
# Records and flow templates

Push your own objects and let a template turn their state changes into invoices and bookings.

## Record types

```graphql
mutation { definePlatformRecordType(input: {
  key: "shipment", name: "Shipment",
  schema: { type: "object", required: ["reference"], properties: { reference: { type: "string" } } },
  states: ["booked", "delivered", "cancelled"], initialState: "booked",
  displayTemplate: "Shipment {{data.reference}}"
}) { version } }
```

Changing the schema, states or transitions creates a new version; an identical call returns the current one. `transitions` (`{ "booked": ["delivered"] }`) restricts which moves are allowed.

## Records

`upsertCustomRecord` creates or updates a record by `(company, type, externalId)`. `data` is validated against the type. A change of status or data bumps `revision`; the record keeps its history, the bookings it caused (`effects`) and its runs. `deleteCustomRecord` only works for a record without bookings.

## Flow templates

A template is YAML or JSON:

```yaml
apiVersion: finbaze.com/flows/v1
kind: FlowTemplate
metadata: { key: shipment-invoicing, version: 1, recordType: shipment }
chart: rgs
ledgers: { carrier_costs: "<ledger code>", accrued_costs: "<ledger code>" }
on:
  - transition: { to: delivered }
    onDataChange: rebook          # ignore (default) | rebook | fail
    steps:
      - id: invoice
        create_sales_invoice:
          relation: "= steps.customer.id"
          date: "= $date(record.data.deliveredAt, 'Europe/Amsterdam')"
          currency: "= record.data.currency"
          finalise: true
          lines:
            - forEach: "= record.data.lanes"
              as: lane
              name: "Transport {{ lane.from }} - {{ lane.to }}"
              priceMinor: "= lane.revenueMinor"
              taxCode: NL_2012_HIGH
```

- `"{{ path }}"` interpolates text. A string starting with `=` is a [JSONata](https://jsonata.org) expression with typed results. Functions you can define yourself and `$eval` are not available.
- Helpers: `$lookup(table, ctx)`, `$net(grossMinor, taxCode)`, `$vatRate(taxCode)`, `$date(timestamp, zone)`, `$euCountry(code)`.
- Steps: `upsert_relation`, `upsert_project`, `create_sales_invoice`, `create_purchase_invoice`, `create_journal_entry`, `reverse` and `fail`. Objects get the id `flow:<template>:<record>:<step>`, so running a trigger again changes nothing.
- A `reverse` step credits the invoices and mirrors the journal entries that a step of an earlier run created. It uses what that run recorded, never the current template.

`testFlowTemplate` plans what a template would do for sample records without writing anything. `activateFlowTemplate` checks that the ledgers named in `ledgers` exist in your companies' charts.

## Runs

A run is one transaction: if a step fails, nothing of the run is kept and the run is `failed` with the step, code and path. Runs of one record go in order, so a failed run holds the later ones back until you `retryFlowRun`. Events: `flow_run.succeeded` and `flow_run.failed`.


---

<!-- /concepts/events-and-webhooks -->
# Events and webhooks

What happened to your companies' data, delivered to your endpoint or read in order.

## Events

Every event has an id (`evt_…`), a `type` (`company.created`, `sales_invoice.created`, `bank_transaction.booked`, …), the `apiVersion` it was written in, the company, and a snapshot of the object in `data.object`. Read the catalogue with `platformEventCatalog`; entries with status `planned` are not sent yet. An event of a module that is hidden or off for the company is not published.

`platformEvents(after: <sequence>)` returns events in order; store the last `sequence` and continue from it after downtime. Events are kept for 30 days.

## Webhook endpoints

```ts
const endpoint = await finbaze.platform.webhookEndpoints.create({ url: "https://example.com/finbaze", eventTypes: ["company.created", "bank_transaction.booked"] });
// endpoint.signingSecret is shown once
```

Each delivery is a `POST` with `X-FinBaze-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. Verify it with `finbaze.webhooks.constructPlatformEvent(rawBody, header, secret)`; dedupe on the event id.

- **Retries** after a failure with growing delays (30 seconds up to 24 hours, 8 attempts). A `410 Gone` disables the endpoint at once; an endpoint that keeps failing is disabled with a reason and a notice. `failoverUrl` is tried when the main URL fails.
- **Rotation.** `rotatePlatformWebhookSecret` returns a new secret; for `keepPreviousHours` the old one signs as well (the header carries two `v1` values), so you can deploy the new secret without losing a delivery. Pass `[new, old]` to `constructPlatformEvent` while both are live.
- **Replay.** `replayPlatformWebhookDelivery`, `replayPlatformWebhookDeliveries` (by filter, rate limited) and `resendPlatformEvent` send an event again, marked `X-FinBaze-Replay`.
- `pingPlatformWebhookEndpoint` sends a test event.

## Order and duplicates

Webhooks are at-least-once and not ordered across events. Use `sequence` to order, and the event id to dedupe.


---

<!-- /concepts/getting-data-out -->
# Getting data out

Reports, documents, the audit file and scheduled exports to your own bucket.

## Reports

`platformReport(company, input)` for `profit_loss`, `balance_sheet`, `trial_balance`, `vat_position` (needs a `taxFilingId`), `cashflow`, `aged_receivables`, `aged_payables`, `kpis`, `general_ledger` and `forecast`. Amounts are in minor units. `profit_loss` and `balance_sheet` return `lines` (`amountMinor` in the normal sign, `signedMinor` debit-positive) and `totals`; `compare: previous_period | previous_year` adds `compareMinor`. `general_ledger` is paged with `offset` and `limit`. `platformReportDocument` renders a report as `XLSX` or `PDF` (profit and loss, balance sheet, cash flow, forecast, aged reports). PDFs use the company's `report` document layout (your preset or the company's own), like payslips and annual accounts.

## Documents

`companyDocument(company, kind, object, params)` renders on demand. The answer has a `downloadUrl` that works for 15 minutes without a token (`GET /v2/platform/files/<token>`), and files are kept 24 hours.

| Kind | `object` | `params` | Module |
| --- | --- | --- | --- |
| `sales_invoice_pdf`, `sales_invoice_ubl`, `credit_note_pdf` | invoice (`id` or `externalId`) |  | `sales_invoices` |
| `quote_pdf`, `reminder_pdf` | quote / reminder |  | `quotes` / `reminders` |
| `purchase_invoice_original` | purchase invoice | `documentId` (optional) | `purchase_invoices` |
| `receipt_original` | bank transaction (`id` or `externalId`) | `documentId` (one of `booking.receipt.documentIds`) | `banking` |
| `tax_filing_pdf` | filing (`id`) |  | `tax_filings` |
| `tax_filing_receipt` | submitted filing (`id`); JSON with the reference and the authority's status messages |  | `tax_filings` |
| `annual_accounts_pdf` | financial year (`id`), or none | `financialYear` | `annual_accounts` |
| `payslip_pdf`, `year_document_pdf` | payslip / year document (`id`) |  | `payroll` |
| `report_pdf`, `report_xlsx` |  | the `PlatformReportInput` fields | the report's |
| `xaf` |  | `financialYear` or `from`/`to`, `version` (`4.0` default, `3.2`) |  |

Every kind also needs `data_export`. A transaction without a receipt answers `NOT_ATTACHED`; a draft filing has no receipt (`UNSUPPORTED_OPERATION`). `audit_log` is not a company document: use `requestAuditLogExport`.

## The audit file

`requestXafExport(company, financialYear, version)` writes an Auditfile Financieel in the background: XAF 4.0 by default (the only version the Belastingdienst accepts from 1 January 2027), `version: "3.2"` for receivers that still need it. The run's `document` carries the link when it is ready, and `export.ready` is sent. Invoice lines carry their VAT (`vat`: code, percentage, amount) and the relation (`custSupID`, the relation id without hyphens); the VAT codes used are listed in `vatCodes`. The 4.0 output is validated against the official XSD; 3.2 follows the official field order but is not validated.

## Scheduled exports

1. `createPlatformExportDestination` with an S3 (or S3-compatible `endpoint`, such as GCS interoperability, OVH or MinIO) bucket and keys, or an Azure container SAS URL. FinBaze writes `_finbaze_check/<time>.txt` to prove it can; credentials are encrypted and never returned.
2. `createPlatformExportSchedule` with `datasets`, `format` (`parquet`, `csv`, `ndjson`), a `cron` (at most once an hour) and `timezone`.
3. `runPlatformExportNow(key, companies)` queues a run, optionally for some of the schedule's companies only (`companies`; the manifest lists them in `companyFilter`, and the other companies' next run still carries their changes); `platformExportRun` shows it.

Datasets: `journal_lines`, `trial_balance` (snapshots), and `bank_transactions`, `sales_invoices`, `sales_invoice_lines`, `purchase_invoices`, `purchase_invoice_lines`, `relations`, `custom_records`, `record_effects`, `vat_returns` (only what changed since the last run, with `op` = `upsert` or `delete`). `vat_returns` holds the NL and UK VAT returns: period, status, reference, `amount_due_minor` and the `boxes` as computed or filed. Every row has `company_id`, `company_external_id` and `exported_at`. A run writes the data files first, then `_manifest.json`, then an empty `_SUCCESS`: a folder without `_SUCCESS` is incomplete.

## What happened to a bank transaction

`bankTransactionBookings(company, externalIds)` (at most 100) returns the status (`unbooked`, `suggested`, `booked`, `needs_review`), the counterpart, the ledger legs, the VAT code, the invoice's VAT (`vatAmountMinor`), the receipt status and its documents, what FinBaze proposes for an unbooked transaction (`suggestion`: counterpart, ledger, confidence) and why it needs a person (`reviewReason`: `policy_review_required`, `awaiting_document`, `amount_difference`, `low_confidence`). The same object is `booking` on `MonetaryAccountPayment`. The events `bank_transaction.booked`, `.unbooked`, `.needs_receipt` and `.needs_review` tell you when one changes.


---

<!-- /concepts/messages -->
# Messages

How FinBaze hands you what it would otherwise email to your users, and how you confirm you delivered it.

FinBaze says things to people: a VAT return is ready, a receipt is missing, an agent needs approval. For a company on your platform your users have no FinBaze inbox, so FinBaze never emails them on its own. Each message is stored first, then routed by who should deliver it. The [message catalogue](/reference/message-catalogue) lists every type.

## Routing

| Routing | What happens |
| --- | --- |
| `partner_delivers` | You receive `message.created` and deliver it in your own app, push or email. **The default for notifications.** |
| `finbaze_sends` | FinBaze emails the user. Needs a verified sender domain for your platform, so mail never shows "via FinBaze"; without one the message falls back to `partner_delivers`. |
| `both` | You receive the event and FinBaze sends the email. |
| `suppress` | Nobody sends it. It still shows in the log with the reason. |

Set a rule with `platform.messages.routing.set` for everything (`scope: 'all'`), one category or one type, for the whole platform or one company. The most specific rule wins: company type, company category, company all, platform type, platform category, platform all, then the catalogue default.

Lifecycle, billing and FinBaze account-security messages are never delivered for platform companies and cannot be changed (`ROUTING_NOT_CHANGEABLE`). A message of a feature you hide for the company is not sent at all.

## Receiving a message

```ts
const event = await finbaze.webhooks.constructPlatformEvent(rawBody, signature, secret);
if (isMessageEvent(event) && event.type === "message.created") {
  const message = event.data.object;
  if (message.type === "tax.filing_ready") {
    await push(message.recipient, message.content.push); // message.data is typed for this type
  }
  await finbaze.platform.messages.acknowledge({ id: message.id, channel: "push" });
}
```

`data.object` is the message:

| Field |  |
| --- | --- |
| `id`, `type`, `category`, `priority` | `critical`, `normal` or `digestible` |
| `recipient` | The platform user (`kind`, `account`), by FinBaze id |
| `content` | Ready-made `push` (title ≤ 50, body ≤ 150), `in_app` (title ≤ 80, body ≤ 400, `cta_label`, `severity`), `email` (`subject`, `text`) and `sms` (≤ 160). Links are stripped from model-written text |
| `deep_link` | `{ route, params }`, the same routes the embedded components open |
| `data` | The type's payload, typed as `MessageData<'tax.filing_ready'>` in the SDK |
| `ack_required`, `ack_deadline` | Whether and until when FinBaze expects an acknowledgement |
| `dedupe_key`, `expires_at`, `created` | Dedupe on `dedupe_key`; do not deliver after `expires_at` |

Deliveries are at least once. The same message to the same person for the same thing on the same day has the same `dedupe_key`.

## Acknowledging

Critical messages, and messages that serve as evidence (invoices and reminders you deliver), need an acknowledgement: `messages.acknowledge({ id, channel, deliveredAt?, providerMessageId?, outcome? })`, or `acknowledgeMany` for up to 100. It is idempotent. `outcome: 'failed'` tells FinBaze you could not deliver; the message then stays unacknowledged. `markRead` records that the user saw it.

For invoices and reminders the acknowledgement is written to the invoice's event log (`partner: true`, channel, your id, delivery time), so a dispute has the same trail as for a mail FinBaze sent itself.

If no acknowledgement arrives by `ack_deadline` (default 60 minutes for critical, 240 otherwise), FinBaze sends `message.unacknowledged` with the same object. With `criticalEmailFallback` on and a verified sender domain, FinBaze then emails a critical message itself after `fallbackAfterMinutes` (default 60).

## Quiet hours, digests and limits

- **Critical messages** are never held, digested or limited.
- **Quiet hours** (`settings.update({ quietHours })`, in `company` time or an IANA zone) hold other messages until the window ends.
- **Digests.** Types marked digestible are folded into one `digest.<category>` message per person, daily at `digestHourLocal` or hourly, when your rule asks for it or the type's default says so.
- **Limits.** More than 20 messages per person per hour, or 3 of one type, fold into an hourly digest.

## Reading the log

`platform.messages.list({ company?, status?, unacknowledgedOnly? })` shows what was sent, the routing decision and why (`routingReason`: `catalogue_default`, `platform_category`, `company_override`, `hard_rule`, `feature_hidden`, …), and the acknowledgement state. The developer portal has the same under **Messages**, with the routing matrix and settings.

## Push notifications and the Expo sub-processor

FinBaze sends push notifications only to **FinBaze's own mobile app**, for companies that are not on a platform (feature key `push_notifications`). A platform company's users have no FinBaze app: you deliver push yourself from `message.created`, and FinBaze never pushes for them.

For its own app FinBaze uses **Expo's push service** (`exp.host`) to reach Apple's and Google's push networks. Expo is therefore a sub-processor for FinBaze direct customers:

- **What Expo receives.** The device's push token and the notification text (title up to 50 and body up to 150 characters, plus a deep-link route). For tax deadlines and document notices the lock-screen text is generic: no amounts, names or file names.
- **What it does not receive.** No documents, no bookkeeping data, nothing about platform companies.
- **Switch.** `api.jobs.message_dispatch.push.enabled` is `false` in production. It is switched on only after Expo is on the published sub-processor list, the data processing agreement with Expo is signed, and customers have had the notice period the DPA requires. Until then the in-app notification centre and email carry the messages.
- **Dead devices.** Expo receipts are read 15 minutes after sending; a token Expo reports as unregistered is removed.

If you hold a data processing agreement with FinBaze, this changes nothing for you: platform companies never reach this path, and the sub-processor list in your agreement only changes when push is enabled for FinBaze direct customers.


---

<!-- /concepts/company-lifecycle -->
# Company lifecycle

Suspend, close, archive and transfer a company, end a user, and read the audit log.

A company on your platform is `active`, `suspended`, `closed` or `archived`. You move it with your server key; FinBaze staff can move any company. Books, filings, documents and Digipoort or HMRC history are never deleted by a lifecycle change.

| State | What it means |
| --- | --- |
| `active` | Normal. |
| `suspended` | Read-only. Mutations fail with `COMPANY_SUSPENDED` (ending an authorisation or engagement, answering a support request and exports still work). Cron work (recurring invoices, payment batches, reminders, bank sync) skips the company. A suspended company does not count as active for usage. |
| `closed` | The company stopped trading on `closeEffectiveDate`. Final returns can still be filed and exported; everything else fails with `COMPANY_CLOSED`. |
| `archived` | Detached from your platform. Only exports work (`COMPANY_ARCHIVED`). The books are kept until `retentionUntil` (per country, 7 years in the Netherlands by default, counted from the later of the closing date and the last financial year end). Archived companies are hidden from `platformCompanies` unless you pass `includeArchived`. |

## Moving a company

```ts
await finbaze.platform.companies.suspend(id, { reason: "non-payment", displayMessage: "Your account is on hold." });
await finbaze.platform.companies.reactivate(id);

const checklist = await finbaze.platform.companies.closingChecklist(id, "2026-10-31");
await finbaze.platform.companies.close(id, { effectiveDate: "2026-10-31" });
await finbaze.platform.companies.reopen(id);   // within the reopen window (90 days by default)
await finbaze.platform.companies.archive(id);  // needs every blocking checklist item done
```

The checklist has one blocking item per registered return (final VAT, ICP, OSS, corporate income tax) and informational items (open receivables and payables, deregistration with the KVK and the Belastingdienst). `archive` fails with `ARCHIVE_BLOCKED` while a blocking item is open. A company FinBaze suspended cannot be reactivated by you (`SUSPENDED_BY_FINBAZE`).

Errors: `INVALID_LIFECYCLE_TRANSITION`, `INVALID_EFFECTIVE_DATE`, `REOPEN_WINDOW_PASSED`, `ARCHIVE_BLOCKED`, `SUSPENDED_BY_FINBAZE`, `NOT_A_PLATFORM_COMPANY`.

Events: `company.suspended`, `company.reactivated`, `company.closed`, `company.reopened`, `company.archived`.

## Transfers

A company can move to another platform or to direct FinBaze. The company's admin consents in the embedded `company-transfer` element, which shows a versioned statement and sends back its hash; the consent is audited with the statement version and hash.

- **To another platform.** The element shows a one-time 12-character code, once. Hand it to the receiving platform, whose backend calls `platform.transfers.accept(code, externalId)`. The code works once and expires (14 days by default); every wrong, used or expired code fails the same way (`TRANSFER_CODE_INVALID`).
- **To direct FinBaze.** The company admin enters an email address and FinBaze emails a claim link to `/claim-company/<code>`. A signed-in FinBaze account claims the company and chooses a plan, or keeps its accountant when it has one.

On completion the sending platform loses access: its users, limits, data sources and embed sessions are detached, and you receive `company.transferred_out`. The receiving side gets `company.transferred_in`. The former owner never sees the new owner's `externalId`. Cancel a pending transfer with `platform.transfers.cancel`; `company.transfer.created` and `company.transfer.cancelled` report the rest.

Errors: `TRANSFER_CODE_INVALID`, `TRANSFER_CODE_EXPIRED`, `TRANSFER_ALREADY_PENDING`, `TRANSFER_TO_SAME_PLATFORM`, `TRANSFER_WRONG_TARGET`, `TRANSFER_STATEMENT_OUTDATED`, `TRANSFER_EMAIL_REQUIRED`, `TRANSFER_EMAIL_MISMATCH`, `EXTERNAL_ID_TAKEN`.

## Ending a user

`platform.users.deprovision(id, { anonymise })` revokes every token and embed session of the hidden user at once and removes the user from all companies. Tokens issued before the call fail with `UNAUTHENTICATED`. `platform.users.upsert` with the same `externalUserId` brings the user back with a new identity; old tokens stay dead. Event: `platform_user.deprovisioned`.

## Audit log

`platform.audit.list({ filter, limit, starting_after })` returns what happened to your companies, newest first, in keyset pages (`nextCursor`). It needs the `audit:read` scope and an admin role, and only ever shows your own companies; another platform's entries do not exist for you. Each entry carries the actor (`actorKind`: `user`, `platform`, `support`, ...), `platformUserId` and `platformUserExternalId`, `tokenType`, `ip`, `userAgent`, `requestId` (also returned as the `X-Request-Id` response header), `stepUpAssertionId` and `supportGrantId`. Secrets, tokens, transfer codes and bank details are redacted. `platform.audit.export(filter)` starts an NDJSON export that appears on `platform.exports`.


---

<!-- /concepts/delegated-actions -->
# Delegated actions

What FinBaze asks your platform to do: pay tax, suppliers and wages, supply a payment link, confirm a user, take a photo.

Some things only your platform can do: move money from your users' accounts, confirm that it really is the user (biometrics, SCA), open the camera. FinBaze asks; you do it in your own app and tell FinBaze how it went. What you do is declared once with a **provider** per action:

```graphql
mutation {
  upsertPlatformProvider(
    input: {
      action: payments
      mode: both # webhook, embed or both
      config: { kinds: ["tax", "supplier_batch", "wages"], includePain001: true }
    }
  ) { id enabled }
}
```

| Action | Config | Needs the feature |
| --- | --- | --- |
| `payments` | `kinds`, `includePain001`, `pain001Version` | `delegated.payment_requests` |
| `payment_links` | `allowedHosts`, `waitSeconds` (30), `replaceFinbazePsp` | `delegated.payment_links` |
| `tax_reservation` | `taxes` (`nl_vat`, `nl_wage_tax`), `cadence`, `minAmountMinor` | `delegated.tax_reservation` |
| `step_up` | `actions`, `jwksUrl` (https) or `keys`, `maxAgeSeconds` | `delegated.step_up` |
| `camera` | none (embed only) | none |

FinBaze puts the feature in your allowance per contract. Registering without it fails with `FEATURE_NOT_ALLOWED`, and a request made after it was taken away fails the same way.

## Payment requests

A payment request is FinBaze asking you to pay something it has worked out: the VAT or wage tax of an accepted filing, a supplier batch, or net wages. FinBaze creates them itself when a VAT or wage tax filing is accepted with an amount due, when a pay run batch is created, and on demand with `createTaxPaymentRequest` and `createPaymentRequestFromBatch`. You get `payment_request.created` with every line:

```json
{
  "id": "pr_4b1f…",
  "kind": "tax",
  "amountMinor": 124000,
  "currency": "EUR",
  "dueDate": "2026-10-31",
  "endToEndId": "FB7KQ2M4XH3TD5N6P8RA",
  "lines": [
    {
      "creditorName": "Belastingdienst",
      "iban": "NL86INGB0002445588",
      "amountMinor": 124000,
      "structuredReference": "1234567891230010",
      "endToEndId": "FB7KQ2M4XH3TD5N6P8RA-001"
    }
  ]
}
```

- **Pay exactly these lines.** Creditor IBANs are fixed when the request is created, from verified data. You cannot change them, and a request whose lines you edit will not be matched.
- **Put the `endToEndId` in the SEPA `EndToEndId`** (the line's, for a batch), and for tax the `structuredReference` as the payment reference. Supplier and wage batches come with a signed `pain001Url`.
- **Report progress with `reportPaymentRequestStatus`**: `sent`, `accepted`, `scheduled`, `failed` or `cancelled`. You can never report `paid`. A request becomes `paid` (or `partially_paid`) only when the bank transaction shows up in the company's books and is matched by end-to-end id, or for tax by the betalingskenmerk, the Belastingdienst IBAN and the exact amount. Push the bank feed with the data API and it happens by itself.
- **`approvePaymentRequest`** records which user confirmed it in your app (and, when you require it, the step-up).

In an embedded `vat-return`, the **Pay** button creates the request and calls your page:

```ts
const finbaze = await loadFinBaze(publishableKey, {
  fetchClientSecret,
  onPaymentRequested: async (request) => {
    const transfer = await openTransferScreen(request.lines, request.endToEndId);
    return { status: transfer.confirmed ? "accepted" : "cancelled", partnerReference: transfer.id };
  },
});
```

Without the callback there is no Pay button.

## Payment links

With a `payment_links` provider, FinBaze asks you for the link before it sends an invoice: you get `payment_link.requested` and have `waitSeconds` to answer with `providePaymentLink(requestId, url)`. The link must be `https` on one of your `allowedHosts`. The invoice email, the PDF and the public page then show your link, and FinBaze's own payment buttons are hidden for that invoice (`replaceFinbazePsp`). Past the deadline the invoice goes out without it, with FinBaze's own options; a link that arrives later still shows on the public page. A payment that reaches the bank is matched by the invoice number in the reference as usual.

## Tax reservation

`tax_reservation.advised` says how much a company should have set aside now for its open VAT or wage tax period (VAT collected minus deductible so far; wage tax withheld on approved or paid pay runs). A new advice supersedes the previous one for the period. Tell FinBaze what you reserved with `reportTaxReservation(adviceId, reservedMinor, accountRef)`; `taxReservationAdvice(company)` lists them.

## Step-up

With a `step_up` provider, high-risk actions by your users need your confirmation: `tax_filing.submit`, `pay_run.approve`, `bank_details.change` (adding, changing or deleting a creditor's bank account) and `payment_request.approve`. `tax_authorisation.grant` is also available: list it to have every [filing consent](/concepts/filing-consent) confirmed. Your server tokens are not affected.

1. The user does the action in the embedded component. FinBaze answers `STEP_UP_REQUIRED` with a challenge (`id`, `nonce`, `action`, `summary`, valid for five minutes) and sends `step_up.required`.
2. The component hands the challenge to your page (`onStepUp`). Run your biometrics or SCA.
3. Your **backend** signs a JWS for it and the page returns it. The component retries the action with `FinBaze-Step-Up: <challengeId>.<jws>`.

```ts
import { SignJWT, importPKCS8 } from "jose";

export async function signStepUp(challenge: Challenge, user: { externalUserId: string }, amr: string[]) {
  const key = await importPKCS8(process.env.STEP_UP_PRIVATE_KEY!, "ES256");
  const now = Math.floor(Date.now() / 1000);
  return new SignJWT({
    challenge_id: challenge.id,
    nonce: challenge.nonce,
    action: challenge.action,
    amr, // e.g. ["bio"] or ["sca"]
  })
    .setProtectedHeader({ alg: "ES256", kid: "step-up-1" })
    .setIssuer(PLATFORM_ID) // your platform id
    .setAudience("finbaze")
    .setSubject(user.externalUserId)
    .setIssuedAt(now)
    .setExpirationTime(now + 120) // at most maxAgeSeconds
    .sign(key);
}
```

With the SDK you do not need `jose`: `finbaze.platform.stepUp.sign` (also exported as `signStepUp`) builds the same assertion with Node's `crypto` and returns the `FinBaze-Step-Up` header value (`<challengeId>.<jws>`):

```ts
const header = await finbaze.platform.stepUp.sign({
  challenge, // { id, nonce, action } from step_up.required or the STEP_UP_REQUIRED error
  issuer: PLATFORM_ID,
  subject: user.externalUserId,
  privateKey: process.env.STEP_UP_PRIVATE_KEY!, // PEM (PKCS#8) or JWK
  algorithm: "ES256", // or "EdDSA", "RS256"
  keyId: "step-up-1",
  amr: ["bio"],
});
```

```ts
onStepUp: async (challenge) => {
  const confirmed = await confirmWithBiometrics(challenge.summary);
  if (!confirmed) return null;
  return { jws: await api.signStepUp(challenge) };
},
```

FinBaze verifies it against your `jwksUrl` (cached ten minutes, key rotation by `kid`) or your registered `keys`. Only `ES256`, `EdDSA` and `RS256` are accepted. The assertion must name this challenge, its nonce and action, the user it was for, and live no longer than `maxAgeSeconds`. A challenge works once.

## With the SDK

```ts
const { platform } = finbaze;
await platform.providers.upsert({ action: "payments", mode: "webhook", config: { /* debtor account, limits */ } });

// A request for an accepted VAT filing; FinBaze marks it paid when the bank transaction arrives.
const request = await platform.paymentRequests.createForTaxFiling({ externalId: "acme" }, taxFilingId);
await platform.paymentRequests.reportStatus({ paymentRequestId: request.id, status: "scheduled", partnerReference: "bank-123" });

// Answer payment_link.requested before its deadline.
await platform.paymentLinks.provide({ requestId, url: "https://pay.example.com/i/42" });

// Tax reservation.
const [advice] = await platform.taxReservation.advice({ externalId: "acme" });
await platform.taxReservation.report({ adviceId: advice.id, reservedMinor: advice.amountMinor });
```

`reportStatus` never accepts `paid`: FinBaze marks a request paid when the matching transaction arrives. The events (`payment_request.created`, `payment_request.paid`, `payment_link.requested`, `tax_reservation.advised`, `step_up.required`) are typed: `isControlEvent(event)` narrows an event from `constructPlatformEvent` to `PlatformControlEvent`.

## Camera

With a `camera` provider (or the `onCameraCapture` callback) the components ask your page to take the photo: `{ purpose, accept, maxBytes }` in, `{ name, mime, data }` or `null` out. Without it the component opens the phone's own camera through a file input.


---

<!-- /concepts/filing-consent -->
# Filing consent

FinBaze files a company's returns only with the company's authorisation. How the consent is given, what it covers, and how you read and revoke it.

For your companies FinBaze files the returns itself: VAT, ICP, OSS, corporate income tax, annual accounts, wage tax and the pension declaration, and for the UK VAT and Income Tax. It only does so with the **company's authorisation**. The company's own user gives it, in your app, in front of a text that names **FinBaze B.V. as the filer** and your platform only as "via {your platform}". Your backend cannot give it for them.

## Who files

FinBaze files as a **software supplier**: it is not a tax intermediary and has **no BECON number**. For a company on your platform that has no accountant connected, FinBaze submits the return on the company's behalf under the company's own authorisation: the return is filed in the company's name as the taxpayer (`Bedrijf`), with no intermediary number in it, and FinBaze's filing desk as the contact for questions. The stored consent record is the legal basis.

- A company whose accountant files a tax (see [working with accountants](/concepts/working-with-accountants)) is filed by the accountant, with the firm's own BECON number, instead.
- A request that only an intermediary may make, such as the corporate income tax extension (`nl_cit_uitstel`), is refused for a company without an accountant with `FILER_MUST_BE_INTERMEDIARY`. It is a blocked reason (`taxFilingSubmitPreview.blockedReason`), not a failure: show that the company's accountant files it.
- FinBaze staff never file for your companies, also not under a support grant.

## Who does what

|  | Embed or headless session (the company's admin user) | Your server token | FinBaze staff |
| --- | --- | --- | --- |
| Read the statement, grant | yes (`grantTaxAuthorisation`) | **no**, `FORBIDDEN_TOKEN_TYPE` | no |
| Read status and history | yes | yes | yes |
| Revoke | yes | yes (for instance when you offboard a company) | yes, on written instruction |

A user token minted by your backend (`createPlatformUserToken`) cannot grant either. The session must include the `onboarding` or the `tax-authorisation` component, and the user must be an `admin` of the company. A company of another platform answers `404`.

## The consent in your app

In the embedded components the consent is already there:

- **`onboarding`** shows a "Filing authorisation" step while a `tax_<tax>_authorisation` requirement is `currently_due` (see below). Switch it off per session with `components.onboarding.features.filingConsent: false`.
- **`tax-authorisation`** shows the status per tax, the history, a grant for what is missing and a revoke per tax with a dialog that says what it does ("FinBaze will no longer submit your Dutch VAT returns; you can still prepare them"). `features.grant` and `features.revoke` switch the buttons off.
- **`vat-return`, `icp-return`, `oss-return`** show the grant panel in place of an error while FinBaze may not file yet (`features.inlineConsent`; without it they send the user to the `tax-authorisation` component with a `navigate` event). When the company's accountant files the tax they say so.

The components emit `tax_authorisation.granted` and `tax_authorisation.revoked` with `{ companyId, taxes, channel, stepUp, at }`, the payload of the webhook.

If you build your own screens with the [headless hooks](/sdks/headless), `useTaxAuthorisation()` gives you `status`, `statement(taxes)`, `grant({ statement })`, `revoke()` and `history()`:

```tsx
const { status, statement, grant } = useTaxAuthorisation();
const shown = await statement(["nl_vat", "nl_icp"], "nl-NL"); // render shown.title and shown.paragraphs
await grant({ statement: shown });                             // sends shown.version and shown.hash back
```

## What the user agrees to

`taxAuthorisationStatement(companyId, taxes, locale)` returns the statement for the chosen taxes: a title, the paragraphs (one per tax: what FinBaze files, when, that the user reviews before submitting; what revoking does; that an accountant who files a tax files it instead) and a `hash`. The grant sends back the `statementVersion` and `statementHash` it displayed. FinBaze renders the same text again and refuses any difference with `TAX_AUTHORISATION_STATEMENT_OUTDATED`, so the stored record proves the exact text, the language and the taxes. Statements are versioned (`nl-2026-10`, `en-2026-10`). A statement that changes meaning is published as a new version: existing grants show as `reconfirmation_due` and stay valid for a grace period (60 days) while the user confirms again.

## Taxes

| Tax | Covers |
| --- | --- |
| `nl_vat` | VAT returns, corrections (suppletie), objections, EU VAT refund requests |
| `nl_icp`, `nl_oss` | ICP and OSS returns |
| `nl_cit` | Corporate income tax return, extension, provisional assessment, objection |
| `nl_annual_accounts` | Annual accounts |
| `nl_wage_tax`, `nl_pension` | Payroll tax returns and the pension declaration (UPA) |
| `uk_vat`, `uk_income_tax` | UK VAT and MTD Income Tax. The HMRC connection stays as it is; this is FinBaze's authority to file |
| `uk_annual_accounts` | UK annual accounts at Companies House. Registered when the company's annual accounts file at Companies House (a UK company, LLP or qualifying partnership), not by a tax obligation |

A grant can only name taxes the company has an obligation for (`TAX_NOT_REGISTERED` otherwise).

## Status, history and revoking

```graphql
query { taxAuthorisationStatus(companyId: "…") { tax state firmName } }
```

`state` is `active`, `missing`, `reconfirmation_due` or `delegated_to_firm` (a firm engagement covers the tax; the firm files it, `firmName` says who). Direct FinBaze companies have no consent and get no rows.

```graphql
query { taxAuthorisations(companyId: "…", includeRevoked: true) { id taxes channel grantedAt stepUp revokedAt revokedVia supersedesId grantedBy { externalUserId } } }

mutation { revokeTaxAuthorisation(input: { companyId: "…", taxes: [nl_icp], reason: "offboarding" }) { id taxes revokedAt } }
```

The history is append-only. A revoke for some of a grant's taxes revokes that grant and writes a new one for the rest (`supersedesId`) that keeps the original evidence. Records are never deleted. **A revoke is effective on the next request**: the next submit for that tax fails with `TAX_AUTHORISATION_REQUIRED`. Drafts stay.

```ts
await finbaze.platform.taxAuthorisations.status(companyId);
await finbaze.platform.taxAuthorisations.list(companyId, { includeRevoked: true });
await finbaze.platform.taxAuthorisations.revoke(companyId, { taxes: ["nl_icp"], reason: "offboarding" });
```

There is no `grant` in the server SDK, on purpose.

## Requirements

For each active obligation that maps to one of these taxes, `onboardingRequirements` lists `tax_<tax>_authorisation` (for example `tax_nl_vat_authorisation`; in the design notes this is `tax.<tax>.authorisation`) as `currently_due` while the tax is `missing` or `reconfirmation_due`. It is absent once `active` or `delegated_to_firm`. When it changes you get `company.requirements.updated`.

## Step-up

If your `step_up` provider lists the action `tax_authorisation.grant` (see [delegated actions](/concepts/delegated-actions)), the first `grantTaxAuthorisation` fails with `STEP_UP_REQUIRED` and a challenge. The embedded components hand it to your page (`onStepUp`) and retry with your signed assertion; with the headless hook the error carries `extensions.challenge` and you call `grant` again with `stepUp: { challengeId, jws }`. The record keeps the satisfied challenge (`stepUp: true`).

## Events

| Event | When | `data.object` |
| --- | --- | --- |
| `tax_authorisation.granted` | A user authorised FinBaze | `{ companyId, taxes, channel, stepUp, at }` |
| `tax_authorisation.revoked` | A revoke wrote | the same; `channel` is `embed`, `headless`, `platform`, `admin` or `lifecycle` |
| `company.requirements.updated` | The requirements of a company changed | the company; `data.details.reason` is `tax_authorisation` |

No IP address or user agent is in a webhook; they are in the audit log. FinBaze sends the user nothing about a revoke itself: the message type `tax_authorisation.revoked` goes through your [message routing](/concepts/messages) (`partner_delivers` by default).

## Errors

`TAX_AUTHORISATION_REQUIRED` (a submit without consent), `TAX_AUTHORISATION_STATEMENT_OUTDATED`, `TAX_NOT_REGISTERED`, `STEP_UP_REQUIRED`, `FORBIDDEN_TOKEN_TYPE`, `FILING_DELEGATED_TO_FIRM`, `FIRM_NOT_AUTHORISED_FOR_TAX` and `FILER_MUST_BE_INTERMEDIARY`. See [errors](/reference/errors).


---

<!-- /concepts/working-with-accountants -->
# Working with accountants

How a company on your platform connects its accounting firm, what the firm can do, what it costs, and how the connection ends.

A company on your platform can work with an accounting firm that uses FinBaze. The firm opens the company in its normal FinBaze dashboard (`/b/<firm>/…`) with the same tools it has for its other clients, **inside the features that are effective for that company**. There are no firm services, no reselling and no marketplace: a company connects one firm, by name, and can end it at any time.

|  |  |
| --- | --- |
| **Who pays** | You keep paying for the company (active companies). The firm pays nothing for it: no client seat, no filings-only fee, no per-document or AI usage. Usage by firm staff on the company is yours, as for your own users. |
| **What the firm sees** | Whatever the company's effective features allow. A module you hide for the company is hidden for the firm too, for reads and for changes. The firm cannot switch features on. Firm-installed apps and MCP access do not reach your companies. |
| **What the firm files** | Nothing, unless the company chooses taxes for it. For the taxes the company hands over, the firm files with its **BECON number** and FinBaze no longer files those. All other taxes stay with FinBaze, which files as a software supplier without a BECON number (see [filing consent](/concepts/filing-consent)). Requests only an intermediary may make, such as the corporate income tax extension, need a connected firm with a BECON number. |
| **Whose users** | The firm's staff are normal FinBaze accounts. They never become your platform users, and your users never get firm permissions. |

## Connecting

There are two ways. Both end in the same engagement, and both need the company to confirm a statement that names the firm, what it can see and do, the taxes it files, the billing rule and how to end.

**1. The company invites its firm** (the `accountant-connect` component).

1. A company admin enters the firm's KvK number or its connect code. `lookupFirmForConnect` returns the firm for an exact match only: there is no directory to browse. Lookups are limited to 10 an hour per company.
2. The admin picks the taxes the firm may file (none means bookkeeping access only), reads the statement (`firmEngagementStatement`) and confirms it. A firm without a BECON number can only get bookkeeping access (`FIRM_HAS_NO_BECON`).
3. `requestFirmConnection` stores the invitation. The firm sees it in its dashboard under *Clients, Invites, Requests from companies*, and gets an email. It accepts or declines; a request nobody answers expires after 14 days.

**2. The firm asks for access.** A firm admin enters the company's KvK number (and optionally a contact email and a message) in its dashboard. FinBaze sends a request to **every** platform company with that number whose platform has accountant connections on. The firm is never told whether a company matched, which platform it is on, or whether it was declined: `requestCompanyAccess` always answers `true`, and the firm's list says *waiting*, *connected* or *closed*.

You learn about a request when it arrives: the webhook `firm.access_requested` and the message `firm.access_requested` (routed like any notification, by default delivered by you). The company sees it in the `notification-banner` and approves or declines it in `accountant-connect`, choosing the taxes.

```ts
// Mount the component; the company does the rest.
<FinBazeAccountantConnect
  onFirmConnected={({ firmId }) => refresh()}
  onFirmDisconnected={({ firmId }) => refresh()}
/>
```

Create the session with `components: { accountantConnect: { enabled: true } }`. Its component features are `invite`, `approve` and `end`; switch one off and that button and its operation are gone for the session. The consent steps need an `embed` or `headless` token of a company **admin**; a backend-minted `platform_user` token gets `FORBIDDEN_TOKEN_TYPE`, and your server token cannot consent for a company.

## Reading the state

```graphql
query { companyFirmEngagements(companyId: "…", includeEnded: false) {
  id status origin taxes filingAuthority requestedAt expiresAt endsAt
  firm { id name hasBecon }
} }
```

With the SDK: `platform.firms.listEngagements(companyId)`. A server token needs the scope `platform_firms:read`.

## `firm_access` and ending a connection

Accountant connections are the feature key `firm_access`, which FinBaze puts in your allowance and you may limit per company or for the whole platform like any limitable key (see [allowance and limits](/concepts/feature-allowance-and-limits)).

- **Hide it:** no new connections or requests. Companies with an active firm get a **notice** (default 30 days): you receive `firm.disconnect_scheduled`, the company and the firm get a message, and the engagement ends at the set time (`endedBySide: platform`, reason `firm_access_hidden`). Show the key again before then and the notice is cancelled.
- **End it yourself** with `platform.firms.end(engagementId, { reason })` (scope `platform_firms:write`). A platform may only use the reasons `firm_access_hidden`, `company_closed`, `company_transferred` and `platform_request`; the last is logged and both sides are told.
- **Either side** can end it any time: the company admin in `accountant-connect`, a firm admin in the dashboard, FinBaze staff.

Ending is one transaction: the firm loses access on the next request; its BECON is no longer used for the company; its HMRC client authorisations for the company are cancelled (HMRC's side cannot be removed through the API, so the firm and the company are told to remove the relationship there); its open document requests are closed; the company's drafts and books stay. From then on FinBaze files the taxes the firm used to file, once the company's consent exists. You receive `firm.disconnected`.

## Events

| Event | When |
| --- | --- |
| `firm.access_requested` | A firm asked for access to a company. |
| `firm.connection_requested` | The company invited a firm; the firm has not answered. |
| `firm.connected` | The firm now works the company. |
| `firm.connection_declined` | A request was declined or withdrawn. |
| `firm.connection_expired` | A request expired after 14 days. |
| `firm.disconnect_scheduled` | The engagement ends at `endsAt` because `firm_access` was hidden. |
| `firm.disconnected` | The engagement ended. |
| `firm.authority_changed` | The company changed which taxes the firm files. |

`data.object` is the engagement: `id`, `companyId`, `firmId`, `firmName`, `origin`, `status`, `filingAuthority`, `taxes`, `expiresAt`, and for some events `endedBySide`, `reason`, `endsAt`, `previousTaxes`. No email address is ever in an event.

## Error codes

| Code | Meaning |
| --- | --- |
| `FIRM_ACCESS_DISABLED` | `firm_access` is hidden for the company. |
| `FIRM_NOT_FOUND` | No such firm. |
| `FIRM_HAS_NO_BECON` | Taxes chosen, but the firm has no BECON number. |
| `FIRM_ENGAGEMENT_STATEMENT_OUTDATED` | The statement changed since it was shown; read it again. |
| `ENGAGEMENT_NOT_PENDING` | The request was already answered or expired. |
| `FORBIDDEN_TOKEN_TYPE` | Consent needs an embed or headless token. |
| `COMPANY_ADMIN_REQUIRED` / `FIRM_ADMIN_REQUIRED` | The person lacks the role. |
| `PLATFORM_END_REASON_NOT_ALLOWED` | A platform ended it with a reason that is not in its list. |
| `FIRM_LOOKUP_RATE_LIMITED` | Too many lookups or requests. |
| `PLATFORM_COMPANY_USE_ENGAGEMENT` | A firm tried to connect a platform company through an invite link, onboarding or `createClient`. |


---

<!-- /concepts/policies-and-extensions -->
# Policies and extensions

The rules FinBaze runs by for your companies, and how you extend FinBaze screens: custom actions, links, fields and field control.

## Policies

A **policy** is a versioned setting for all your companies, with an override per company. Kinds: `category_mapping` (including MCC codes), `chart_template`, `booking_rules`, `filing_policy`, `roles_mapping`, `company_defaults` (including optional modules), `quotas`, `messaging` and `documents`.

You write a **draft**, FinBaze validates it against the kind's schema (`platform.policies.schemas()`), and **activating** it makes it live and archives the previous version. A company override applies on top of the platform policy; `effective` shows the result.

```ts
const draft = await finbaze.platform.policies.createDraft("quotas", { aiRunsPerMonth: 200 });
await finbaze.platform.policies.activate(draft.id);

await finbaze.platform.policies.overrides.set(companyId, "quotas", { aiRunsPerMonth: 20 });
const effective = await finbaze.platform.policies.effective("quotas", companyId);
```

### Sandbox to production

Configure in the sandbox, then promote with one action. In the sandbox `bundle.export` signs a bundle of the active policies; in production you `preview` it (a diff per kind plus warnings) and `confirm` the import, which activates every kind in one transaction.

```ts
const bundleId = await sandbox.platform.policies.bundle.export(); // all kinds, or pass a list
const preview = await live.platform.policies.bundle.preview(bundleId);
if (preview.warnings.length === 0) await live.platform.policies.bundle.confirm(preview.importId);
```

Filing policy produces `tax.deadline_upcoming` messages and can require roles to prepare and approve a filing. `quota.reached` is sent once a month when a quota is used up, and `policy.activated` when a version goes live.

## Extensions

**Custom actions** add buttons next to FinBaze's own on a booking, an invoice or a transaction. A click either calls your embed callback or sends `custom_action.invoked` to your endpoints. **Slots** are named places on a screen where you put items. **Link templates** turn a FinBaze object into a link in your own app ("Open shipment in TMS"), and `linkTemplates.resolve` returns the resolved links; the host of every link must be one of your allowed origins.

```ts
const ext = finbaze.platform.extensions;
await ext.linkTemplates.upsert({
  resourceType: "sales_invoice",
  urlTemplate: "https://tms.example.com/shipments/{externalId}",
  label: { en: "Open shipment", nl: "Open zending" },
});
await ext.customActions.upsert({
  key: "open_tms",
  label: { en: "Open in TMS" },
  placements: ["sales_invoice"],
  contextType: "sales_invoice",
});
```

**Custom fields** add your own typed fields to invoices, transactions, relations and projects (feature `extensions.custom_fields`). They show in the embedded views, can be included in events (`custom_fields`) and on documents, and are written with `customFields.setValues`; only the keys you pass change.

**Field control** hides, locks or presets a field of a FinBaze view, for all your companies or one. Fields the law requires on a document cannot be controlled. A write to a locked field fails with `FIELD_LOCKED`.

```ts
await ext.customFields.define({ entityType: "sales_invoice", key: "shipment", label: { en: "Shipment" }, type: "text" });
await ext.fieldControl.set({ view: "invoice", field: "reference", mode: "locked" });
```


---

<!-- /concepts/documents-and-rendering -->
# Documents and rendering

Your branding on invoices, quotes, reminders and payslips: layout presets, templates, documents you render yourself, fonts and custom domains.

FinBaze files and keeps the official copy of every invoice, quote, reminder, payslip and year document. You decide how it looks, at one of three levels per document type (`platform.documentRendering.settings.set`):

| Mode | What renders |
| --- | --- |
| `finbaze_layout` | FinBaze's layout with your **preset**: colours, fonts, logo, blocks. |
| `template` | Your logic-less HTML **template**, rendered by FinBaze in an isolated renderer. |
| `partner` | **You** render the PDF; FinBaze stores it as the official copy. |

Whatever the level, the required content (VAT number, address, invoice number, reverse-charge text and so on) is checked. Rules the tax adviser has not yet confirmed produce warnings; the others refuse activation or reject your PDF, and FinBaze then falls back to its own layout.

## Presets and fonts

```ts
const { platform } = finbaze;
const layout = await platform.documentLayouts.save({
  documentType: "invoice",
  name: "Acme classic",
  layout: { /* blocks, theme */ },
  companyEditable: "unlocked_blocks",
});
const problems = await platform.documentLayouts.validate("invoice", layout.layout);
await platform.documentLayouts.activate(layout.id, { makeDefault: true });
await platform.documentFonts.upload({ woff2, family: "Acme Sans", weight: 400, attest: true });
```

A preset can let a company choose between several (`documentLayouts.choose`) or edit unlocked blocks. A company that picked a preset follows its new versions. Presets travel with the `documents` policy when you promote from the sandbox.

## Templates

Templates use a small logic-less language (placeholders, loops and conditions over the document's data model) with CSS and small images. Scripts, iframes, remote images, `@import` and SVG with script are refused. `validate` renders twelve fixtures and checks the required content; `activate` only works after a pass.

```ts
const t = await platform.documentTemplates.save({ documentType: "invoice", name: "Acme", source: html, css });
const checked = await platform.documentTemplates.validate(t.id); // checked.validationReport lists failures
await platform.documentTemplates.activate(checked.id, { makeDefault: true });
```

## Rendering it yourself

With mode `partner`, FinBaze sends `document.render_requested` with the data model (never a BSN), a deadline and signed links to attachments such as the invoice UBL. Render the PDF and answer before the deadline:

```ts
if (event.type === "document.render_requested") {
  const { job, dataModel } = event.data.object;
  const pdf = await renderInvoice(dataModel);
  const { uploadId } = await finbaze.platform.documentRendering.upload(pdf); // up to 10 MB, valid for an hour
  await finbaze.platform.documentRendering.attach(job, { uploadId }); // or { pdfBase64 } for small files
}
```

FinBaze scans the PDF (no scripts or embedded files) and checks its text against the document's facts. Emails and payment pages wait for the job to settle; on a rejection, a timeout or no answer FinBaze renders its own layout. Events: `document.render_requested`, `document.render_rejected`, `document.render_failed`, `document.official_copy_created`.

## Custom domains

Invoice, quote and payment pages can live on your own domain: `customDomains.add("pay.acme.nl")`, create the CNAME and TXT records it returns, and `check`. FinBaze issues the certificate; `custom_domain.status_changed` follows the status. A company is only served on its own platform's domains.


---

<!-- /concepts/support-and-view-as -->
# Support and view-as

Route your users' support requests, escalate to FinBaze, and decide when FinBaze staff may look at a company.

Two things live here: how a support request from one of your users is handled (you first, or FinBaze directly), and the rule that FinBaze staff can open one of your companies only with the company's consent.

## Who answers your users

The embedded `contact-support` element is the "Contact support" button. What it does depends on `supportMode`, which you set per platform in the portal (Support) or with `platform.support.settings.update`:

| `supportMode` | What the button does |
| --- | --- |
| `partner_first` (default) | Tells your page (`support.requested` event) and your backend (webhook `support.requested`). You answer, and escalate to FinBaze through the API when you need to. If your page has no handler and you set a `supportUrl`, the SDK opens it. |
| `finbaze_direct` | Opens FinBaze's form. The case becomes an escalation (`source: user`) for FinBaze support, with the request ids attached. |

The event data is `{ companyId, screen, requestIds, componentVersion }`: `requestIds` are the `X-Request-Id` values of the last (up to five) failed calls of that page, so you or FinBaze can find them in the logs and the audit log. Every API response carries an `X-Request-Id` header (send your own, 8 to 64 characters of `A-Z a-z 0-9 . _ -`, and it is kept), embed errors carry it as `requestId`, and the audit log stores it.

```ts
const instance = await loadFinBaze(publishableKey, { fetchClientSecret });
const help = instance.create("contact-support", { screen: "vat-return" });
help.on("support.requested", ({ companyId, requestIds }) => openMyHelpWidget(companyId, requestIds));
help.mount("#help");
```

Settings: `supportMode`, `supportUrl` (https), `supportEmail` and `supportEscalationEnabled` (default `true`; `false` makes `createSupportEscalation` fail with `SUPPORT_ESCALATION_DISABLED`).

## Escalating to FinBaze

Level 2 is FinBaze. With your server key (scope `support:write`):

```ts
const escalation = await finbaze.platform.support.escalations.create({
  companyId, subject: "VAT draft starts a quarter late",
  description: "Since this morning ...", severity: "high",
  requestIds: ["7b0c2f1e-..."], screen: "vat-return",
});
await finbaze.platform.support.escalations.comment(escalation.id, "Request 7b0c2f1e is the first failing one.");
const open = await finbaze.platform.support.escalations.list({ status: ["open", "in_progress"] });
```

FinBaze support is mailed (there is no helpdesk integration yet) and works the case in an admin list. Statuses: `open`, `in_progress`, `waiting_on_platform`, `resolved`, `closed`. Your comment on a case that waits for you or is resolved reopens it. Events: `support.escalation.created` and `support.escalation.updated` (`data.object.change` is `status`, `severity` or `comment`). Which member of staff handles it is not shared.

## Consented view-as

FinBaze staff used to open any company. For a company on your platform they now need a **support access grant**:

1. Staff ask in the admin console: a reason, `read` or `read_write`, a duration (default 4 hours, at most 72) and optionally the escalation. You get the event `support.access_requested`, and the company's admins see the request in the `notification-banner` (approve or decline in place) and in the `support-access` element.
2. A company **admin** approves or declines, in the element or banner (an embed or headless token; if your `step_up` provider lists `support_access.approve`, the admin confirms first). Or your backend decides for them with `platform.support.grants.decide(grantId, { approve: true, attestation: "…" })`; a server token must say how it obtained the consent (`attestation`, at least 10 characters), which is recorded. A token your backend minted for a user cannot consent.
3. The grant is `active` until `expiresAt` (`support.access_granted`). The company or you can end it any time with `platform.support.grants.revoke(grantId)` (`support.access_revoked`); expiry is `support.access_expired`. Expiry and revocation take effect on the next request.

```ts
const grants = await finbaze.platform.support.grants.list(companyId);          // requested and active
await finbaze.platform.support.grants.decide(grants[0].id, { approve: true, attestation: "Customer agreed on ticket #4411" });
await finbaze.platform.support.grants.revoke(grants[0].id);
```

What a grant allows:

|  | `read` | `read_write` |
| --- | --- | --- |
| View the company's books, filings and settings | yes | yes |
| Change data (invoices, relations, settings) | no (`SUPPORT_GRANT_READ_ONLY`) | yes |
| Submit filings, give or withdraw filing consent, decide firm connections, move the company, decide on support access | never (`SUPPORT_GRANT_DENIED_OPERATION`) | never |

Without a grant, staff cannot open the company at all (`SUPPORT_GRANT_REQUIRED`); direct FinBaze companies are not affected. Everything staff do under a grant is audited as actor kind `support` with the grant id and shows in `platform.audit.list` (reads too). The platform and the company never see a staff member's name, only "FinBaze support" and the reason.

## Break-glass

For a legal order or a security incident FinBaze can open a company **without** consent: one FinBaze admin requests it with a written reason and a **second** admin approves. It is read only, lasts two hours at most and you receive `support.break_glass` the moment it starts. Staff cannot approve their own request.

## Errors and events

Errors: `SUPPORT_GRANT_REQUIRED`, `SUPPORT_GRANT_READ_ONLY`, `SUPPORT_GRANT_DENIED_OPERATION`, `SUPPORT_GRANT_NOT_PENDING`, `SUPPORT_GRANT_NOT_ACTIVE`, `SUPPORT_ATTESTATION_REQUIRED`, `SUPPORT_COMPANY_ADMIN_REQUIRED`, `SUPPORT_ESCALATION_DISABLED`.

Events: `support.requested`, `support.escalation.created`, `support.escalation.updated`, `support.access_requested`, `support.access_granted`, `support.access_revoked`, `support.access_expired`, `support.break_glass`. Their `data.object` JSON Schemas are in the event catalogue.

Scopes: `support:read` and `support:write`. The `support-access` element has the features `decide` and `revoke`; `notification-banner` has `supportApproval`. Each can be switched off per session, in which case that control is not shown.


---

<!-- /components -->
# Components overview

Nineteen embeddable views and elements, and how they work.

A component is a piece of FinBaze UI that runs in an iframe on FinBaze's origin and talks to your page through the SDK. **Views** fill their container (a tax calendar, a VAT return). **Elements** are small inline pieces (a chip, a button) you place next to your own UI.

| Component | Kind |
| --- | --- |
| [`onboarding`](/components/onboarding), [`tax-authorisation`](/components/tax-authorisation) | view |
| [`notification-banner`](/components/notification-banner), [`action-centre`](/components/action-centre) | view |
| [`transactions`](/components/transactions), [`transaction-detail`](/components/transaction-detail), [`purchase-inbox`](/components/purchase-inbox) | view |
| [`tax-calendar`](/components/tax-calendar), [`vat-return`](/components/vat-return), [`icp-return`](/components/icp-return), [`oss-return`](/components/oss-return), [`tax-payments`](/components/tax-payments) | view |
| [`accountant-connect`](/components/accountant-connect), [`support-access`](/components/support-access) | view |
| [`booking-chip`](/components/booking-chip), [`receipt-button`](/components/receipt-button), [`tax-due-chip`](/components/tax-due-chip), [`company-transfer`](/components/company-transfer), [`contact-support`](/components/contact-support) | element |

## Lifecycle

1. `loadFinBaze(publishableKey, { fetchClientSecret })` loads the controller (or `<FinBazeProvider>` in React).
2. `instance.create("tax-calendar", options)` returns a component; `component.mount(target)` shows it.
3. The component emits events (`ready`, `navigate`, `error`, plus component events). Handle them with `component.on(...)` or React props.
4. `instance.update({ appearance, locale })` restyles everything live. `instance.logout()` drops the token when your user signs out; `instance.destroy()` removes everything.

## Navigation

By default components navigate inside themselves. Set `navigation: "external"` and every move is emitted as a `navigate` event with an intent, so your router can handle it. Return `component.navigate(intent)` to push a destination into a mounted component.

## Locales

`nl-NL`, `en-NL`, `en-GB`, `en-US`. Defaults to the company's language; override with `locale`.

## Try them

The [component gallery](/components/gallery) runs every component on seeded sandbox companies.


---

<!-- /components/appearance -->
# Appearance reference

Colours, fonts and radius: the variables you can set, and the rules they are checked against.

```ts
instance.update({
  appearance: {
    theme: "auto", // "light" | "dark" | "auto"
    variables: { colorPrimary: "#0a7d5a", borderRadius: "10px", fontFamily: "Inter, system-ui, sans-serif" },
    variablesDark: { colorBackground: "#10151c" },
    poweredBy: "subtle",
  },
});
```

| Variable | Type | Notes |
| --- | --- | --- |
| `colorPrimary`, `colorPrimaryText` | colour | Buttons and links, and the text on them |
| `colorBackground`, `colorText`, `colorTextSecondary` | colour | Surface and text |
| `colorDanger`, `colorBorder`, `colorRing` | colour | Errors, borders, focus ring |
| `fontFamily` | font stack | Up to 8 families, each a registered web font (Inter, Open Sans, Lato, Montserrat, Poppins, DM Sans, Manrope, Figtree, IBM Plex Sans, Source Sans 3, Merriweather, …) or a system/generic family (`system-ui`, `-apple-system`, `Segoe UI`, `Roboto`, `Arial`, `sans-serif`, …). Any other name is rejected. The components load no font files: a family shows where the viewer's device has it, so end the stack with a generic family |
| `fontSizeBase` | `14px`–`18px` |  |
| `borderRadius` | `0px`–`24px` |  |
| `spacingUnit` | `3px`–`6px` | Default `4px` |

`variablesDark` overrides `variables` in dark mode. `poweredBy: "hidden"` is only honoured if your contract allows it. `copy.companyNoun` switches "company" to "business".

## Safety

There is no free CSS. Colours are parsed strictly (hex, `rgb()`, `hsl()`, `oklch()` and named colours) and applied as custom properties; anything else is rejected with a warning in the console. Text and background pairs that fail contrast are corrected so the component stays readable.


---

<!-- /components/reference -->
# Component props at a glance

Every component: kind, session key, requirements, features, options and events, generated from the registry.

Generated from the component registry (80 components). Each name links to its page.

| Component | Kind | Session key | Requires | Features (default) | Options | Events |
| --- | --- | --- | --- | --- | --- | --- |
| [`onboarding`](/components/onboarding) | view | `onboarding` | none | `editCompany` (on), `taxSetup` (on), `filingConsent` (on) | `collect` | `ready`, `navigate`, `error`, `tax_authorisation.granted`, `onboarding.step_completed`, `onboarding.completed` |
| [`tax-authorisation`](/components/tax-authorisation) | view | `taxAuthorisation` | `tax_filings` | `revoke` (on), `hmrcConnect` (on), `grant` (on) | `taxes` | `ready`, `navigate`, `error`, `tax_authorisation.granted`, `tax_authorisation.revoked`, `hmrc.connected` |
| [`notification-banner`](/components/notification-banner) | view | `notificationBanner` | none | `supportApproval` (on) | `dismissible` | `ready`, `navigate`, `error`, `dismissed`, `support.access.approved`, `support.access.declined` |
| [`action-centre`](/components/action-centre) | view | `actionCentre` | none | none | `types`, `limit` | `ready`, `navigate`, `error`, `action.selected` |
| [`transactions`](/components/transactions) | view | `transactions` | `banking` | `categorise` (on), `split` (on), `attachReceipt` (on), `matchInvoices` (on), `aiSuggestions` (on) | `bankAccountId`, `filter` | `ready`, `navigate`, `error`, `transaction.categorised`, `receipt.attached` |
| [`transaction-detail`](/components/transaction-detail) | view | `transactionDetail` | `banking` | `categorise` (on), `split` (on), `attachReceipt` (on), `matchInvoices` (on), `aiSuggestions` (on) | `transactionId`, `bankAccountId + externalId` | `ready`, `navigate`, `error`, `transaction.categorised`, `receipt.attached` |
| [`purchase-inbox`](/components/purchase-inbox) | view | `purchaseInbox` | `process_documents` | `upload` (on), `approve` (on), `emailForwarding` (on) | `tab` | `ready`, `navigate`, `error`, `document.uploaded`, `document.processed` |
| [`tax-calendar`](/components/tax-calendar) | view | `taxCalendar` | `tax_filings` | none | `year` | `ready`, `navigate`, `error`, `filing.selected` |
| [`vat-return`](/components/vat-return) | view | `vatReturn` | `tax_filings` | `submit` (on), `payment` (on), `suppletie` (on), `inlineConsent` (on) | `period`, `filingId` | `ready`, `navigate`, `error`, `filing.submitted`, `payment.requested`, `tax_authorisation.granted` |
| [`icp-return`](/components/icp-return) | view | `icpReturn` | `tax_filings`, `icp_filing` | `submit` (on), `inlineConsent` (on) | `period`, `filingId` | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`oss-return`](/components/oss-return) | view | `ossReturn` | `tax_filings`, `one_stop_shop_filing` | `submit` (on), `inlineConsent` (on) | `period`, `filingId` | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`tax-payments`](/components/tax-payments) | view | `taxPayments` | `tax_filings` | `paymentHandoff` (on), `internetkassa` (off) | common only | `ready`, `navigate`, `error`, `payment.requested` |
| [`booking-chip`](/components/booking-chip) | element | `bookingChip` | `banking` | `edit` (on) | `transactionId | bankAccountId + externalId`, `size` |
| [`receipt-button`](/components/receipt-button) | element | `receiptButton` | `banking`, `process_documents` | none | `transactionId | bankAccountId + externalId`, `label`, `variant` |
| [`tax-due-chip`](/components/tax-due-chip) | element | `taxDueChip` | `tax_filings` | none | `taxes`, `onClick` | `ready`, `navigate`, `error`, `click` |
| [`accountant-connect`](/components/accountant-connect) | view | `accountantConnect` | `firm_access` | `invite` (on), `approve` (on), `end` (on) | common only | `ready`, `navigate`, `error`, `firm.connected`, `firm.disconnected` |
| [`company-transfer`](/components/company-transfer) | element | `companyTransfer` | none | none | common only | `ready`, `navigate`, `error`, `company.transfer.created`, `company.transfer.cancelled` |
| [`contact-support`](/components/contact-support) | element | `contactSupport` | none | none | `screen`, `label` | `ready`, `navigate`, `error`, `support.requested`, `support.escalation.created` |
| [`support-access`](/components/support-access) | view | `supportAccess` | none | `decide` (on), `revoke` (on) | common only | `ready`, `navigate`, `error`, `support.access.approved`, `support.access.declined`, `support.access.revoked` |
| [`company-settings`](/components/company-settings) | view | `companySettings` | none | `editCompany` (on), `financialYears` (on) | `tab` | `ready`, `navigate`, `error`, `company.updated` |
| [`bank-connections`](/components/bank-connections) | view | `bankConnections` | `lunchflow_accounts` | `connect` (on), `disconnect` (on) | common only | `ready`, `navigate`, `error`, `bank_connection.connected`, `bank_connection.disconnected` |
| [`users-and-access`](/components/users-and-access) | view | `usersAndAccess` | none | `invite` (on), `changeRole` (on), `remove` (on) | common only | `ready`, `navigate`, `error`, `user.invite_requested`, `user.role_change_requested`, `user.removal_requested` |
| [`data-export`](/components/data-export) | view | `dataExport` | none | `request` (on) | common only | `ready`, `navigate`, `error`, `export.requested` |
| [`dashboard`](/components/dashboard) | view | `dashboard` | none | none | `period`, `granularity` | `ready`, `navigate`, `error`, `click` |
| [`insights`](/components/insights) | view | `insights` | none | none | `tab` | `ready`, `navigate`, `error` |
| [`bank-rules`](/components/bank-rules) | view | `bankRules` | `banking` | `create` (on), `edit` (on), `delete` (on), `apply` (on) | common only | `ready`, `navigate`, `error`, `bank_rule.created`, `bank_rule.updated`, `bank_rule.deleted` |
| [`reconciliation`](/components/reconciliation) | view | `reconciliation` | `banking` | none | `accountId`, `period` | `ready`, `navigate`, `error`, `reconciliation.day_selected` |
| [`payment-batches`](/components/payment-batches) | view | `paymentBatches` | `payment_batches` | `requestPayment` (on) | `batchId` | `ready`, `navigate`, `error`, `payment.requested`, `payment_batch.selected` |
| [`sales-invoices`](/components/sales-invoices) | view | `salesInvoices` | `sales_invoices` | `create` (on), `send` (on), `credit` (on), `export` (on) | `status`, `invoiceId`, `customerId` | `ready`, `navigate`, `error`, `invoice.sent`, `invoice.credited`, `invoice.selected` |
| [`invoice-editor`](/components/invoice-editor) | view | `invoiceEditor` | `sales_invoices` | `save` (on), `send` (on) | `invoiceId`, `externalId`, `prefill` | `ready`, `navigate`, `error`, `invoice.created`, `invoice.sent` |
| [`quotes`](/components/quotes) | view | `quotes` | `quotes` | `send` (on), `convert` (on) | `quoteId` | `ready`, `navigate`, `error`, `quote.sent`, `quote.converted`, `quote.selected` |
| [`recurring-invoices`](/components/recurring-invoices) | view | `recurringInvoices` | `subscription_invoices` | `activate` (on) | `recurringId` | `ready`, `navigate`, `error`, `recurring_invoice.activated`, `recurring_invoice.selected` |
| [`customers`](/components/customers) | view | `customers` | `relations` | `create` (on), `edit` (on) | `customerId` | `ready`, `navigate`, `error`, `customer.created`, `customer.updated`, `customer.selected` |
| [`products`](/components/products) | view | `products` | `products` | none | `productId` | `ready`, `navigate`, `error`, `product.selected` |
| [`reminders`](/components/reminders) | view | `reminders` | `reminders` | `send` (on), `close` (on) | `reminderId` | `ready`, `navigate`, `error`, `reminder.sent`, `reminder.closed`, `reminder.selected` |
| [`purchase-invoices`](/components/purchase-invoices) | view | `purchaseInvoices` | `purchase_invoices` | `confirm` (on) | `invoiceId` | `ready`, `navigate`, `error`, `purchase_invoice.confirmed`, `purchase_invoice.selected` |
| [`suppliers`](/components/suppliers) | view | `suppliers` | `relations` | `create` (on), `edit` (on) | `supplierId` | `ready`, `navigate`, `error`, `supplier.created`, `supplier.updated`, `supplier.selected` |
| [`document-requests`](/components/document-requests) | view | `documentRequests` | `document_requests` | `respond` (on), `upload` (on) | `requestId` | `ready`, `navigate`, `error`, `document_request.answered` |
| [`reports`](/components/reports) | view | `reports` | none | `export` (on) | `type`, `period`, `granularity` | `ready`, `navigate`, `error`, `report.opened` |
| [`general-ledger`](/components/general-ledger) | view | `generalLedger` | none | none | `period`, `granularity`, `ledgerCode` | `ready`, `navigate`, `error`, `ledger_account.selected` |
| [`journal`](/components/journal) | view | `journal` | `settlements` | `create` (on), `delete` (off) | `entryId` | `ready`, `navigate`, `error`, `journal_entry.created`, `journal_entry.deleted`, `journal_entry.selected` |
| [`assets`](/components/assets) | view | `assets` | `assets` | none | `assetId` | `ready`, `navigate`, `error`, `asset.selected` |
| [`loans`](/components/loans) | view | `loans` | `loans` | none | `loanId` | `ready`, `navigate`, `error`, `loan.selected` |
| [`vehicles`](/components/vehicles) | view | `vehicles` | `vehicles` | `create` (on) | common only | `ready`, `navigate`, `error`, `vehicle.created` |
| [`projects`](/components/projects) | view | `projects` | `projects` | none | `projectId` | `ready`, `navigate`, `error`, `project.selected` |
| [`cost-centers`](/components/cost-centers) | view | `costCenters` | `cost_centers` | `create` (on), `edit` (on) | common only | `ready`, `navigate`, `error`, `cost_center.created`, `cost_center.updated` |
| [`year-end`](/components/year-end) | view | `yearEnd` | none | `close` (on) | `yearId` | `ready`, `navigate`, `error`, `financial_year.closed` |
| [`annual-accounts`](/components/annual-accounts) | view | `annualAccounts` | `tax_filings`, `annual_accounts` | `edit` (on), `approve` (on), `submit` (on), `inlineConsent` (on) | `dossierId` | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`cit-return`](/components/cit-return) | view | `citReturn` | `tax_filings`, `corporate_income_tax` | `submit` (on), `inlineConsent` (on) | common only | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`uk-itsa`](/components/uk-itsa) | view | `ukItsa` | `tax_filings`, `uk_itsa` | `prepare` (on), `submit` (on), `inlineConsent` (on), `hmrcConnect` (on) | `filingId` | `ready`, `navigate`, `error`, `filing.submitted`, `hmrc.connected` |
| [`us-1120`](/components/us-1120) | view | `us1120` | `tax_filings`, `us_federal_tax` | `prepare` (on), `export` (on) | `filingId` | `ready`, `navigate`, `error`, `filing.prepared` |
| [`employees`](/components/employees) | view | `employees` | `payroll` | `create` (on), `edit` (on) | `employeeId` | `ready`, `navigate`, `error`, `employee.created`, `employee.updated`, `employee.selected` |
| [`pay-runs`](/components/pay-runs) | view | `payRuns` | `payroll` | `create` (on), `calculate` (on), `approve` (on), `finalise` (on), `paymentHandoff` (on), `filings` (on) | `payRunId` | `ready`, `navigate`, `error`, `pay_run.created`, `pay_run.approved`, `pay_run.selected`, `payment.requested` |
| [`payslip-viewer`](/components/payslip-viewer) | view | `payslipViewer` | `payroll`, `employee_self_service` | `download` (on), `yearDocuments` (on) | common only | `ready`, `navigate`, `error`, `payslip.opened`, `payslip.downloaded` |
| [`payroll-filings`](/components/payroll-filings) | view | `payrollFilings` | `payroll`, `submit_tax_filings` | `prepare` (on), `submit` (on), `inlineConsent` (on) | `filingId`, `type` | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`assistant`](/components/assistant) | view | `assistant` | `ai_assistant`, `ai_chat` | none | common only | `ready`, `navigate`, `error`, `assistant.message` |
| [`agent-tasks`](/components/agent-tasks) | view | `agentTasks` | `ai.agents` | `approve` (on), `create` (on), `manage` (on) | `taskId` | `ready`, `navigate`, `error`, `agent_task.approved`, `agent_task.rejected`, `agent_task.selected` |
| [`automations`](/components/automations) | view | `automations` | `automations` | `toggle` (on), `edit` (on) | common only | `ready`, `navigate`, `error`, `automation.updated` |
| [`suite`](/components/suite) | view | `suite` | none | none | `initialRoute`, `route` | `ready`, `navigate`, `error` |
| [`receipt-dropzone`](/components/receipt-dropzone) | element | `receiptDropzone` | `process_documents` | none | `transactionId`, `bankAccountId`, `transactionExternalId`, `accept` | `ready`, `navigate`, `error`, `receipt.uploaded`, `receipt.matched` |
| [`category-picker`](/components/category-picker) | element | `categoryPicker` | none | none | `value`, `kind`, `name`, `label`, `disabled` | `ready`, `navigate`, `error`, `change` |
| [`ledger-account-picker`](/components/ledger-account-picker) | element | `ledgerAccountPicker` | none | none | `value`, `kinds`, `label`, `disabled` | `ready`, `navigate`, `error`, `change` |
| [`vat-code-picker`](/components/vat-code-picker) | element | `vatCodePicker` | none | none | `value`, `direction`, `country`, `label`, `disabled` | `ready`, `navigate`, `error`, `change` |
| [`invoice-status-badge`](/components/invoice-status-badge) | element | `invoiceStatusBadge` | `sales_invoices` | none | `invoiceId` | `ready`, `navigate`, `error`, `click` |
| [`invoice-pdf-preview`](/components/invoice-pdf-preview) | element | `invoicePdfPreview` | `sales_invoices` | none | `invoiceId` | `ready`, `navigate`, `error` |
| [`file-now-button`](/components/file-now-button) | element | `fileNowButton` | `tax_filings` | none | common only | `ready`, `navigate`, `error`, `opened` |
| [`vat-reservation-meter`](/components/vat-reservation-meter) | element | `vatReservationMeter` | `delegated.tax_reservation` | none | `targetAccountExternalId` | `ready`, `navigate`, `error`, `reserve.requested` |
| [`profit-tile`](/components/profit-tile) | element | `profitTile` | none | none | `period`, `granularity` | `ready`, `navigate`, `error`, `click` |
| [`revenue-tile`](/components/revenue-tile) | element | `revenueTile` | none | none | `period`, `granularity` | `ready`, `navigate`, `error`, `click` |
| [`cash-runway-tile`](/components/cash-runway-tile) | element | `cashRunwayTile` | none | none | common only | `ready`, `navigate`, `error`, `click` |
| [`period-picker`](/components/period-picker) | element | `periodPicker` | none | none | `period`, `granularity`, `granularities` | `ready`, `navigate`, `error`, `change` |
| [`customer-picker`](/components/customer-picker) | element | `customerPicker` | `relations` | none | `value`, `label`, `disabled` | `ready`, `navigate`, `error`, `change` |
| [`product-tax-code-picker`](/components/product-tax-code-picker) | element | `productTaxCodePicker` | `products` | none | `value`, `country`, `label`, `disabled` | `ready`, `navigate`, `error`, `change` |
| [`requirements-checklist`](/components/requirements-checklist) | element | `requirementsChecklist` | none | none | common only | `ready`, `navigate`, `error`, `requirement.completed` |
| [`onboarding-progress`](/components/onboarding-progress) | element | `onboardingProgress` | none | none | common only | `ready`, `navigate`, `error`, `requirement.completed` |
| [`company-search`](/components/company-search) | element | `companySearch` | none | none | `country`, `label`, `disabled` | `ready`, `navigate`, `error`, `select` |
| [`approval-button`](/components/approval-button) | element | `approvalButton` | `ai.agents` | none | `approvalId` | `ready`, `navigate`, `error`, `approved`, `rejected` |
| [`accountant-badge`](/components/accountant-badge) | element | `accountantBadge` | `firm_access` | none | common only | `ready`, `navigate`, `error` |
| [`engagement-card`](/components/engagement-card) | element | `engagementCard` | `firm_access` | `end` (on) | common only | `ready`, `navigate`, `error`, `engagement.ended` |
| [`feed-status`](/components/feed-status) | element | `feedStatus` | `banking` | none | `dataSourceId` | `ready`, `navigate`, `error`, `click` |

Every component also takes `appearance` and `navigation`, and emits `ready`, `navigate` and `error`.


---

<!-- /components/events -->
# Events reference

Every event each component emits, with the React prop that handles it.

Events are typed in `@finbaze/embed-js` (`ComponentEvents`). In React, `filing.submitted` becomes `onFilingSubmitted`.

| Component | Events |
| --- | --- |
| [`onboarding`](/components/onboarding) | `ready`, `navigate`, `error`, `tax_authorisation.granted`, `onboarding.step_completed`, `onboarding.completed` |
| [`tax-authorisation`](/components/tax-authorisation) | `ready`, `navigate`, `error`, `tax_authorisation.granted`, `tax_authorisation.revoked`, `hmrc.connected` |
| [`notification-banner`](/components/notification-banner) | `ready`, `navigate`, `error`, `dismissed`, `support.access.approved`, `support.access.declined` |
| [`action-centre`](/components/action-centre) | `ready`, `navigate`, `error`, `action.selected` |
| [`transactions`](/components/transactions) | `ready`, `navigate`, `error`, `transaction.categorised`, `receipt.attached` |
| [`transaction-detail`](/components/transaction-detail) | `ready`, `navigate`, `error`, `transaction.categorised`, `receipt.attached` |
| [`purchase-inbox`](/components/purchase-inbox) | `ready`, `navigate`, `error`, `document.uploaded`, `document.processed` |
| [`tax-calendar`](/components/tax-calendar) | `ready`, `navigate`, `error`, `filing.selected` |
| [`vat-return`](/components/vat-return) | `ready`, `navigate`, `error`, `filing.submitted`, `payment.requested`, `tax_authorisation.granted` |
| [`icp-return`](/components/icp-return) | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`oss-return`](/components/oss-return) | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`tax-payments`](/components/tax-payments) | `ready`, `navigate`, `error`, `payment.requested` |
| [`booking-chip`](/components/booking-chip) | `ready`, `navigate`, `error`, `booking.changed` |
| [`receipt-button`](/components/receipt-button) | `ready`, `navigate`, `error`, `receipt.attached` |
| [`tax-due-chip`](/components/tax-due-chip) | `ready`, `navigate`, `error`, `click` |
| [`accountant-connect`](/components/accountant-connect) | `ready`, `navigate`, `error`, `firm.connected`, `firm.disconnected` |
| [`company-transfer`](/components/company-transfer) | `ready`, `navigate`, `error`, `company.transfer.created`, `company.transfer.cancelled` |
| [`contact-support`](/components/contact-support) | `ready`, `navigate`, `error`, `support.requested`, `support.escalation.created` |
| [`support-access`](/components/support-access) | `ready`, `navigate`, `error`, `support.access.approved`, `support.access.declined`, `support.access.revoked` |
| [`company-settings`](/components/company-settings) | `ready`, `navigate`, `error`, `company.updated` |
| [`bank-connections`](/components/bank-connections) | `ready`, `navigate`, `error`, `bank_connection.connected`, `bank_connection.disconnected` |
| [`users-and-access`](/components/users-and-access) | `ready`, `navigate`, `error`, `user.invite_requested`, `user.role_change_requested`, `user.removal_requested` |
| [`data-export`](/components/data-export) | `ready`, `navigate`, `error`, `export.requested` |
| [`dashboard`](/components/dashboard) | `ready`, `navigate`, `error`, `click` |
| [`insights`](/components/insights) | `ready`, `navigate`, `error` |
| [`bank-rules`](/components/bank-rules) | `ready`, `navigate`, `error`, `bank_rule.created`, `bank_rule.updated`, `bank_rule.deleted` |
| [`reconciliation`](/components/reconciliation) | `ready`, `navigate`, `error`, `reconciliation.day_selected` |
| [`payment-batches`](/components/payment-batches) | `ready`, `navigate`, `error`, `payment.requested`, `payment_batch.selected` |
| [`sales-invoices`](/components/sales-invoices) | `ready`, `navigate`, `error`, `invoice.sent`, `invoice.credited`, `invoice.selected` |
| [`invoice-editor`](/components/invoice-editor) | `ready`, `navigate`, `error`, `invoice.created`, `invoice.sent` |
| [`quotes`](/components/quotes) | `ready`, `navigate`, `error`, `quote.sent`, `quote.converted`, `quote.selected` |
| [`recurring-invoices`](/components/recurring-invoices) | `ready`, `navigate`, `error`, `recurring_invoice.activated`, `recurring_invoice.selected` |
| [`customers`](/components/customers) | `ready`, `navigate`, `error`, `customer.created`, `customer.updated`, `customer.selected` |
| [`products`](/components/products) | `ready`, `navigate`, `error`, `product.selected` |
| [`reminders`](/components/reminders) | `ready`, `navigate`, `error`, `reminder.sent`, `reminder.closed`, `reminder.selected` |
| [`purchase-invoices`](/components/purchase-invoices) | `ready`, `navigate`, `error`, `purchase_invoice.confirmed`, `purchase_invoice.selected` |
| [`suppliers`](/components/suppliers) | `ready`, `navigate`, `error`, `supplier.created`, `supplier.updated`, `supplier.selected` |
| [`document-requests`](/components/document-requests) | `ready`, `navigate`, `error`, `document_request.answered` |
| [`reports`](/components/reports) | `ready`, `navigate`, `error`, `report.opened` |
| [`general-ledger`](/components/general-ledger) | `ready`, `navigate`, `error`, `ledger_account.selected` |
| [`journal`](/components/journal) | `ready`, `navigate`, `error`, `journal_entry.created`, `journal_entry.deleted`, `journal_entry.selected` |
| [`assets`](/components/assets) | `ready`, `navigate`, `error`, `asset.selected` |
| [`loans`](/components/loans) | `ready`, `navigate`, `error`, `loan.selected` |
| [`vehicles`](/components/vehicles) | `ready`, `navigate`, `error`, `vehicle.created` |
| [`projects`](/components/projects) | `ready`, `navigate`, `error`, `project.selected` |
| [`cost-centers`](/components/cost-centers) | `ready`, `navigate`, `error`, `cost_center.created`, `cost_center.updated` |
| [`year-end`](/components/year-end) | `ready`, `navigate`, `error`, `financial_year.closed` |
| [`annual-accounts`](/components/annual-accounts) | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`cit-return`](/components/cit-return) | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`uk-itsa`](/components/uk-itsa) | `ready`, `navigate`, `error`, `filing.submitted`, `hmrc.connected` |
| [`us-1120`](/components/us-1120) | `ready`, `navigate`, `error`, `filing.prepared` |
| [`employees`](/components/employees) | `ready`, `navigate`, `error`, `employee.created`, `employee.updated`, `employee.selected` |
| [`pay-runs`](/components/pay-runs) | `ready`, `navigate`, `error`, `pay_run.created`, `pay_run.approved`, `pay_run.selected`, `payment.requested` |
| [`payslip-viewer`](/components/payslip-viewer) | `ready`, `navigate`, `error`, `payslip.opened`, `payslip.downloaded` |
| [`payroll-filings`](/components/payroll-filings) | `ready`, `navigate`, `error`, `filing.submitted`, `tax_authorisation.granted` |
| [`assistant`](/components/assistant) | `ready`, `navigate`, `error`, `assistant.message` |
| [`agent-tasks`](/components/agent-tasks) | `ready`, `navigate`, `error`, `agent_task.approved`, `agent_task.rejected`, `agent_task.selected` |
| [`automations`](/components/automations) | `ready`, `navigate`, `error`, `automation.updated` |
| [`suite`](/components/suite) | `ready`, `navigate`, `error` |
| [`receipt-dropzone`](/components/receipt-dropzone) | `ready`, `navigate`, `error`, `receipt.uploaded`, `receipt.matched` |
| [`category-picker`](/components/category-picker) | `ready`, `navigate`, `error`, `change` |
| [`ledger-account-picker`](/components/ledger-account-picker) | `ready`, `navigate`, `error`, `change` |
| [`vat-code-picker`](/components/vat-code-picker) | `ready`, `navigate`, `error`, `change` |
| [`invoice-status-badge`](/components/invoice-status-badge) | `ready`, `navigate`, `error`, `click` |
| [`invoice-pdf-preview`](/components/invoice-pdf-preview) | `ready`, `navigate`, `error` |
| [`file-now-button`](/components/file-now-button) | `ready`, `navigate`, `error`, `opened` |
| [`vat-reservation-meter`](/components/vat-reservation-meter) | `ready`, `navigate`, `error`, `reserve.requested` |
| [`profit-tile`](/components/profit-tile) | `ready`, `navigate`, `error`, `click` |
| [`revenue-tile`](/components/revenue-tile) | `ready`, `navigate`, `error`, `click` |
| [`cash-runway-tile`](/components/cash-runway-tile) | `ready`, `navigate`, `error`, `click` |
| [`period-picker`](/components/period-picker) | `ready`, `navigate`, `error`, `change` |
| [`customer-picker`](/components/customer-picker) | `ready`, `navigate`, `error`, `change` |
| [`product-tax-code-picker`](/components/product-tax-code-picker) | `ready`, `navigate`, `error`, `change` |
| [`requirements-checklist`](/components/requirements-checklist) | `ready`, `navigate`, `error`, `requirement.completed` |
| [`onboarding-progress`](/components/onboarding-progress) | `ready`, `navigate`, `error`, `requirement.completed` |
| [`company-search`](/components/company-search) | `ready`, `navigate`, `error`, `select` |
| [`approval-button`](/components/approval-button) | `ready`, `navigate`, `error`, `approved`, `rejected` |
| [`accountant-badge`](/components/accountant-badge) | `ready`, `navigate`, `error` |
| [`engagement-card`](/components/engagement-card) | `ready`, `navigate`, `error`, `engagement.ended` |
| [`feed-status`](/components/feed-status) | `ready`, `navigate`, `error`, `click` |


---

<!-- /components/onboarding -->
# onboarding

Collects what FinBaze still needs to know about the company: legal details, tax set-up.

Kind: **view (fills its container)** · Session key: `onboarding` · React: `<FinBazeOnboarding />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { onboarding: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.onboarding.features`.

| Feature | Default |
| --- | --- |
| `editCompany` | on |
| `taxSetup` | on |
| `filingConsent` | on |

## Options

Passed to `instance.create("onboarding", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `collect` | `"currently_due" \| "eventually_due"` | Which requirements to ask for. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |
| `onboarding.step_completed` | `onOnboardingStepCompleted` |
| `onboarding.completed` | `onOnboardingCompleted` |

## Use it

```tsx
import { FinBazeOnboarding } from "@finbaze/embed-react";

<FinBazeOnboarding />
```

```ts
const component = instance.create("onboarding");
component.mount("#finbaze");
```


---

<!-- /components/tax-authorisation -->
# tax-authorisation

The company's authorisation for FinBaze to file its returns (per tax, with history and revoke) and the HMRC connection for UK VAT.

> **Filing consent**
>
> FinBaze files a platform company's returns only with the company's authorisation, given here by the company's admin user (see [Filing consent](/concepts/filing-consent)). A UK company also connects to HMRC in a popup and can disconnect it again (the `revoke` feature); that needs the `hmrc_mtd` feature in the allowance and the embed callback URL registered with HMRC. Your server cannot grant the consent, only read and revoke it.

Kind: **view (fills its container)** · Session key: `taxAuthorisation` · React: `<FinBazeTaxAuthorisation />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { taxAuthorisation: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.taxAuthorisation.features`.

| Feature | Default |
| --- | --- |
| `revoke` | on |
| `hmrcConnect` | on |
| `grant` | on |

## Options

Passed to `instance.create("tax-authorisation", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `taxes` | `("nl_vat" \| "nl_icp" \| "nl_oss" \| "nl_cit" \| "nl_annual_accounts" \| "nl_wage_tax" \| "nl_pension" \| "uk_vat" \| "uk_income_tax" \| "uk_annual_accounts")[]` | Limit to these taxes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |
| `tax_authorisation.revoked` | `onTaxAuthorisationRevoked` |
| `hmrc.connected` | `onHmrcConnected` |

## Use it

```tsx
import { FinBazeTaxAuthorisation } from "@finbaze/embed-react";

<FinBazeTaxAuthorisation />
```

```ts
const component = instance.create("tax-authorisation");
component.mount("#finbaze");
```


---

<!-- /components/notification-banner -->
# notification-banner

A one-line banner for the most important thing waiting: an overdue filing, missing authorisation.

Kind: **view (fills its container)** · Session key: `notificationBanner` · React: `<FinBazeNotificationBanner />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { notificationBanner: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.notificationBanner.features`.

| Feature | Default |
| --- | --- |
| `supportApproval` | on |

## Options

Passed to `instance.create("notification-banner", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `dismissible` | `boolean` | Show a close button. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `dismissed` | `onDismissed` |
| `support.access.approved` | `onSupportAccessApproved` |
| `support.access.declined` | `onSupportAccessDeclined` |

## Use it

```tsx
import { FinBazeNotificationBanner } from "@finbaze/embed-react";

<FinBazeNotificationBanner />
```

```ts
const component = instance.create("notification-banner");
component.mount("#finbaze");
```


---

<!-- /components/action-centre -->
# action-centre

The prioritised to-do list across bookkeeping and tax.

Kind: **view (fills its container)** · Session key: `actionCentre` · React: `<FinBazeActionCentre />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { actionCentre: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("action-centre", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `types` | `string[]` | Only these action types. |
| `limit` | `number` | Maximum number of items. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `action.selected` | `onActionSelected` |

## Use it

```tsx
import { FinBazeActionCentre } from "@finbaze/embed-react";

<FinBazeActionCentre />
```

```ts
const component = instance.create("action-centre");
component.mount("#finbaze");
```


---

<!-- /components/transactions -->
# transactions

Bank transactions with categorisation, splitting and receipt matching.

Kind: **view (fills its container)** · Session key: `transactions` · React: `<FinBazeTransactions />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { transactions: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.transactions.features`.

| Feature | Default |
| --- | --- |
| `categorise` | on |
| `split` | on |
| `attachReceipt` | on |
| `matchInvoices` | on |
| `aiSuggestions` | on |

## Options

Passed to `instance.create("transactions", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `bankAccountId` | `string` | One bank account. |
| `filter` | `"all" \| "processed" \| "unprocessed"` | Initial filter. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `transaction.categorised` | `onTransactionCategorised` |
| `receipt.attached` | `onReceiptAttached` |

## Use it

```tsx
import { FinBazeTransactions } from "@finbaze/embed-react";

<FinBazeTransactions />
```

```ts
const component = instance.create("transactions");
component.mount("#finbaze");
```


---

<!-- /components/transaction-detail -->
# transaction-detail

One transaction in detail, for deep links from your own list.

Kind: **view (fills its container)** · Session key: `transactionDetail` · React: `<FinBazeTransactionDetail />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { transactionDetail: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.transactionDetail.features`.

| Feature | Default |
| --- | --- |
| `categorise` | on |
| `split` | on |
| `attachReceipt` | on |
| `matchInvoices` | on |
| `aiSuggestions` | on |

## Options

Passed to `instance.create("transaction-detail", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `transactionId` | `string` | FinBaze transaction id. Or: |
| `bankAccountId + externalId` | `string` | Your id for the transaction. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `transaction.categorised` | `onTransactionCategorised` |
| `receipt.attached` | `onReceiptAttached` |

## Use it

```tsx
import { FinBazeTransactionDetail } from "@finbaze/embed-react";

<FinBazeTransactionDetail />
```

```ts
const component = instance.create("transaction-detail");
component.mount("#finbaze");
```


---

<!-- /components/purchase-inbox -->
# purchase-inbox

Incoming purchase documents: upload, review, approve.

Kind: **view (fills its container)** · Session key: `purchaseInbox` · React: `<FinBazePurchaseInbox />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { purchaseInbox: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `process_documents`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.purchaseInbox.features`.

| Feature | Default |
| --- | --- |
| `upload` | on |
| `approve` | on |
| `emailForwarding` | on |

## Options

Passed to `instance.create("purchase-inbox", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `tab` | `"inbox" \| "processed"` | Initial tab. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `document.uploaded` | `onDocumentUploaded` |
| `document.processed` | `onDocumentProcessed` |

## Use it

```tsx
import { FinBazePurchaseInbox } from "@finbaze/embed-react";

<FinBazePurchaseInbox />
```

```ts
const component = instance.create("purchase-inbox");
component.mount("#finbaze");
```


---

<!-- /components/tax-calendar -->
# tax-calendar

Upcoming and past tax obligations with their status.

Kind: **view (fills its container)** · Session key: `taxCalendar` · React: `<FinBazeTaxCalendar />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { taxCalendar: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("tax-calendar", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `year` | `number` | Calendar year. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.selected` | `onFilingSelected` |

## Use it

```tsx
import { FinBazeTaxCalendar } from "@finbaze/embed-react";

<FinBazeTaxCalendar />
```

```ts
const component = instance.create("tax-calendar");
component.mount("#finbaze");
```


---

<!-- /components/vat-return -->
# vat-return

Prepare, review and file a VAT return.

> **Overview only**
>
> This component shows the period, its status and what is owed. Preparing and submitting the return still happens in FinBaze; the `submit` feature has no effect yet.

Kind: **view (fills its container)** · Session key: `vatReturn` · React: `<FinBazeVatReturn />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { vatReturn: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.vatReturn.features`.

| Feature | Default |
| --- | --- |
| `submit` | on |
| `payment` | on |
| `suppletie` | on |
| `inlineConsent` | on |

## Options

Passed to `instance.create("vat-return", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `"current" \| "previous" \| { year, quarter?, month? }` | Which period. |
| `filingId` | `string` | Open a specific filing instead. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `payment.requested` | `onPaymentRequested` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazeVatReturn } from "@finbaze/embed-react";

<FinBazeVatReturn />
```

```ts
const component = instance.create("vat-return");
component.mount("#finbaze");
```


---

<!-- /components/icp-return -->
# icp-return

Prepare and file the Dutch ICP (intra-community supplies) return.

> **Overview only**
>
> This component shows the period, its status and what is owed. Preparing and submitting the return still happens in FinBaze; the `submit` feature has no effect yet.

Kind: **view (fills its container)** · Session key: `icpReturn` · React: `<FinBazeIcpReturn />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { icpReturn: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `icp_filing`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.icpReturn.features`.

| Feature | Default |
| --- | --- |
| `submit` | on |
| `inlineConsent` | on |

## Options

Passed to `instance.create("icp-return", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `"current" \| "previous" \| { year, quarter?, month? }` | Which period. |
| `filingId` | `string` | Open a specific filing instead. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazeIcpReturn } from "@finbaze/embed-react";

<FinBazeIcpReturn />
```

```ts
const component = instance.create("icp-return");
component.mount("#finbaze");
```


---

<!-- /components/oss-return -->
# oss-return

Prepare and file the One-Stop-Shop return.

> **Overview only**
>
> This component shows the period, its status and what is owed. Preparing and submitting the return still happens in FinBaze; the `submit` feature has no effect yet.

Kind: **view (fills its container)** · Session key: `ossReturn` · React: `<FinBazeOssReturn />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { ossReturn: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `one_stop_shop_filing`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.ossReturn.features`.

| Feature | Default |
| --- | --- |
| `submit` | on |
| `inlineConsent` | on |

## Options

Passed to `instance.create("oss-return", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `"current" \| "previous" \| { year, quarter?, month? }` | Which period. |
| `filingId` | `string` | Open a specific filing instead. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazeOssReturn } from "@finbaze/embed-react";

<FinBazeOssReturn />
```

```ts
const component = instance.create("oss-return");
component.mount("#finbaze");
```


---

<!-- /components/tax-payments -->
# tax-payments

Hand-off for paying filed returns.

> **Not yet available**
>
> This component is in the catalogue but has not shipped. `createEmbedSession` refuses it until it does ("is not available yet"); nothing else about your integration changes when it goes live.

Kind: **view (fills its container)** · Session key: `taxPayments` · React: `<FinBazeTaxPayments />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { taxPayments: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.taxPayments.features`.

| Feature | Default |
| --- | --- |
| `paymentHandoff` | on |
| `internetkassa` | off |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `payment.requested` | `onPaymentRequested` |

## Use it

```tsx
import { FinBazeTaxPayments } from "@finbaze/embed-react";

<FinBazeTaxPayments />
```

```ts
const component = instance.create("tax-payments");
component.mount("#finbaze");
```


---

<!-- /components/booking-chip -->
# booking-chip

A small inline chip showing how a transaction is booked; embed it in your own transaction list.

Kind: **element (inline)** · Session key: `bookingChip` · React: `<FinBazeBookingChip />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { bookingChip: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.bookingChip.features`.

| Feature | Default |
| --- | --- |
| `edit` | on |

## Options

Passed to `instance.create("booking-chip", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `transactionId | bankAccountId + externalId` | `string` |
| `size` | `"sm" \| "md"` | Chip size. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `booking.changed` | `onBookingChanged` |

## Use it

```tsx
import { FinBazeBookingChip } from "@finbaze/embed-react";

<FinBazeBookingChip />
```

```ts
const component = instance.create("booking-chip");
component.mount("#finbaze");
```


---

<!-- /components/receipt-button -->
# receipt-button

A button that attaches a receipt to a transaction.

Kind: **element (inline)** · Session key: `receiptButton` · React: `<FinBazeReceiptButton />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { receiptButton: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`, `process_documents`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("receipt-button", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `transactionId | bankAccountId + externalId` | `string` |
| `label` | `string` | Button label. |
| `variant` | `"button" \| "icon"` | Look. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `receipt.attached` | `onReceiptAttached` |

## Use it

```tsx
import { FinBazeReceiptButton } from "@finbaze/embed-react";

<FinBazeReceiptButton />
```

```ts
const component = instance.create("receipt-button");
component.mount("#finbaze");
```


---

<!-- /components/tax-due-chip -->
# tax-due-chip

A small inline chip with the next tax deadline.

Kind: **element (inline)** · Session key: `taxDueChip` · React: `<FinBazeTaxDueChip />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { taxDueChip: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("tax-due-chip", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `taxes` | `("nl_vat" \| "uk_vat")[]` | Which taxes. |
| `onClick` | `"event" \| "open"` | Emit `click` or open the filing. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeTaxDueChip } from "@finbaze/embed-react";

<FinBazeTaxDueChip />
```

```ts
const component = instance.create("tax-due-chip");
component.mount("#finbaze");
```


---

<!-- /components/accountant-connect -->
# accountant-connect

The company's accountant: find the firm by KvK number or connect code, choose what it may file, confirm the statement, approve a firm's request, or end the connection.

Kind: **view (fills its container)** · Session key: `accountantConnect` · React: `<FinBazeAccountantConnect />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { accountantConnect: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `firm_access`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.accountantConnect.features`.

| Feature | Default |
| --- | --- |
| `invite` | on |
| `approve` | on |
| `end` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `firm.connected` | `onFirmConnected` |
| `firm.disconnected` | `onFirmDisconnected` |

## Use it

```tsx
import { FinBazeAccountantConnect } from "@finbaze/embed-react";

<FinBazeAccountantConnect />
```

```ts
const component = instance.create("accountant-connect");
component.mount("#finbaze");
```


---

<!-- /components/company-transfer -->
# company-transfer

The company admin moves the company to another platform or to FinBaze: reads the statement, consents, gets a one-time code or an emailed claim link.

Kind: **element (inline)** · Session key: `companyTransfer` · React: `<FinBazeCompanyTransfer />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { companyTransfer: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `company.transfer.created` | `onCompanyTransferCreated` |
| `company.transfer.cancelled` | `onCompanyTransferCancelled` |

## Use it

```tsx
import { FinBazeCompanyTransfer } from "@finbaze/embed-react";

<FinBazeCompanyTransfer />
```

```ts
const component = instance.create("company-transfer");
component.mount("#finbaze");
```


---

<!-- /components/contact-support -->
# contact-support

A "Contact support" button. Your team handles the request first (`support.requested`), or FinBaze's form creates an escalation, depending on your support mode.

Kind: **element (inline)** · Session key: `contactSupport` · React: `<FinBazeContactSupport />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { contactSupport: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("contact-support", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `screen` | `string` | Where the user is (for example `vat-return`); sent with the request. |
| `label` | `string` | Button label. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `support.requested` | `onSupportRequested` |
| `support.escalation.created` | `onSupportEscalationCreated` |

## Use it

```tsx
import { FinBazeContactSupport } from "@finbaze/embed-react";

<FinBazeContactSupport />
```

```ts
const component = instance.create("contact-support");
component.mount("#finbaze");
```


---

<!-- /components/support-access -->
# support-access

The company admin's say over FinBaze support's access: approve or decline a request, see what is live, end it at once.

Kind: **view (fills its container)** · Session key: `supportAccess` · React: `<FinBazeSupportAccess />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { supportAccess: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.supportAccess.features`.

| Feature | Default |
| --- | --- |
| `decide` | on |
| `revoke` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `support.access.approved` | `onSupportAccessApproved` |
| `support.access.declined` | `onSupportAccessDeclined` |
| `support.access.revoked` | `onSupportAccessRevoked` |

## Use it

```tsx
import { FinBazeSupportAccess } from "@finbaze/embed-react";

<FinBazeSupportAccess />
```

```ts
const component = instance.create("support-access");
component.mount("#finbaze");
```


---

<!-- /components/company-settings -->
# company-settings

The company's details, tax questions, taxes and financial years.

Kind: **view (fills its container)** · Session key: `companySettings` · React: `<FinBazeCompanySettings />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { companySettings: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.companySettings.features`.

| Feature | Default |
| --- | --- |
| `editCompany` | on |
| `financialYears` | on |

## Options

Passed to `instance.create("company-settings", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `tab` | `'general' \| 'tax_questions' \| 'financial_years' \| 'taxes'` | The section to open first. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `company.updated` | `onCompanyUpdated` |

## Use it

```tsx
import { FinBazeCompanySettings } from "@finbaze/embed-react";

<FinBazeCompanySettings />
```

```ts
const component = instance.create("company-settings");
component.mount("#finbaze");
```


---

<!-- /components/bank-connections -->
# bank-connections

Connected bank accounts and feeds: connect a bank, see its status, disconnect it.

Kind: **view (fills its container)** · Session key: `bankConnections` · React: `<FinBazeBankConnections />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { bankConnections: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `lunchflow_accounts`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.bankConnections.features`.

| Feature | Default |
| --- | --- |
| `connect` | on |
| `disconnect` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `bank_connection.connected` | `onBankConnectionConnected` |
| `bank_connection.disconnected` | `onBankConnectionDisconnected` |

## Use it

```tsx
import { FinBazeBankConnections } from "@finbaze/embed-react";

<FinBazeBankConnections />
```

```ts
const component = instance.create("bank-connections");
component.mount("#finbaze");
```


---

<!-- /components/users-and-access -->
# users-and-access

Who has access to the company and with which role. Invitations, role changes and removals are requests to your platform, which decides: FinBaze sends no invitation email and creates no account.

Kind: **view (fills its container)** · Session key: `usersAndAccess` · React: `<FinBazeUsersAndAccess />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { usersAndAccess: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.usersAndAccess.features`.

| Feature | Default |
| --- | --- |
| `invite` | on |
| `changeRole` | on |
| `remove` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `user.invite_requested` | `onUserInviteRequested` |
| `user.role_change_requested` | `onUserRoleChangeRequested` |
| `user.removal_requested` | `onUserRemovalRequested` |

## Use it

```tsx
import { FinBazeUsersAndAccess } from "@finbaze/embed-react";

<FinBazeUsersAndAccess />
```

```ts
const component = instance.create("users-and-access");
component.mount("#finbaze");
```


---

<!-- /components/data-export -->
# data-export

Request exports of the company's books (XAF, PDF bundle, CSV) and download them.

Kind: **view (fills its container)** · Session key: `dataExport` · React: `<FinBazeDataExport />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { dataExport: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.dataExport.features`.

| Feature | Default |
| --- | --- |
| `request` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `export.requested` | `onExportRequested` |

## Use it

```tsx
import { FinBazeDataExport } from "@finbaze/embed-react";

<FinBazeDataExport />
```

```ts
const component = instance.create("data-export");
component.mount("#finbaze");
```


---

<!-- /components/dashboard -->
# dashboard

Revenue, costs, profit, cash and what needs attention, at a glance.

Kind: **view (fills its container)** · Session key: `dashboard` · React: `<FinBazeDashboard />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { dashboard: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("dashboard", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. Defaults to month. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeDashboard } from "@finbaze/embed-react";

<FinBazeDashboard />
```

```ts
const component = instance.create("dashboard");
component.mount("#finbaze");
```


---

<!-- /components/insights -->
# insights

Tax signals and advice, the cash and profit forecast and cash flow. Each part shows only when its module is on for the company.

Kind: **view (fills its container)** · Session key: `insights` · React: `<FinBazeInsights />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { insights: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("insights", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `tab` | `'advice' \| 'forecast' \| 'cashflow'` | The part to open first. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |

## Use it

```tsx
import { FinBazeInsights } from "@finbaze/embed-react";

<FinBazeInsights />
```

```ts
const component = instance.create("insights");
component.mount("#finbaze");
```


---

<!-- /components/bank-rules -->
# bank-rules

Rules that book recurring bank transactions automatically; yours, your platform's and the ones learned from bookings.

Kind: **view (fills its container)** · Session key: `bankRules` · React: `<FinBazeBankRules />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { bankRules: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.bankRules.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `edit` | on |
| `delete` | on |
| `apply` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `bank_rule.created` | `onBankRuleCreated` |
| `bank_rule.updated` | `onBankRuleUpdated` |
| `bank_rule.deleted` | `onBankRuleDeleted` |

## Use it

```tsx
import { FinBazeBankRules } from "@finbaze/embed-react";

<FinBazeBankRules />
```

```ts
const component = instance.create("bank-rules");
component.mount("#finbaze");
```


---

<!-- /components/reconciliation -->
# reconciliation

Per bank account and day: the statement balance against the ledger, with what explains a difference.

Kind: **view (fills its container)** · Session key: `reconciliation` · React: `<FinBazeReconciliation />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { reconciliation: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("reconciliation", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `accountId` | `string` | The bank account to show. Defaults to the first one. |
| `period` | `'current' \| 'previous' \| { year: number; month?: number }` | The month to show. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `reconciliation.day_selected` | `onReconciliationDaySelected` |

## Use it

```tsx
import { FinBazeReconciliation } from "@finbaze/embed-react";

<FinBazeReconciliation />
```

```ts
const component = instance.create("reconciliation");
component.mount("#finbaze");
```


---

<!-- /components/payment-batches -->
# payment-batches

Supplier payments grouped into batches. Your platform executes them; FinBaze never moves money.

Kind: **view (fills its container)** · Session key: `paymentBatches` · React: `<FinBazePaymentBatches />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { paymentBatches: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `payment_batches`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.paymentBatches.features`.

| Feature | Default |
| --- | --- |
| `requestPayment` | on |

## Options

Passed to `instance.create("payment-batches", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `batchId` | `string` | Open this batch instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `payment.requested` | `onPaymentRequested` |
| `payment_batch.selected` | `onPaymentBatchSelected` |

## Use it

```tsx
import { FinBazePaymentBatches } from "@finbaze/embed-react";

<FinBazePaymentBatches />
```

```ts
const component = instance.create("payment-batches");
component.mount("#finbaze");
```


---

<!-- /components/sales-invoices -->
# sales-invoices

Sales invoices: list, detail, send, credit.

Kind: **view (fills its container)** · Session key: `salesInvoices` · React: `<FinBazeSalesInvoices />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { salesInvoices: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `sales_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.salesInvoices.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `send` | on |
| `credit` | on |
| `export` | on |

## Options

Passed to `instance.create("sales-invoices", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `status` | `"all" \| "draft" \| "open" \| "overdue" \| "paid"` | Which invoices the list starts on. |
| `invoiceId` | `string` | Open this invoice instead of the list. |
| `customerId` | `string` | Only this customer's invoices. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `invoice.sent` | `onInvoiceSent` |
| `invoice.credited` | `onInvoiceCredited` |
| `invoice.selected` | `onInvoiceSelected` |

## Use it

```tsx
import { FinBazeSalesInvoices } from "@finbaze/embed-react";

<FinBazeSalesInvoices />
```

```ts
const component = instance.create("sales-invoices");
component.mount("#finbaze");
```


---

<!-- /components/invoice-editor -->
# invoice-editor

Create and edit a sales invoice draft, prefilled from your own data (a shipment, an order). Finalising books the invoice; with `send` it is mailed too.

Kind: **view (fills its container)** · Session key: `invoiceEditor` · React: `<FinBazeInvoiceEditor />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { invoiceEditor: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `sales_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.invoiceEditor.features`.

| Feature | Default |
| --- | --- |
| `save` | on |
| `send` | on |

## Options

Passed to `instance.create("invoice-editor", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `invoiceId` | `string` | Edit this invoice instead of starting one. |
| `externalId` | `string` | Your own id for the invoice (a shipment id, an order number). The editor finds the draft again by it and the invoice carries it, so opening it twice for the same shipment shows the same draft. |
| `prefill` | `{ customer?: { id?: string; externalId?: string; legalName?: string; firstName?: string; lastName?: string; email?: string; vatNumber?: string; address?: { country?: string; thoroughfare?: string; premise?: string; postalCode?: string; locality?: string } }; reference?: string; currency?: string; date?: string; due?: string; memo?: string; lines?: Array<{ name: string; description?: string; quantity: number; price: number; taxCode?: string; productId?: string }> }` | Starts a new draft with this data. Prices are minor units (cents) per unit; dates are YYYY-MM-DD. A customer you name by `id` or `externalId` is looked up among the company's customers. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `invoice.created` | `onInvoiceCreated` |
| `invoice.sent` | `onInvoiceSent` |

## Use it

```tsx
import { FinBazeInvoiceEditor } from "@finbaze/embed-react";

<FinBazeInvoiceEditor />
```

```ts
const component = instance.create("invoice-editor");
component.mount("#finbaze");
```


---

<!-- /components/quotes -->
# quotes

Quotes: list, detail, send, convert to an invoice.

Kind: **view (fills its container)** · Session key: `quotes` · React: `<FinBazeQuotes />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { quotes: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `quotes`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.quotes.features`.

| Feature | Default |
| --- | --- |
| `send` | on |
| `convert` | on |

## Options

Passed to `instance.create("quotes", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `quoteId` | `string` | Open this quote instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `quote.sent` | `onQuoteSent` |
| `quote.converted` | `onQuoteConverted` |
| `quote.selected` | `onQuoteSelected` |

## Use it

```tsx
import { FinBazeQuotes } from "@finbaze/embed-react";

<FinBazeQuotes />
```

```ts
const component = instance.create("quotes");
component.mount("#finbaze");
```


---

<!-- /components/recurring-invoices -->
# recurring-invoices

Subscription invoices that are issued on a schedule.

Kind: **view (fills its container)** · Session key: `recurringInvoices` · React: `<FinBazeRecurringInvoices />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { recurringInvoices: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `subscription_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.recurringInvoices.features`.

| Feature | Default |
| --- | --- |
| `activate` | on |

## Options

Passed to `instance.create("recurring-invoices", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `recurringId` | `string` | Open this subscription instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `recurring_invoice.activated` | `onRecurringInvoiceActivated` |
| `recurring_invoice.selected` | `onRecurringInvoiceSelected` |

## Use it

```tsx
import { FinBazeRecurringInvoices } from "@finbaze/embed-react";

<FinBazeRecurringInvoices />
```

```ts
const component = instance.create("recurring-invoices");
component.mount("#finbaze");
```


---

<!-- /components/customers -->
# customers

Customers: list, detail, create, edit.

Kind: **view (fills its container)** · Session key: `customers` · React: `<FinBazeCustomers />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { customers: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `relations`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.customers.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `edit` | on |

## Options

Passed to `instance.create("customers", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `customerId` | `string` | Open this customer instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `customer.created` | `onCustomerCreated` |
| `customer.updated` | `onCustomerUpdated` |
| `customer.selected` | `onCustomerSelected` |

## Use it

```tsx
import { FinBazeCustomers } from "@finbaze/embed-react";

<FinBazeCustomers />
```

```ts
const component = instance.create("customers");
component.mount("#finbaze");
```


---

<!-- /components/products -->
# products

Products and services with their prices and tax codes. Read only.

Kind: **view (fills its container)** · Session key: `products` · React: `<FinBazeProducts />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { products: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `products`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("products", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `productId` | `string` | Open this product instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `product.selected` | `onProductSelected` |

## Use it

```tsx
import { FinBazeProducts } from "@finbaze/embed-react";

<FinBazeProducts />
```

```ts
const component = instance.create("products");
component.mount("#finbaze");
```


---

<!-- /components/reminders -->
# reminders

Payment reminders for overdue sales invoices.

Kind: **view (fills its container)** · Session key: `reminders` · React: `<FinBazeReminders />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { reminders: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `reminders`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.reminders.features`.

| Feature | Default |
| --- | --- |
| `send` | on |
| `close` | on |

## Options

Passed to `instance.create("reminders", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `reminderId` | `string` | Open this reminder instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `reminder.sent` | `onReminderSent` |
| `reminder.closed` | `onReminderClosed` |
| `reminder.selected` | `onReminderSelected` |

## Use it

```tsx
import { FinBazeReminders } from "@finbaze/embed-react";

<FinBazeReminders />
```

```ts
const component = instance.create("reminders");
component.mount("#finbaze");
```


---

<!-- /components/purchase-invoices -->
# purchase-invoices

Purchase invoices: list, detail, confirm.

Kind: **view (fills its container)** · Session key: `purchaseInvoices` · React: `<FinBazePurchaseInvoices />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { purchaseInvoices: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `purchase_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.purchaseInvoices.features`.

| Feature | Default |
| --- | --- |
| `confirm` | on |

## Options

Passed to `instance.create("purchase-invoices", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `invoiceId` | `string` | Open this invoice instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `purchase_invoice.confirmed` | `onPurchaseInvoiceConfirmed` |
| `purchase_invoice.selected` | `onPurchaseInvoiceSelected` |

## Use it

```tsx
import { FinBazePurchaseInvoices } from "@finbaze/embed-react";

<FinBazePurchaseInvoices />
```

```ts
const component = instance.create("purchase-invoices");
component.mount("#finbaze");
```


---

<!-- /components/suppliers -->
# suppliers

Suppliers: list, detail, create, edit.

Kind: **view (fills its container)** · Session key: `suppliers` · React: `<FinBazeSuppliers />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { suppliers: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `relations`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.suppliers.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `edit` | on |

## Options

Passed to `instance.create("suppliers", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `supplierId` | `string` | Open this supplier instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `supplier.created` | `onSupplierCreated` |
| `supplier.updated` | `onSupplierUpdated` |
| `supplier.selected` | `onSupplierSelected` |

## Use it

```tsx
import { FinBazeSuppliers } from "@finbaze/embed-react";

<FinBazeSuppliers />
```

```ts
const component = instance.create("suppliers");
component.mount("#finbaze");
```


---

<!-- /components/document-requests -->
# document-requests

Documents your accountant asks for, with a place to answer and upload.

Kind: **view (fills its container)** · Session key: `documentRequests` · React: `<FinBazeDocumentRequests />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { documentRequests: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `document_requests`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.documentRequests.features`.

| Feature | Default |
| --- | --- |
| `respond` | on |
| `upload` | on |

## Options

Passed to `instance.create("document-requests", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `requestId` | `string` | Open this request instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `document_request.answered` | `onDocumentRequestAnswered` |

## Use it

```tsx
import { FinBazeDocumentRequests } from "@finbaze/embed-react";

<FinBazeDocumentRequests />
```

```ts
const component = instance.create("document-requests");
component.mount("#finbaze");
```


---

<!-- /components/reports -->
# reports

Profit and loss, balance sheet and the other reports, for any period.

Kind: **view (fills its container)** · Session key: `reports` · React: `<FinBazeReports />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { reports: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.reports.features`.

| Feature | Default |
| --- | --- |
| `export` | on |

## Options

Passed to `instance.create("reports", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `type` | `'profit_loss' \| 'balance_sheet' \| 'cashflow' \| 'debtors' \| 'creditors'` | The report to open first. |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `report.opened` | `onReportOpened` |

## Use it

```tsx
import { FinBazeReports } from "@finbaze/embed-react";

<FinBazeReports />
```

```ts
const component = instance.create("reports");
component.mount("#finbaze");
```


---

<!-- /components/general-ledger -->
# general-ledger

Ledger accounts with their balance for a period, and the entries on each.

Kind: **view (fills its container)** · Session key: `generalLedger` · React: `<FinBazeGeneralLedger />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { generalLedger: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("general-ledger", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. Defaults to month. |
| `ledgerCode` | `string` | Open this ledger account instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `ledger_account.selected` | `onLedgerAccountSelected` |

## Use it

```tsx
import { FinBazeGeneralLedger } from "@finbaze/embed-react";

<FinBazeGeneralLedger />
```

```ts
const component = instance.create("general-ledger");
component.mount("#finbaze");
```


---

<!-- /components/journal -->
# journal

Manual journal entries (memorial bookings).

Kind: **view (fills its container)** · Session key: `journal` · React: `<FinBazeJournal />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { journal: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `settlements`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.journal.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `delete` | off |

## Options

Passed to `instance.create("journal", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `entryId` | `string` | Open this entry instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `journal_entry.created` | `onJournalEntryCreated` |
| `journal_entry.deleted` | `onJournalEntryDeleted` |
| `journal_entry.selected` | `onJournalEntrySelected` |

## Use it

```tsx
import { FinBazeJournal } from "@finbaze/embed-react";

<FinBazeJournal />
```

```ts
const component = instance.create("journal");
component.mount("#finbaze");
```


---

<!-- /components/assets -->
# assets

Fixed assets and their depreciation. Read only.

Kind: **view (fills its container)** · Session key: `assets` · React: `<FinBazeAssets />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { assets: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `assets`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("assets", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `assetId` | `string` | Open this asset instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `asset.selected` | `onAssetSelected` |

## Use it

```tsx
import { FinBazeAssets } from "@finbaze/embed-react";

<FinBazeAssets />
```

```ts
const component = instance.create("assets");
component.mount("#finbaze");
```


---

<!-- /components/loans -->
# loans

Loans and their instalment schedule. Read only.

Kind: **view (fills its container)** · Session key: `loans` · React: `<FinBazeLoans />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { loans: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `loans`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("loans", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `loanId` | `string` | Open this loan instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `loan.selected` | `onLoanSelected` |

## Use it

```tsx
import { FinBazeLoans } from "@finbaze/embed-react";

<FinBazeLoans />
```

```ts
const component = instance.create("loans");
component.mount("#finbaze");
```


---

<!-- /components/vehicles -->
# vehicles

Company vehicles with their licence plate, and adding one.

Kind: **view (fills its container)** · Session key: `vehicles` · React: `<FinBazeVehicles />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { vehicles: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `vehicles`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.vehicles.features`.

| Feature | Default |
| --- | --- |
| `create` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `vehicle.created` | `onVehicleCreated` |

## Use it

```tsx
import { FinBazeVehicles } from "@finbaze/embed-react";

<FinBazeVehicles />
```

```ts
const component = instance.create("vehicles");
component.mount("#finbaze");
```


---

<!-- /components/projects -->
# projects

Projects with their revenue and costs this year. Read only.

Kind: **view (fills its container)** · Session key: `projects` · React: `<FinBazeProjects />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { projects: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `projects`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("projects", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `projectId` | `string` | Open this project instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `project.selected` | `onProjectSelected` |

## Use it

```tsx
import { FinBazeProjects } from "@finbaze/embed-react";

<FinBazeProjects />
```

```ts
const component = instance.create("projects");
component.mount("#finbaze");
```


---

<!-- /components/cost-centers -->
# cost-centers

Cost centres to split costs by.

Kind: **view (fills its container)** · Session key: `costCenters` · React: `<FinBazeCostCenters />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { costCenters: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `cost_centers`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.costCenters.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `edit` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `cost_center.created` | `onCostCenterCreated` |
| `cost_center.updated` | `onCostCenterUpdated` |

## Use it

```tsx
import { FinBazeCostCenters } from "@finbaze/embed-react";

<FinBazeCostCenters />
```

```ts
const component = instance.create("cost-centers");
component.mount("#finbaze");
```


---

<!-- /components/year-end -->
# year-end

The financial years: where each stands, and closing a year.

Kind: **view (fills its container)** · Session key: `yearEnd` · React: `<FinBazeYearEnd />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { yearEnd: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

Switch these off per session with `components.yearEnd.features`.

| Feature | Default |
| --- | --- |
| `close` | on |

## Options

Passed to `instance.create("year-end", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `yearId` | `string` | Open this financial year instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `financial_year.closed` | `onFinancialYearClosed` |

## Use it

```tsx
import { FinBazeYearEnd } from "@finbaze/embed-react";

<FinBazeYearEnd />
```

```ts
const component = instance.create("year-end");
component.mount("#finbaze");
```


---

<!-- /components/annual-accounts -->
# annual-accounts

The annual accounts (jaarrekening) of a financial year: the year-end questions, a frozen version, the directors' approval (the adoption) and the deposit at the KvK. The deposit goes through FinBaze's filing gate: it needs the company's authorisation (the consent form shows in place when it is missing, if the session also has the tax-authorisation or onboarding component) and shows who files.

Kind: **view (fills its container)** · Session key: `annualAccounts` · React: `<FinBazeAnnualAccounts />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { annualAccounts: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `annual_accounts`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.annualAccounts.features`.

| Feature | Default |
| --- | --- |
| `edit` | on |
| `approve` | on |
| `submit` | on |
| `inlineConsent` | on |

## Options

Passed to `instance.create("annual-accounts", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `dossierId` | `string` | Open this annual accounts dossier instead of the list of years. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazeAnnualAccounts } from "@finbaze/embed-react";

<FinBazeAnnualAccounts />
```

```ts
const component = instance.create("annual-accounts");
component.mount("#finbaze");
```


---

<!-- /components/cit-return -->
# cit-return

Corporate income tax (VPB): the return, provisional assessment, objection and extension.

> **Not yet available**
>
> This component is in the catalogue but has not shipped. `createEmbedSession` refuses it until it does ("is not available yet"); nothing else about your integration changes when it goes live.

Kind: **view (fills its container)** · Session key: `citReturn` · React: `<FinBazeCitReturn />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { citReturn: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `corporate_income_tax`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.citReturn.features`.

| Feature | Default |
| --- | --- |
| `submit` | on |
| `inlineConsent` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazeCitReturn } from "@finbaze/embed-react";

<FinBazeCitReturn />
```

```ts
const component = instance.create("cit-return");
component.mount("#finbaze");
```


---

<!-- /components/uk-itsa -->
# uk-itsa

UK Income Tax (MTD ITSA): quarterly updates and the final declaration. HMRC is connected in a popup (the system browser in a native app).

Kind: **view (fills its container)** · Session key: `ukItsa` · React: `<FinBazeUkItsa />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { ukItsa: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `uk_itsa`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.ukItsa.features`.

| Feature | Default |
| --- | --- |
| `prepare` | on |
| `submit` | on |
| `inlineConsent` | on |
| `hmrcConnect` | on |

## Options

Passed to `instance.create("uk-itsa", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `filingId` | `string` | Open this filing instead of the list of periods. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `hmrc.connected` | `onHmrcConnected` |

## Use it

```tsx
import { FinBazeUkItsa } from "@finbaze/embed-react";

<FinBazeUkItsa />
```

```ts
const component = instance.create("uk-itsa");
component.mount("#finbaze");
```


---

<!-- /components/us-1120 -->
# us-1120

US federal corporate tax: prepare Form 1120 from the ledger and take the PDF. FinBaze does not e-file it.

Kind: **view (fills its container)** · Session key: `us1120` · React: `<FinBazeUs1120 />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { us1120: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`, `us_federal_tax`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.us1120.features`.

| Feature | Default |
| --- | --- |
| `prepare` | on |
| `export` | on |

## Options

Passed to `instance.create("us-1120", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `filingId` | `string` | Open this filing instead of the list of tax years. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.prepared` | `onFilingPrepared` |

## Use it

```tsx
import { FinBazeUs1120 } from "@finbaze/embed-react";

<FinBazeUs1120 />
```

```ts
const component = instance.create("us-1120");
component.mount("#finbaze");
```


---

<!-- /components/employees -->
# employees

Employees: list, detail with their employments (read only), create and edit. The citizen service number and the ID document are never shown.

Kind: **view (fills its container)** · Session key: `employees` · React: `<FinBazeEmployees />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { employees: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `payroll`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.employees.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `edit` | on |

## Options

Passed to `instance.create("employees", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `employeeId` | `string` | Open this employee instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `employee.created` | `onEmployeeCreated` |
| `employee.updated` | `onEmployeeUpdated` |
| `employee.selected` | `onEmployeeSelected` |

## Use it

```tsx
import { FinBazeEmployees } from "@finbaze/embed-react";

<FinBazeEmployees />
```

```ts
const component = instance.create("employees");
component.mount("#finbaze");
```


---

<!-- /components/pay-runs -->
# pay-runs

Pay runs: calculate, approve (a second person), lock (posts to the ledger), pay the net wages through your platform and file the wage tax. FinBaze never moves money: paying hands a payment request to your app.

Kind: **view (fills its container)** · Session key: `payRuns` · React: `<FinBazePayRuns />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { payRuns: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `payroll`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.payRuns.features`.

| Feature | Default |
| --- | --- |
| `create` | on |
| `calculate` | on |
| `approve` | on |
| `finalise` | on |
| `paymentHandoff` | on |
| `filings` | on |

## Options

Passed to `instance.create("pay-runs", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `payRunId` | `string` | Open this pay run instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `pay_run.created` | `onPayRunCreated` |
| `pay_run.approved` | `onPayRunApproved` |
| `pay_run.selected` | `onPayRunSelected` |
| `payment.requested` | `onPaymentRequested` |

## Use it

```tsx
import { FinBazePayRuns } from "@finbaze/embed-react";

<FinBazePayRuns />
```

```ts
const component = instance.create("pay-runs");
component.mount("#finbaze");
```


---

<!-- /components/payslip-viewer -->
# payslip-viewer

An employee sees their own payslips and annual statements. Needs a session bound to the employee.

Kind: **view (fills its container)** · Session key: `payslipViewer` · React: `<FinBazePayslipViewer />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { payslipViewer: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `payroll`, `employee_self_service`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.payslipViewer.features`.

| Feature | Default |
| --- | --- |
| `download` | on |
| `yearDocuments` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `payslip.opened` | `onPayslipOpened` |
| `payslip.downloaded` | `onPayslipDownloaded` |

## Use it

```tsx
import { FinBazePayslipViewer } from "@finbaze/embed-react";

<FinBazePayslipViewer />
```

```ts
const component = instance.create("payslip-viewer");
component.mount("#finbaze");
```


---

<!-- /components/payroll-filings -->
# payroll-filings

Payroll tax (loonaangifte) and pension (UPA) filings of a pay run, from the first draft to the authority's answer, with corrections. Who files payroll for a platform company is not settled yet (open question Q4): the filer shown is whatever FinBaze's filing gate resolves, so enable this view per company and per platform once that is confirmed.

Kind: **view (fills its container)** · Session key: `payrollFilings` · React: `<FinBazePayrollFilings />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { payrollFilings: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `payroll`, `submit_tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.payrollFilings.features`.

| Feature | Default |
| --- | --- |
| `prepare` | on |
| `submit` | on |
| `inlineConsent` | on |

## Options

Passed to `instance.create("payroll-filings", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `filingId` | `string` | Open this filing instead of the list. |
| `type` | `'lh' \| 'upa'` | Which list to show first: wage tax (lh, default) or pension (upa). |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `filing.submitted` | `onFilingSubmitted` |
| `tax_authorisation.granted` | `onTaxAuthorisationGranted` |

## Use it

```tsx
import { FinBazePayrollFilings } from "@finbaze/embed-react";

<FinBazePayrollFilings />
```

```ts
const component = instance.create("payroll-filings");
component.mount("#finbaze");
```


---

<!-- /components/assistant -->
# assistant

The bookkeeping assistant chat. What the assistant may do on the books is cut to the other components of the session: with the assistant alone it answers and changes nothing. Its AI use is metered to your platform.

Kind: **view (fills its container)** · Session key: `assistant` · React: `<FinBazeAssistant />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { assistant: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `ai_assistant`, `ai_chat`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `assistant.message` | `onAssistantMessage` |

## Use it

```tsx
import { FinBazeAssistant } from "@finbaze/embed-react";

<FinBazeAssistant />
```

```ts
const component = instance.create("assistant");
component.mount("#finbaze");
```


---

<!-- /components/agent-tasks -->
# agent-tasks

Tasks FinBaze's agents prepared and the approvals they wait for. Agents that drive a computer are not part of the embed.

Kind: **view (fills its container)** · Session key: `agentTasks` · React: `<FinBazeAgentTasks />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { agentTasks: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `ai.agents`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.agentTasks.features`.

| Feature | Default |
| --- | --- |
| `approve` | on |
| `create` | on |
| `manage` | on |

## Options

Passed to `instance.create("agent-tasks", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `taskId` | `string` | Open this task instead of the list. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `agent_task.approved` | `onAgentTaskApproved` |
| `agent_task.rejected` | `onAgentTaskRejected` |
| `agent_task.selected` | `onAgentTaskSelected` |

## Use it

```tsx
import { FinBazeAgentTasks } from "@finbaze/embed-react";

<FinBazeAgentTasks />
```

```ts
const component = instance.create("agent-tasks");
component.mount("#finbaze");
```


---

<!-- /components/automations -->
# automations

Automations that react to events or run on a schedule. E-mail and WhatsApp actions go through the company's message routing; a webhook action can only reach the webhook hosts your platform registered; AI actions are not offered.

Kind: **view (fills its container)** · Session key: `automations` · React: `<FinBazeAutomations />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { automations: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `automations`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.automations.features`.

| Feature | Default |
| --- | --- |
| `toggle` | on |
| `edit` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `automation.updated` | `onAutomationUpdated` |

## Use it

```tsx
import { FinBazeAutomations } from "@finbaze/embed-react";

<FinBazeAutomations />
```

```ts
const component = instance.create("automations");
component.mount("#finbaze");
```


---

<!-- /components/suite -->
# suite

The whole product as one component: navigation over the views you enable.

Kind: **view (fills its container)** · Session key: `suite` · React: `<FinBazeSuite />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { suite: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("suite", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `initialRoute` | `string` | A suite route to open first, for example `sales/sales-invoices`. A route is `<section>/<component>` or `<section>/<component>/<id>`. |
| `route` | `string` | Drive the suite: pass a route and it opens that page. In external navigation the partner uses this to show the page a `suite_route` navigation pointed at. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |

## Use it

```tsx
import { FinBazeSuite } from "@finbaze/embed-react";

<FinBazeSuite />
```

```ts
const component = instance.create("suite");
component.mount("#finbaze");
```


---

<!-- /components/receipt-dropzone -->
# receipt-dropzone

A drop zone that uploads a receipt. With a transaction the receipt is attached to it; without one it goes to the purchase inbox, where FinBaze matches it to a payment.

Kind: **element (inline)** · Session key: `receiptDropzone` · React: `<FinBazeReceiptDropzone />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { receiptDropzone: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `process_documents`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("receipt-dropzone", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `transactionId` | `string` | The FinBaze transaction to attach the receipt to. |
| `bankAccountId` | `string` | With `transactionExternalId`: the bank account the transaction belongs to. |
| `transactionExternalId` | `string` | Your id of the transaction (as delivered in the feed), with `bankAccountId`. |
| `accept` | `string` | The file types the file dialog offers. Defaults to photos and PDFs. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `receipt.uploaded` | `onReceiptUploaded` |
| `receipt.matched` | `onReceiptMatched` |

## Use it

```tsx
import { FinBazeReceiptDropzone } from "@finbaze/embed-react";

<FinBazeReceiptDropzone />
```

```ts
const component = instance.create("receipt-dropzone");
component.mount("#finbaze");
```


---

<!-- /components/category-picker -->
# category-picker

A field that picks a cost or revenue category from the company's chart. Locked accounts are left out.

Kind: **element (inline)** · Session key: `categoryPicker` · React: `<FinBazeCategoryPicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { categoryPicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("category-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `value` | `string` | The account code chosen at first. |
| `kind` | `'cost' \| 'revenue' \| 'any'` | Which categories are offered. Defaults to any. |
| `name` | `string` | Your name for the field; it comes back in the `change` event. |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazeCategoryPicker } from "@finbaze/embed-react";

<FinBazeCategoryPicker />
```

```ts
const component = instance.create("category-picker");
component.mount("#finbaze");
```


---

<!-- /components/ledger-account-picker -->
# ledger-account-picker

A field that picks a ledger account from the company's chart. Locked accounts are left out.

Kind: **element (inline)** · Session key: `ledgerAccountPicker` · React: `<FinBazeLedgerAccountPicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { ledgerAccountPicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("ledger-account-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `value` | `string` | The account code chosen at first. |
| `kinds` | `Array<'balance' \| 'profit_loss'>` | Only these kinds of account. |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazeLedgerAccountPicker } from "@finbaze/embed-react";

<FinBazeLedgerAccountPicker />
```

```ts
const component = instance.create("ledger-account-picker");
component.mount("#finbaze");
```


---

<!-- /components/vat-code-picker -->
# vat-code-picker

A field that picks a VAT code for sales or purchases. For sales it offers the codes the company's tax obligations allow.

Kind: **element (inline)** · Session key: `vatCodePicker` · React: `<FinBazeVatCodePicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { vatCodePicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("vat-code-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `value` | `string` | The VAT code chosen at first. |
| `direction` | `'sales' \| 'purchase'` | Sales (default) or purchases. |
| `country` | `string` | Only this country's codes. Defaults to all for sales and the company's country for purchases. |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazeVatCodePicker } from "@finbaze/embed-react";

<FinBazeVatCodePicker />
```

```ts
const component = instance.create("vat-code-picker");
component.mount("#finbaze");
```


---

<!-- /components/invoice-status-badge -->
# invoice-status-badge

A badge showing where a sales invoice stands.

Kind: **element (inline)** · Session key: `invoiceStatusBadge` · React: `<FinBazeInvoiceStatusBadge />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { invoiceStatusBadge: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `sales_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("invoice-status-badge", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `invoiceId` | `string` | The sales invoice. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeInvoiceStatusBadge } from "@finbaze/embed-react";

<FinBazeInvoiceStatusBadge />
```

```ts
const component = instance.create("invoice-status-badge");
component.mount("#finbaze");
```


---

<!-- /components/invoice-pdf-preview -->
# invoice-pdf-preview

A preview of a sales invoice as FinBaze renders it (the document the PDF is made from). Previewing a draft that is not saved yet is not available: save the draft in the invoice editor first.

Kind: **element (inline)** · Session key: `invoicePdfPreview` · React: `<FinBazeInvoicePdfPreview />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { invoicePdfPreview: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `sales_invoices`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("invoice-pdf-preview", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `invoiceId` | `string` | The sales invoice to preview. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |

## Use it

```tsx
import { FinBazeInvoicePdfPreview } from "@finbaze/embed-react";

<FinBazeInvoicePdfPreview />
```

```ts
const component = instance.create("invoice-pdf-preview");
component.mount("#finbaze");
```


---

<!-- /components/file-now-button -->
# file-now-button

A button that opens the VAT return that is due next. Nothing is shown when none is due.

Kind: **element (inline)** · Session key: `fileNowButton` · React: `<FinBazeFileNowButton />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { fileNowButton: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `tax_filings`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `opened` | `onOpened` |

## Use it

```tsx
import { FinBazeFileNowButton } from "@finbaze/embed-react";

<FinBazeFileNowButton />
```

```ts
const component = instance.create("file-now-button");
component.mount("#finbaze");
```


---

<!-- /components/vat-reservation-meter -->
# vat-reservation-meter

How much to set aside for VAT, and a way to ask your platform to move it.

Kind: **element (inline)** · Session key: `vatReservationMeter` · React: `<FinBazeVatReservationMeter />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { vatReservationMeter: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `delegated.tax_reservation`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("vat-reservation-meter", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `targetAccountExternalId` | `string` | Your id of the account the money should move to; it comes back in `reserve.requested`. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `reserve.requested` | `onReserveRequested` |

## Use it

```tsx
import { FinBazeVatReservationMeter } from "@finbaze/embed-react";

<FinBazeVatReservationMeter />
```

```ts
const component = instance.create("vat-reservation-meter");
component.mount("#finbaze");
```


---

<!-- /components/profit-tile -->
# profit-tile

A tile with the profit of a period.

Kind: **element (inline)** · Session key: `profitTile` · React: `<FinBazeProfitTile />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { profitTile: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("profit-tile", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. Defaults to month. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeProfitTile } from "@finbaze/embed-react";

<FinBazeProfitTile />
```

```ts
const component = instance.create("profit-tile");
component.mount("#finbaze");
```


---

<!-- /components/revenue-tile -->
# revenue-tile

A tile with the revenue of a period.

Kind: **element (inline)** · Session key: `revenueTile` · React: `<FinBazeRevenueTile />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { revenueTile: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("revenue-tile", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. Defaults to month. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeRevenueTile } from "@finbaze/embed-react";

<FinBazeRevenueTile />
```

```ts
const component = instance.create("revenue-tile");
component.mount("#finbaze");
```


---

<!-- /components/cash-runway-tile -->
# cash-runway-tile

A tile with how many months the cash lasts at the pace of the last three months.

Kind: **element (inline)** · Session key: `cashRunwayTile` · React: `<FinBazeCashRunwayTile />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { cashRunwayTile: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeCashRunwayTile } from "@finbaze/embed-react";

<FinBazeCashRunwayTile />
```

```ts
const component = instance.create("cash-runway-tile");
component.mount("#finbaze");
```


---

<!-- /components/period-picker -->
# period-picker

A control to choose a period (month, quarter or year).

Kind: **element (inline)** · Session key: `periodPicker` · React: `<FinBazePeriodPicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { periodPicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("period-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `period` | `'current' \| 'previous' \| { year: number; month?: number; quarter?: number }` | The period to show. |
| `granularity` | `'month' \| 'quarter' \| 'year'` | How long a period is. Defaults to month. |
| `granularities` | `Array<'month' \| 'quarter' \| 'year'>` | The period lengths to offer. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazePeriodPicker } from "@finbaze/embed-react";

<FinBazePeriodPicker />
```

```ts
const component = instance.create("period-picker");
component.mount("#finbaze");
```


---

<!-- /components/customer-picker -->
# customer-picker

A field that picks a customer, searched on the server as the person types. Creating a customer is the customers view.

Kind: **element (inline)** · Session key: `customerPicker` · React: `<FinBazeCustomerPicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { customerPicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `relations`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("customer-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `value` | `string` | The customer chosen at first. |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazeCustomerPicker } from "@finbaze/embed-react";

<FinBazeCustomerPicker />
```

```ts
const component = instance.create("customer-picker");
component.mount("#finbaze");
```


---

<!-- /components/product-tax-code-picker -->
# product-tax-code-picker

A field that picks a product and reports its tax code for the company's country.

Kind: **element (inline)** · Session key: `productTaxCodePicker` · React: `<FinBazeProductTaxCodePicker />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { productTaxCodePicker: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `products`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("product-tax-code-picker", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `value` | `string` | The product chosen at first. |
| `country` | `string` | The country whose tax code is reported. Defaults to the company's. |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `change` | `onChange` |

## Use it

```tsx
import { FinBazeProductTaxCodePicker } from "@finbaze/embed-react";

<FinBazeProductTaxCodePicker />
```

```ts
const component = instance.create("product-tax-code-picker");
component.mount("#finbaze");
```


---

<!-- /components/requirements-checklist -->
# requirements-checklist

What FinBaze still needs from the company, as a checklist.

Kind: **element (inline)** · Session key: `requirementsChecklist` · React: `<FinBazeRequirementsChecklist />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { requirementsChecklist: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `requirement.completed` | `onRequirementCompleted` |

## Use it

```tsx
import { FinBazeRequirementsChecklist } from "@finbaze/embed-react";

<FinBazeRequirementsChecklist />
```

```ts
const component = instance.create("requirements-checklist");
component.mount("#finbaze");
```


---

<!-- /components/onboarding-progress -->
# onboarding-progress

How far the company is with what FinBaze asks of it, as a progress bar.

Kind: **element (inline)** · Session key: `onboardingProgress` · React: `<FinBazeOnboardingProgress />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { onboardingProgress: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `requirement.completed` | `onRequirementCompleted` |

## Use it

```tsx
import { FinBazeOnboardingProgress } from "@finbaze/embed-react";

<FinBazeOnboardingProgress />
```

```ts
const component = instance.create("onboarding-progress");
component.mount("#finbaze");
```


---

<!-- /components/company-search -->
# company-search

Search the Dutch KvK or UK Companies House register and return the company's registry data.

Kind: **element (inline)** · Session key: `companySearch` · React: `<FinBazeCompanySearch />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { companySearch: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

No feature requirements.

## Component features

None.

## Options

Passed to `instance.create("company-search", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `country` | `'NL' \| 'GB'` | The register to search: NL (KvK, default) or GB (Companies House). |
| `label` | `string` | The field label. |
| `disabled` | `boolean` | Show the field but do not allow changes. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `select` | `onSelect` |

## Use it

```tsx
import { FinBazeCompanySearch } from "@finbaze/embed-react";

<FinBazeCompanySearch />
```

```ts
const component = instance.create("company-search");
component.mount("#finbaze");
```


---

<!-- /components/approval-button -->
# approval-button

Approve or reject something an agent waits on a person for. Filing and payment approvals are not approvals in the API yet, so for now `approvalId` is an agent approval.

Kind: **element (inline)** · Session key: `approvalButton` · React: `<FinBazeApprovalButton />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { approvalButton: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `ai.agents`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("approval-button", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `approvalId` | `string` | The agent approval to decide. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `approved` | `onApproved` |
| `rejected` | `onRejected` |

## Use it

```tsx
import { FinBazeApprovalButton } from "@finbaze/embed-react";

<FinBazeApprovalButton />
```

```ts
const component = instance.create("approval-button");
component.mount("#finbaze");
```


---

<!-- /components/accountant-badge -->
# accountant-badge

A badge with the company's accountant. Nothing is shown without one.

Kind: **element (inline)** · Session key: `accountantBadge` · React: `<FinBazeAccountantBadge />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { accountantBadge: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `firm_access`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |

## Use it

```tsx
import { FinBazeAccountantBadge } from "@finbaze/embed-react";

<FinBazeAccountantBadge />
```

```ts
const component = instance.create("accountant-badge");
component.mount("#finbaze");
```


---

<!-- /components/engagement-card -->
# engagement-card

The company's engagement with its accountant: firm, scope, start date and a button to end it.

Kind: **element (inline)** · Session key: `engagementCard` · React: `<FinBazeEngagementCard />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { engagementCard: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `firm_access`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

Switch these off per session with `components.engagementCard.features`.

| Feature | Default |
| --- | --- |
| `end` | on |

## Options

Only the common options: `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `engagement.ended` | `onEngagementEnded` |

## Use it

```tsx
import { FinBazeEngagementCard } from "@finbaze/embed-react";

<FinBazeEngagementCard />
```

```ts
const component = instance.create("engagement-card");
component.mount("#finbaze");
```


---

<!-- /components/feed-status -->
# feed-status

How healthy the bank feed is: last update, gaps, errors.

Kind: **element (inline)** · Session key: `feedStatus` · React: `<FinBazeFeedStatus />`

## Create the session

```graphql
mutation {
  createEmbedSession(input: {
    companyId: "…"
    user: { externalUserId: "…" }
    components: { feedStatus: { enabled: true } }
  }) { clientSecret }
}
```

## Requirements

The company must have these features effective: `banking`. A hidden feature makes `createEmbedSession` fail with `FEATURE_DISABLED`.

## Component features

None.

## Options

Passed to `instance.create("feed-status", options)` or as props.

| Option | Type |  |
| --- | --- | --- |
| `dataSourceId` | `string` | Only the feeds of this data source. |

Every component also takes `appearance` and `navigation` (`"internal"` or `"external"`).

## Events

| Event | React prop |
| --- | --- |
| `ready` | `onReady` |
| `navigate` | `onNavigate` |
| `error` | `onError` |
| `click` | `onClick` |

## Use it

```tsx
import { FinBazeFeedStatus } from "@finbaze/embed-react";

<FinBazeFeedStatus />
```

```ts
const component = instance.create("feed-status");
component.mount("#finbaze");
```


---

<!-- /sdks/embed-js -->
# @finbaze/embed-js

The browser SDK: load the controller, create components, handle events.

```bash
npm install @finbaze/embed-js
```

```ts
import { loadFinBaze } from "@finbaze/embed-js";

const finbaze = await loadFinBaze("fb_pk_test_…", {
  fetchClientSecret: async ({ reason, previousSessionId }) => {
    const res = await fetch("/finbaze/session", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ previousSessionId }),
    });
    return (await res.json()).clientSecret;
  },
  appearance: { theme: "auto" },
  onError: (error) => console.error(error.code, error.message),
  onSessionExpired: (reason) => signOutOrReload(reason),
});

const calendar = finbaze.create("tax-calendar", { navigation: "external" });
calendar.on("navigate", ({ intent }) => router.push(toRoute(intent)));
calendar.mount("#finbaze");
```

Or use the script tag: `<script src="https://embed.finbaze.com/v1/embed.js"></script>` exposes `window.FinBaze.load(...)`.

## `fetchClientSecret`

Called on mount and before every refresh. It must return a **new** client secret each time. `reason` is `"initial"`, `"refresh"`, `"revoked"` (the session was revoked; mint a fresh chain) or `"error"` (the last attempt failed). Pass `previousSessionId` to `createEmbedSession`.

## Instance

| Method |  |
| --- | --- |
| `create(name, options)` | A component; call `mount(target)` on it |
| `update({ appearance, locale })` | Restyle or switch language live |
| `logout()` | Drop the token and destroy every component |
| `destroy()` | Remove the controller and everything it mounted |

## Component

| Method |  |
| --- | --- |
| `mount(target)` / `unmount()` / `destroy()` | Lifecycle |
| `update(options)` | Change options without remounting |
| `navigate(intent)` | Move a mounted component |
| `on(event, handler)` | Returns an unsubscribe function |

See [errors](/reference/errors) for the codes in `FinBazeEmbedError.code`.


---

<!-- /sdks/embed-react -->
# @finbaze/embed-react

React components and hooks for FinBaze.

```bash
npm install @finbaze/embed-react
```

```tsx
import { FinBazeProvider, FinBazeVatReturn } from "@finbaze/embed-react";

<FinBazeProvider publishableKey="fb_pk_test_…" fetchClientSecret={fetchClientSecret} appearance={{ theme: "auto" }}>
  <FinBazeVatReturn period="current" onFilingSubmitted={({ filing }) => track("vat_submitted", filing.id)} onError={console.error} />
</FinBazeProvider>
```

- One `<FinBazeProvider>` per signed-in user. It loads the controller once and destroys it on unmount.
- Every component takes its [options](/components) as props and every event as an `on…` prop (`filing.submitted` → `onFilingSubmitted`).
- Views fill their parent: give the parent a height. Elements (`FinBazeBookingChip`, `FinBazeReceiptButton`, `FinBazeTaxDueChip`) are inline.
- `useFinBaze()` returns the instance for `update`, `logout`, and so on.
- Components run in iframes, so they render only in the browser. In Next.js put them in a client component.

Pass stable references for `fetchClientSecret`; changing the function does not restart the session, but changing `publishableKey` does.


---

<!-- /sdks/headless -->
# Headless hooks

Build your own UI on FinBaze data with a token that lives in your page.

Headless sessions are for platforms that want their own screens. Unlike iframe components, the token lives in **your page**, so your page's security becomes part of FinBaze's. They are off by default (`platforms.headless`) and allowed only from origins you list as headless origins.

```tsx
import { FinBazeHeadlessProvider, useTransactions, useTaxDue } from "@finbaze/embed-react/headless";

function Dashboard() {
  const { items, hasMore, loadMore } = useTransactions({ pageSize: 25 });
  const tax = useTaxDue();
  return (/* your UI */);
}

<FinBazeHeadlessProvider publishableKey="fb_pk_test_…" fetchClientSecret={fetchHeadlessSecret}>
  <Dashboard />
</FinBazeHeadlessProvider>
```

Create the secret with `kind: headless` in `createEmbedSession`. The provider exchanges it in your page, refreshes it before expiry with a new secret, and asks for a new session once if it is revoked.

| Hook | Returns |
| --- | --- |
| `useCompany()` | the session's company, user, locale and open onboarding requirements |
| `useActionCentre()` | counts and the prioritised to-do items |
| `useTaxDue()` | the next tax filings with deadlines |
| `useTransactions({ pageSize, filter })` | a paged list: `items`, `loading`, `error`, `hasMore`, `loadMore()` |
| `useBooking(lookup)` | one booking summary and `attachReceipt(file)` |
| `useTaxAuthorisation()` | the company's [filing consent](/concepts/filing-consent): `status`, `statement(taxes)`, `grant({ statement, stepUp? })`, `revoke()` and `history()`. Needs the `tax-authorisation` or `onboarding` component |

Headless tokens run the same allowlisted operations as components, for the components in the session.


---

<!-- /sdks/server-snippets -->
# Server SDK snippets

The same server calls in Node, Python, PHP, Kotlin and Java.

The server SDKs share their behaviour (see the language pages: [Node](/sdks/node), [Python](/sdks/python), [PHP](/sdks/php), [Kotlin and Java](/sdks/java)): client-credentials exchange with a cached token, the `FinBaze-Version` header, an `Idempotency-Key` on every mutation that can be retried, retries that honour `Retry-After`, typed errors, auto-paging, and a constant-time webhook check. This page is generated from one snippet catalogue, so the five versions of each call cannot drift apart.

## Install

**Node**

```bash
npm install @finbaze/platform-sdk
```

**Python**

```bash
pip install finbaze
```

**PHP**

```bash
composer require finbaze/finbaze-php
```

**Kotlin**

```kotlin
implementation("com.finbaze:finbaze-java:0.1.0")
```

**Java**

```xml
<dependency>
  <groupId>com.finbaze</groupId>
  <artifactId>finbaze-java</artifactId>
  <version>0.1.0</version>
</dependency>
```

## Create the client

A `fb_sk_test_` or `fb_rk_test_` key uses the sandbox API, a live key the live API. The SDK exchanges the key for an access token, caches it and refreshes it a minute before it expires.

**Node**

```ts
import Finbaze from "@finbaze/platform-sdk";

const finbaze = new Finbaze({ secretKey: process.env.FINBAZE_SECRET_KEY });
```

**Python**

```python
import os
from finbaze import FinBaze

finbaze = FinBaze(secret_key=os.environ["FINBAZE_SECRET_KEY"])
```

**PHP**

```php
use FinBaze\FinBaze;

$finbaze = new FinBaze(getenv('FINBAZE_SECRET_KEY'));
```

**Kotlin**

```kotlin
val finbaze = FinBaze(secretKey = System.getenv("FINBAZE_SECRET_KEY"))
```

**Java**

```java
FinBaze finbaze = FinBaze.builder().secretKey(System.getenv("FINBAZE_SECRET_KEY")).build();
```

## Create a company

Idempotent by `externalId`: calling it again returns the same company with `created` false. The sandbox accepts the magic KvK number `00000001`.

**Node**

```ts
const company = await finbaze.platform.companies.create({
  externalId: "acme-1",
  registrationCountry: "NL",
  registrationNumber: "00000001",
});
```

**Python**

```python
company = finbaze.platform.companies.create(
    {"externalId": "acme-1", "registrationCountry": "NL", "registrationNumber": "00000001"}
)
company_id = company.company.id
```

**PHP**

```php
$company = $finbaze->platform->companies->create([
    'externalId' => 'acme-1',
    'registrationCountry' => 'NL',
    'registrationNumber' => '00000001',
]);
$companyId = $company->company->id;
```

**Kotlin**

```kotlin
val company = finbaze.platform.companies.create(
    externalId = "acme-1",
    registrationCountry = Country.NL,
    registrationNumber = "00000001",
)
val companyId = company.company.sdkPlatformCompanyFields.id
```

**Java**

```java
var company = finbaze.getPlatform().getCompanies().createAsync("acme-1", Country.NL, "00000001").get();
String companyId = company.getCompany().getSdkPlatformCompanyFields().getId();
```

## Upsert a user and give it access

Users are yours: identify them by your own id. `role` is `admin`, `member` or `viewer`.

**Node**

```ts
const user = await finbaze.platform.users.upsert({ externalUserId: "user-42", firstName: "Sam", lastName: "Jansen" });
await finbaze.platform.users.setAccess({ userId: user.id, companyId: company.id, role: "admin" });
```

**Python**

```python
user = finbaze.platform.users.upsert({"externalUserId": "user-42", "firstName": "Sam", "lastName": "Jansen"})
finbaze.platform.users.set_access(user_id=user.id, company_id=company_id, role="admin")
```

**PHP**

```php
$user = $finbaze->platform->users->upsert(['externalUserId' => 'user-42', 'firstName' => 'Sam', 'lastName' => 'Jansen']);
$finbaze->platform->users->setAccess(companyId: $companyId, role: 'admin', userId: $user->id);
```

**Kotlin**

```kotlin
val user = finbaze.platform.users.upsert(externalUserId = "user-42", firstName = "Sam", lastName = "Jansen")
finbaze.platform.users.setAccess(companyId = companyId, role = PermissionSet.admin, userId = user.id)
```

**Java**

```java
var user = finbaze.getPlatform().getUsers().upsertAsync("user-42", "Sam", "Jansen").get();
finbaze.getPlatform().getUsers().setAccessAsync(companyId, PermissionSet.admin, user.getId()).get();
```

## Mint a user token

A short-lived token that acts as one platform user on the companies you name. `asUser` does this for you and caches the token.

**Node**

```ts
const token = await finbaze.platform.userTokens.create({ userId: user.id, companyIds: [company.id] });
```

**Python**

```python
token = finbaze.platform.user_tokens.create(user_id=user.id, company_ids=[company_id])
as_user = finbaze.as_user(user_id=user.id, company_ids=[company_id])
```

**PHP**

```php
$token = $finbaze->platform->userTokens->create(userId: $user->id, companyIds: [$companyId]);
$asUser = $finbaze->asUser(userId: $user->id, companyIds: [$companyId]);
```

**Kotlin**

```kotlin
val token = finbaze.platform.userTokens.create(userId = user.id, companyIds = listOf(companyId))
val asUser = finbaze.asUser(userId = user.id, companyIds = listOf(companyId))
```

**Java**

```java
var token = finbaze.getPlatform().getUserTokens().createAsync(user.getId(), null, List.of(companyId), null).get();
FinBaze asUser = finbaze.asUser(user.getId(), null, List.of(companyId), null);
```

## Create an embed session

The client secret works once: create a new session for every mount and refresh, and hand only `clientSecret` to the browser.

**Node**

```ts
const session = await finbaze.platform.embedSessions.create({
  company: company.id,
  user: { id: user.id },
  components: { vatReturn: { enabled: true } },
  previousSessionId, // from the browser SDK's fetchClientSecret
});
return { clientSecret: session.clientSecret };
```

**Python**

```python
session = finbaze.platform.embed_sessions.create(
    company=company_id,
    user={"id": user.id},
    components={"vatReturn": {"enabled": True}},
)
client_secret = session.client_secret
```

**PHP**

```php
$session = $finbaze->platform->embedSessions->create(
    company: $companyId,
    user: ['id' => $user->id],
    components: ['vatReturn' => ['enabled' => true]],
);
$clientSecret = $session->clientSecret;
```

**Kotlin**

```kotlin
val session = finbaze.platform.embedSessions.create(
    company = companyId,
    user = EmbedUser.id(user.id),
    components = EmbedComponents.builder().vatReturn().build(),
)
val clientSecret = session.clientSecret
```

**Java**

```java
var session = finbaze.getPlatform().getEmbedSessions().createAsync(
    companyId, EmbedUser.id(user.getId()), EmbedComponents.builder().vatReturn(true).build()).get();
String clientSecret = session.getClientSecret();
```

## List with auto-paging

Lists are cursor pages. `data` is the current page; the auto-paging helper walks every page and fetches the next one only when you reach it.

**Node**

```ts
const page = await finbaze.platform.companies.list({ limit: 100 });
await page.autoPagingEach(async (c) => console.log(c.externalId));
```

**Python**

```python
for c in finbaze.platform.companies.list(limit=100).auto_paging_iter():
    print(c.external_id)
```

**PHP**

```php
foreach ($finbaze->platform->companies->list(limit: 100)->autoPaging() as $c) {
    echo $c->externalId, "\n";
}
```

**Kotlin**

```kotlin
finbaze.platform.companies.list(limit = 100).autoPaging().collect { println(it.externalId) }
```

**Java**

```java
for (var c : finbaze.getPlatform().getCompanies().listAsync(100, null).get().autoPagingIterable()) {
    System.out.println(c.getExternalId());
}
```

## Verify a webhook

Pass the body exactly as received, before any JSON parsing. The check is constant-time, accepts any of several signatures while a secret rotates, and rejects timestamps more than five minutes off.

**Node**

```ts
const event = await finbaze.webhooks.constructPlatformEvent(rawBody, req.header("x-finbaze-signature"), process.env.FINBAZE_WEBHOOK_SECRET);
```

**Python**

```python
event = finbaze.webhooks.construct_platform_event(raw_body, request.headers["X-FinBaze-Signature"], secret)
```

**PHP**

```php
$event = $finbaze->webhooks->constructPlatformEvent(file_get_contents('php://input'), $_SERVER['HTTP_X_FINBAZE_SIGNATURE'] ?? null, $secret);
```

**Kotlin**

```kotlin
val event = Webhooks.constructPlatformEvent(rawBody, request.header("X-FinBaze-Signature"), secret)
```

**Java**

```java
Map<String, Object> event = Webhooks.constructPlatformEvent(rawBody, request.getHeader("X-FinBaze-Signature"), secret);
```

## Handle errors

Errors are typed from `extensions.code` (see [errors](/reference/errors)). Network errors, 429 and 5xx are retried for you; a mutation that can be retried carries an `Idempotency-Key`.

**Node**

```ts
try {
  await finbaze.platform.companies.retrieve("c_missing");
} catch (error) {
  if (error instanceof FinbazeRateLimitError) await sleep(error.retryAfterSeconds * 1000);
  else throw error;
}
```

**Python**

```python
from finbaze import FeatureDisabledError, RateLimitError

try:
    finbaze.platform.features.effective(company_id)
except RateLimitError as error:
    time.sleep(error.retry_after_seconds or 1)
except FeatureDisabledError as error:
    log.warning("hidden: %s (request %s)", error.code, error.request_id)
```

**PHP**

```php
use FinBaze\Errors\FeatureDisabledError;
use FinBaze\Errors\RateLimitError;

try {
    $finbaze->platform->features->effective($companyId);
} catch (RateLimitError $e) {
    sleep((int) ($e->retryAfterSeconds ?? 1));
} catch (FeatureDisabledError $e) {
    error_log("hidden: {$e->errorCode} (request {$e->requestId})");
}
```

**Kotlin**

```kotlin
try {
    finbaze.platform.features.effective(companyId)
} catch (e: RateLimitError) {
    delay(((e.retryAfterSeconds ?: 1.0) * 1000).toLong())
} catch (e: FeatureDisabledError) {
    log.warn("hidden: ${e.code} (request ${e.requestId})")
}
```

**Java**

```java
try {
    finbaze.executeBlocking(new SdkPlatformCompanyFeaturesQuery(companyId));
} catch (RateLimitError e) {
    Thread.sleep((long) ((e.getRetryAfterSeconds() != null ? e.getRetryAfterSeconds() : 1.0) * 1000));
} catch (FeatureDisabledError e) {
    log.warn("hidden: {} (request {})", e.getCode(), e.getRequestId());
}
```

## Upload many objects (NDJSON)

One request, applied in the background. The API requires an `Idempotency-Key`; the SDK generates one, and reusing it retries the same upload safely.

**Node**

```ts
const job = await finbaze.platform.bulk.create({
  object: "relations",
  lines: [{ externalId: "r1", name: "First" }, { externalId: "r2", name: "Second" }],
  company: { externalId: "acme-1" },
});
```

**Python**

```python
job = finbaze.platform.bulk.create(
    object="relations",
    lines=[{"externalId": "r1", "name": "First"}, {"externalId": "r2", "name": "Second"}],
    company={"external_id": "acme-1"},
)
```

**PHP**

```php
$job = $finbaze->platform->bulk->create(
    object: 'relations',
    lines: [['externalId' => 'r1', 'name' => 'First'], ['externalId' => 'r2', 'name' => 'Second']],
    company: ['externalId' => 'acme-1'],
);
```

**Kotlin**

```kotlin
val job = finbaze.platform.bulk.create(
    objectType = "relations",
    lines = listOf(mapOf("externalId" to "r1", "name" to "First"), mapOf("externalId" to "r2", "name" to "Second")),
    company = "ext:acme-1",
)
```

**Java**

```java
var lines = List.of(Map.<String, Object>of("externalId", "r1", "name", "First"), Map.<String, Object>of("externalId", "r2", "name", "Second"));
var job = finbaze.getPlatform().getBulk().createAsync("relations", lines, "ext:acme-1").get();
```


---

<!-- /sdks/node -->
# @finbaze/platform-sdk

The Node SDK for your backend: companies, users, embed sessions, webhooks and the GraphQL API.

> **Release status**
>
> Version 1.0 is built and tested against the sandbox API, but is not on npm yet. Until it is, the plain GraphQL calls at the end of this page do the same work.

```bash
npm install @finbaze/platform-sdk
```

```ts
import Finbaze from "@finbaze/platform-sdk";

const finbaze = new Finbaze({ secretKey: process.env.FINBAZE_SECRET_KEY }); // fb_sk_test_… uses the sandbox
```

## Create a company, a user and an embed session

```ts
const company = await finbaze.platform.companies.create({ externalId: "acme-1", registrationCountry: "NL", registrationNumber: "12345678" });
const user = await finbaze.platform.users.upsert({ externalUserId: "user-42", firstName: "Sam", lastName: "Jansen" });
await finbaze.platform.users.setAccess({ userId: user.id, companyId: company.id, role: "admin" });

const session = await finbaze.platform.embedSessions.create({
  company: company.id,
  user: { id: user.id },
  components: { taxCalendar: { enabled: true } },
  previousSessionId, // from the browser SDK's fetchClientSecret
});
return { clientSecret: session.clientSecret };
```

Calls that write take `{ idempotencyKey }`; the SDK retries network errors, 429 and 503, and generates a key for a mutation it retries.

## Act as a user

```ts
const asUser = finbaze.asUser({ externalUserId: "user-42" }, { companyIds: [company.id] });
await asUser.companies.taxCalendar.retrieve(company.id, { year: 2026 });
await asUser.companies.transactions.list(company.id, { processed: false });
```

## Webhooks

```ts
const event = await finbaze.webhooks.constructEvent(rawBody, req.header("x-finbaze-signature"), process.env.FINBAZE_WEBHOOK_SECRET);
```

Pass the body exactly as received. Failures throw `FinbazeSignatureVerificationError`.

## What is in it

`platform` (companies, users, userTokens, embedSessions, features, usage, origins, and for the control surfaces messages, providers, paymentRequests, paymentLinks, taxReservation, stepUp, policies, extensions, documentLayouts, documentTemplates, documentRendering, documentFonts, customDomains), `companies` (bankAccounts, transactions, documents, taxCalendar, actionItems, filings, plus the invoice, relation and project resources), `webhooks`, `Finbaze.oauth(...)` for marketplace apps, and `graphql` for anything else. `@finbaze/platform-sdk/operations` adds a typed function for each of about 850 operations (a separate entry point, since it is large). Errors carry `code`, `param` and `requestId`; see [errors](/reference/errors).

## Control surfaces

```ts
import { Finbaze, isControlEvent, isMessageEvent } from "@finbaze/platform-sdk";

const event = await finbaze.webhooks.constructPlatformEvent(rawBody, signature, secret);
if (isMessageEvent(event)) {
  // event.data.object.type narrows event.data.object.data
} else if (isControlEvent(event) && event.type === "payment_link.requested") {
  await finbaze.platform.paymentLinks.provide({
    requestId: event.data.object.paymentLinkRequest.id,
    url: "https://pay.example.com/i/42",
  });
}
```

See [messages](/concepts/messages), [delegated actions](/concepts/delegated-actions), [policies and extensions](/concepts/policies-and-extensions) and [documents and rendering](/concepts/documents-and-rendering).

## Without the SDK

```ts
const BASE = "https://sandbox.api.platform.finbaze.com";
let token: { value: string; expiresAt: number } | null = null;

async function serverToken() {
  if (token && token.expiresAt > Date.now() + 30_000) return token.value;
  const res = await fetch(`${BASE}/v2/oauth2/token`, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ grant_type: "client_credentials", client_secret: process.env.FINBAZE_SECRET_KEY }),
  });
  const body = await res.json();
  token = { value: body.access_token, expiresAt: Date.now() + body.expires_in * 1000 };
  return token.value;
}

export async function finbaze<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
  const res = await fetch(`${BASE}/graphql`, {
    method: "POST",
    headers: { "content-type": "application/json", authorization: `Bearer ${await serverToken()}` },
    body: JSON.stringify({ query, variables }),
  });
  const body = await res.json();
  if (body.errors?.length) throw Object.assign(new Error(body.errors[0].message), { code: body.errors[0].extensions?.code });
  return body.data;
}
```

The [GraphQL reference](/reference/graphql) lists every operation with the scope it needs.

## Other languages

The same resources exist in [Python](/sdks/python), [PHP](/sdks/php) and [Kotlin and Java](/sdks/java); [server SDK snippets](/sdks/server-snippets) shows each call in all five languages.


---

<!-- /sdks/python -->
# Python (finbaze)

The Python server SDK: sync and async clients, typed models, webhooks.

> **Release status**
>
> Version 0.1 is built and tested against the shared conformance fixtures, but is not on PyPI yet. Until it is, the plain GraphQL calls on the [Node page](/sdks/node#without-the-sdk) do the same work from any language.

```bash
pip install finbaze
```

Python 3.10 or newer. `httpx` does the HTTP (sync and async), `pydantic` v2 types every answer. The SDK is generated from the same GraphQL operations as the [Node SDK](/sdks/node), so the resources and names match; only the casing follows the language.

```python
from finbaze import FinBaze

finbaze = FinBaze(secret_key="fb_sk_test_…")  # fb_*_test_ keys use the sandbox API

company = finbaze.platform.companies.create({"externalId": "acme-1", "registrationCountry": "NL", "registrationNumber": "00000001"})
user = finbaze.platform.users.upsert({"externalUserId": "user-42", "firstName": "Sam"})
finbaze.platform.users.set_access(user_id=user.id, company_id=company.company.id, role="admin")

session = finbaze.platform.embed_sessions.create(
    company=company.company.id, user={"id": user.id}, components={"vatReturn": {"enabled": True}},
)
return {"clientSecret": session.client_secret}
```

Async: `from finbaze import AsyncFinBaze`, the same names, `await` the calls and `async for` over `auto_paging_iter()`. `with FinBaze(...)` and `async with AsyncFinBaze(...)` close the connection pool.

Options: `FinBaze(secret_key, api_base=…, version=…, max_retries=2, timeout=30.0, scopes=[…], app_info={"name": …})`. You can also pass `access_token=` (a platform user token) or `client_id=`, `client_secret=` and `profile_id=`.

## What the client does for you

- Exchanges the key for an access token (`POST /v2/oauth2/token`), caches it and refreshes it 60 seconds before it expires; a token the API rejects is dropped and exchanged again.
- Sends `FinBaze-Version` (the API version this SDK was built for).
- Puts an `Idempotency-Key` on every mutation that can be retried and keeps the same key on every attempt. Pass `idempotency_key="…"` to choose it, for example to tie a create to your own order id.
- Retries network errors, HTTP 429 and 500/502/503/504 (not GraphQL errors) with jittered backoff; a `Retry-After` header is a floor. `max_retries=0` turns retries off.

## Webhooks

```python
event = finbaze.webhooks.construct_platform_event(raw_body, request.headers["X-FinBaze-Signature"], secret)
```

Pass the body exactly as received. `secret` may be a list (`[new, old]`) while you rotate. The check is constant-time and rejects timestamps more than 300 seconds off; failures raise `SignatureVerificationError`. `generate_test_header(payload, secret)` builds a valid header for your own tests. See [events and webhooks](/concepts/events-and-webhooks).

## Errors

`FinBazeError` is the base class; every error carries `code`, `status`, `param`, `doc_url` and `request_id`.

| Class | Raised for |
| --- | --- |
| `AuthenticationError` | `UNAUTHENTICATED`, `EMBED_SECRET_INVALID`, `EMBED_SESSION_REVOKED`, HTTP 401 |
| `RateLimitError` | `RATE_LIMITED`, HTTP 429; `retry_after_seconds` |
| `FeatureDisabledError` | `FEATURE_DISABLED`, `EMBED_FEATURE_DISABLED`, `PLATFORM_HEADLESS_DISABLED` |
| `OperationNotAllowedError` | `EMBED_OPERATION_NOT_ALLOWED`, `EMBED_COMPONENT_NOT_ALLOWED`, `FORBIDDEN_TOKEN_TYPE`, `FORBIDDEN` |
| `NotFoundError` | `NOT_FOUND`, `*_NOT_FOUND`, HTTP 404 |
| `ValidationError` | `BAD_USER_INPUT`, `INVALID_PARAMETER`, `INVALID_INPUT`; `param` names the argument |
| `ApiError` | any other code (read `code`) |
| `NetworkError`, `ServiceUnavailableError` | no answer, or HTTP 5xx after the retries |

The mapping is the same in every server SDK; see [errors](/reference/errors) for the codes.

## Resources

`platform.companies`, `users`, `user_tokens`, `embed_sessions`, `features` (and `features.limits`), `usage`, `data_sources`, `bulk` (NDJSON uploads over HTTP), `messages` (`acknowledge`) and `step_up` (`challenge`, and `header` for retrying with a signed assertion). Lists return a `Page`: `page.data` is one page, `page.auto_paging_iter()` walks them all.

`finbaze.graphql` is the typed client for every operation in the [GraphQL reference](/reference/graphql) that the SDK covers, for example `finbaze.graphql.sdk_platform_company(external_id="acme-1")`, returning pydantic models.

The same calls in all five languages are on [server SDK snippets](/sdks/server-snippets).


---

<!-- /sdks/docs-mcp -->
# Docs MCP and llms.txt

Give your coding agent these docs: an MCP server, llms.txt, Markdown for every page, a copy button and an agent skill.

Everything on this site is also available to AI tools, in five ways. All of them are public and read-only.

| What | Where | Use it for |
| --- | --- | --- |
| Docs MCP server | `https://mcp.finbaze.com/docs/mcp` | An agent that looks things up while it writes code |
| `llms.txt` | [`/llms.txt`](/llms.txt) | A short map of the site with the hostnames and auth in one screen |
| `llms-full.txt` | [`/llms-full.txt`](/llms-full.txt) | Every page as one Markdown file, for tools that load the whole thing |
| `.md` per page | `/quickstart.md`, `/guides/banks.md`, … | One page as Markdown |
| Copy for AI | The button on every page | The same Markdown, on your clipboard |
| Agent skill | [Agent skill](/sdks/agent-skill) | "Integrate FinBaze embedded components into a Next.js app" |

## Docs MCP

Add the server to your agent. It needs no sign-in and holds no session: each request stands alone.

```json
{ "mcpServers": { "finbaze-docs": { "url": "https://mcp.finbaze.com/docs/mcp" } } }
```

Claude Code: `claude mcp add --transport http finbaze-docs https://mcp.finbaze.com/docs/mcp`.

| Tool | Input | Returns |
| --- | --- | --- |
| `search_docs` | `query`, `section?` | The top 8 pages with a snippet and the URL |
| `get_page` | `path` | The page as Markdown |
| `get_graphql_type` | `name` | The SDL of a type, its description and the operations that use it |
| `get_operation` | `name` | The operation: signature, scope and feature it needs, a document with example variables, and a request snippet in Node, Kotlin, PHP and Python |
| `list_components`, `get_component` | `key?` | The component catalogue, or one component with its options, features, events and requirements |
| `get_webhook_event` | `type` | The event's description and a sample delivery |
| `get_error_code` | `code` | What an error code means and what to do |

The index is built with the site, from the same Markdown and the same generated references, so the server never answers from an older version than the page you are reading. It lists the operations a platform key or token can reach, not the whole GraphQL schema of FinBaze.

The request snippets call the HTTP API directly (`/v2/oauth2/token`, then `/graphql`). Typed SDK methods for Kotlin, PHP and Python are generated from the same documents and arrive with those SDKs.

The server is rate limited per client. Do not point a loop at it; fetch `llms-full.txt` instead.

## llms.txt and Markdown

`llms.txt` follows the [llms.txt convention](https://llmstxt.org): a title, a summary, then links. `llms-full.txt` is every page in order, each preceded by an HTML comment with its path. Append `.md` to any page address for its Markdown (`/guides/pos.md`), or press **Copy for AI** on the page.


---

<!-- /sdks/php -->
# PHP (finbaze-php)

The PHP server SDK: PSR-18 client, typed operations, webhooks.

> **Release status**
>
> Version 0.1 is built and tested against the shared conformance fixtures, but is not on Packagist yet. Until it is, the plain GraphQL calls on the [Node page](/sdks/node#without-the-sdk) do the same work from any language.

```bash
composer require finbaze/finbaze-php
```

PHP 8.1 or newer, any PSR-18 HTTP client (Guzzle is the default). The typed operation classes are generated with Sailor from the same GraphQL operations as the [Node SDK](/sdks/node); the resources and names match, in camelCase.

```php
use FinBaze\FinBaze;

$finbaze = new FinBaze('fb_sk_test_…');  // fb_*_test_ keys use the sandbox API

$company = $finbaze->platform->companies->create(['externalId' => 'acme-1', 'registrationCountry' => 'NL', 'registrationNumber' => '00000001']);
$user = $finbaze->platform->users->upsert(['externalUserId' => 'user-42', 'firstName' => 'Sam']);
$finbaze->platform->users->setAccess(companyId: $company->company->id, role: 'admin', userId: $user->id);

$session = $finbaze->platform->embedSessions->create(
    company: $company->company->id,
    user: ['id' => $user->id],
    components: ['vatReturn' => ['enabled' => true]],
);
return ['clientSecret' => $session->clientSecret];
```

Options (second argument): `apiBase`, `version`, `maxRetries` (default 2), `timeout` (seconds), `scopes`, `appInfo`, `httpClient` (any PSR-18 client), `requestFactory`, `streamFactory`, and `accessToken` or `clientId` + `clientSecret` + `profileId` instead of a secret key.

## What the client does for you

- Exchanges the key for an access token, caches it and refreshes it 60 seconds before it expires; a token the API rejects is dropped and exchanged again.
- Sends `FinBaze-Version`, and an `Idempotency-Key` on every mutation that can be retried, the same on every attempt. Pass the key as the last argument of a write to choose it.
- Retries network errors, HTTP 429 and 500/502/503/504 (not GraphQL errors) with jittered backoff; a `Retry-After` header is a floor.

## Webhooks

```php
$event = $finbaze->webhooks->constructPlatformEvent(file_get_contents('php://input'), $_SERVER['HTTP_X_FINBAZE_SIGNATURE'] ?? null, $secret);
```

Pass the body exactly as received. `$secret` may be an array (`[$new, $old]`) while you rotate. The check is constant-time (`hash_equals`) and rejects timestamps more than 300 seconds off; failures throw `FinBaze\Errors\SignatureVerificationError`. See [events and webhooks](/concepts/events-and-webhooks).

## Errors

`FinBaze\Errors\FinBazeError` is the base class; each error carries `errorCode`, `status`, `param`, `docUrl` and `requestId`. The subclasses are `AuthenticationError`, `RateLimitError` (`retryAfterSeconds`), `FeatureDisabledError`, `OperationNotAllowedError`, `NotFoundError`, `ValidationError`, `ApiError`, `NetworkError` and `ServiceUnavailableError`, mapped from `extensions.code` exactly as in the [Python SDK](/sdks/python#errors) and every other server SDK. See [errors](/reference/errors).

## Resources and every operation

`platform->companies`, `users`, `userTokens`, `embedSessions`, `features` (and `features->limits`), `usage`, `dataSources`, `bulk` (NDJSON uploads), `messages` (`acknowledge`) and `stepUp`. Lists return a `Page`: `$page->data` is one page, `$page->autoPaging()` is a generator over all of them.

Any other operation is a generated class; run it with the client's credentials, retries and key:

```php
use FinBaze\Generated\Operations\SdkPlatformCompany;

$result = $finbaze->execute(fn () => SdkPlatformCompany::execute(externalId: 'acme-1'));
$result->data->platformCompany->legalName;
```

The same calls in all five languages are on [server SDK snippets](/sdks/server-snippets).


---

<!-- /sdks/agent-skill -->
# Agent skill

A skill that teaches a coding agent to integrate FinBaze embedded components into a Next.js app.

The skill is a folder your coding agent loads when you ask it to add FinBaze to a Next.js app: "integrate FinBaze embedded components into this app". It tells the agent the order of work, the three pieces it must write (a session route, a provider, the components), what never to do (put the secret key in the browser, cache a client secret), and which pages to read.

Download it from this site, or pull the files:

- [`/skills/finbaze-embed-nextjs/SKILL.md`](/skills/finbaze-embed-nextjs/SKILL.md): the skill.
- [`/skills/finbaze-embed-nextjs/references/session-route.md`](/skills/finbaze-embed-nextjs/references/session-route.md): the backend route and the user and access set-up.
- [`/skills/finbaze-embed-nextjs/references/checklist.md`](/skills/finbaze-embed-nextjs/references/checklist.md): the checklist the agent ends with.
- [`/skills/index.json`](/skills/index.json): the list of skills and their files.

Put the folder in `.claude/skills/finbaze-embed-nextjs/` of your project (Claude Code), or add `SKILL.md` to the instructions of another agent. Pair it with the [docs MCP](/sdks/docs-mcp) so the agent can look up component options and error codes.

The skill is generated from the registry and checked in CI: the component names it mentions must exist, and the code it shows is the code of the neobank demo.


---

<!-- /sdks/java -->
# Kotlin and Java (finbaze-java)

The JVM server SDK: coroutines and CompletableFuture, typed Apollo models, webhooks.

> **Release status**
>
> Version 0.1 is built and tested against the shared conformance fixtures, but is not on Maven Central yet. Until it is, the plain GraphQL calls on the [Node page](/sdks/node#without-the-sdk) do the same work from any language.

```kotlin
implementation("com.finbaze:finbaze-java:0.1.0")
```

JVM 17 or newer. OkHttp does the HTTP; the models and operations are generated with Apollo Kotlin from the same GraphQL operations as the [Node SDK](/sdks/node). Kotlin gets `suspend` functions and `Flow`; every call also has an `…Async` twin returning a `CompletableFuture` for Java, and `executeBlocking` for scripts.

```kotlin
val finbaze = FinBaze(secretKey = "fb_sk_test_…")  // fb_*_test_ keys use the sandbox API

val company = finbaze.platform.companies.create(externalId = "acme-1", registrationCountry = Country.NL, registrationNumber = "00000001")
val companyId = company.company.sdkPlatformCompanyFields.id
val user = finbaze.platform.users.upsert(externalUserId = "user-42", firstName = "Sam")
finbaze.platform.users.setAccess(companyId = companyId, role = PermissionSet.admin, userId = user.id)

val session = finbaze.platform.embedSessions.create(
    company = companyId,
    user = EmbedUser.id(user.id),
    components = EmbedComponents.builder().vatReturn().build(),
)
return mapOf("clientSecret" to session.clientSecret)
```

```java
FinBaze finbaze = FinBaze.builder().secretKey("fb_sk_test_…").maxRetries(2).build();

var company = finbaze.getPlatform().getCompanies().createAsync("acme-1", Country.NL, "00000001").get();
```

The long forms take the generated input classes (`CreatePlatformCompanyInput`, `UpsertPlatformUserInput`, …) when you need fields the short forms leave out. Close the client (`close()`) when your application stops.

## What the client does for you

- Exchanges the key for an access token, caches it and refreshes it 60 seconds before it expires; a token the API rejects is dropped and exchanged again.
- Sends `FinBaze-Version`, and an `Idempotency-Key` on every mutation that can be retried, the same on every attempt. Pass `idempotencyKey` to choose it.
- Retries network errors, HTTP 429 and 500/502/503/504 (not GraphQL errors) with jittered backoff; a `Retry-After` header is a floor.

## Webhooks

```kotlin
val event = Webhooks.constructPlatformEvent(rawBody, request.header("X-FinBaze-Signature"), secret)
```

Pass the body exactly as received. `Webhooks` is a static helper for Java; pass a `List<String>` of secrets while you rotate. The check is constant-time and rejects timestamps more than 300 seconds off; failures throw `SignatureVerificationError`. See [events and webhooks](/concepts/events-and-webhooks).

## Errors

`FinBazeError` is the base class (unchecked); each error carries `code`, `status`, `param`, `docUrl` and `requestId`. The subclasses are `AuthenticationError`, `RateLimitError` (`retryAfterSeconds`), `FeatureDisabledError`, `OperationNotAllowedError`, `NotFoundError`, `ValidationError`, `ApiError`, `NetworkError` and `ServiceUnavailableError`, mapped from `extensions.code` exactly as in the [Python SDK](/sdks/python#errors) and every other server SDK. See [errors](/reference/errors).

## Resources and every operation

`platform.companies`, `users`, `userTokens`, `embedSessions`, `features` (and `features.limits`), `usage`, `dataSources`, `bulk` (NDJSON uploads), `messages` (`acknowledge`) and `stepUp`. Lists return a `Page`: `page.data` is one page; `autoPaging()` is a `Flow`, `autoPagingToList()` a list and `autoPagingIterable()` a blocking `Iterable` for Java.

Any other operation is a generated class in `com.finbaze.generated`; run it with the client's credentials, retries and key:

```kotlin
val data = finbaze.execute(SdkPlatformCompanyQuery(profileId = null, externalId = "acme-1"))
data.platformCompany?.sdkPlatformCompanyFields?.legalName
```

The same calls in all five languages are on [server SDK snippets](/sdks/server-snippets).


---

<!-- /reference/errors -->
# Errors

Every error code the platform API returns, grouped by area, and what to do about each.

GraphQL errors carry a top-level `extensions.code`. Branch on the code, not the message. The REST routes (bulk jobs, statement files, downloads) answer `{ "error": { "type", "code", "message", "param", "request_id" } }` with the same codes. Every response has an `X-Request-Id` header; send it to support. This page lists 159 codes.

## Embed sessions and tokens

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `EMBED_SECRET_INVALID` | 401 | The client secret is malformed or unknown. | Create a new session and pass its `clientSecret` unchanged. Never reuse or edit a secret. |
| `EMBED_SECRET_USED` | 403 | The client secret was already exchanged. | Secrets are single use. Return a **new** secret from `fetchClientSecret` every time; do not cache it. |
| `EMBED_SECRET_EXPIRED` | 403 | The client secret was not exchanged within its lifetime (15 minutes). | Create the session as late as possible, in `fetchClientSecret`. |
| `EMBED_SESSION_REVOKED` | 401 | The session was revoked, or the user lost access or was disabled. | The SDK asks `fetchClientSecret` for a new session once (`reason: "revoked"`). If your backend refuses, `onSessionExpired` fires. |
| `EMBED_ORIGIN_NOT_ALLOWED` | 403 | The page's origin is not in the platform's allowed origins (or not the session's `origin`). | Add the origin in the developer portal under **Embedding → Allowed origins**. Test and live origins are separate. |
| `EMBED_COMPONENT_NOT_ALLOWED` | 403 | The component is not part of this session. | Include it in `components` when you create the session. |
| `EMBED_OPERATION_NOT_ALLOWED` | 403 | An embed token tried to run a GraphQL document that is not in the operations manifest. | Embed tokens only run FinBaze's own operations. Use the server API or a headless session for custom queries. |
| `EMBED_FEATURE_DISABLED` | 403 | A component feature (for example `submit`) is switched off for this session. | Enable it in the session's `components.<name>.features`. |
| `EMBED_CHAIN_EXPIRED` | 403 | A chain of refreshed sessions reached its maximum lifetime (12 hours by default). | The user signs in again in your product; mint a session without `previousSessionId`. |
| `EMBED_APP_MISMATCH` | 403 | The session was created for a different channel: a mobile session was used on the web embed, a web session on the mobile shell, or the wrong app id was named. | Create the session with the same `mobileAppId` (or none, for web) that you use to open it, and pass that app id to the mobile SDK. |
| `PLATFORM_HEADLESS_DISABLED` | 403 | Headless sessions are not enabled for this platform. | Ask FinBaze to enable `platforms.headless`, then add the origin as a headless origin. |
| `UNAUTHENTICATED` | 401 | Missing, expired or revoked token. | Request a new token. The embed SDK maps this to `EMBED_SESSION_REVOKED`. |
| `FORBIDDEN_TOKEN_TYPE` | 403 | This kind of token cannot call the operation, for instance a server token calling `grantTaxAuthorisation`. | Consent is given by the company's own user in an embed or headless session. |
| `SERVER_TOKEN_REQUIRED` |  | Only a platform server token can use this endpoint (data ingestion over HTTP). | Call it with your secret or restricted key's token, not a user, embed or headless token. |
| `SCOPE_MISSING` |  | The key or token lacks the scope the endpoint needs. | Add the scope named in the message to the restricted key, or use a secret key. |

## Filing consent and step-up

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `TAX_AUTHORISATION_REQUIRED` | 403 | A return was submitted for a platform company that has not authorised FinBaze to file this tax (or revoked it). | The company's admin authorises it in the `onboarding` or `tax-authorisation` component (or your headless UI). See [Filing consent](/concepts/filing-consent). |
| `TAX_AUTHORISATION_STATEMENT_OUTDATED` | 409 | The statement hash or version sent with `grantTaxAuthorisation` is not the text FinBaze would show now. | Load `taxAuthorisationStatement` again, show it and send back its `version` and `hash`. |
| `TAX_NOT_REGISTERED` | 422 | A grant named a tax the company has no obligation for. | Offer only the taxes in `taxAuthorisationStatus`. |
| `FILING_DELEGATED_TO_FIRM` | 403 | The company's accountant files this return, so the company cannot submit it. | Hide the submit button; the accountant files it. |
| `FILER_MUST_BE_INTERMEDIARY` | 400 | The request (the corporate income tax deferral, `nl_cit_uitstel`) can only be filed by a tax intermediary with a BECON number. FinBaze files as a software supplier without a BECON number, so for a company with no accountant it is refused. | Show it as a blocked reason, not a failure: the company's accountant files the deferral. `taxFilingSubmitPreview.blockedReason` carries the same code. |
| `FIRM_NOT_AUTHORISED_FOR_TAX` | 403 | A firm tried to file a tax its engagement does not cover. | The company has to extend the engagement. |
| `STEP_UP_REQUIRED` | 403 | Your `step_up` provider lists this action and no valid confirmation came with the request. `extensions.challenge` is what to confirm. | Confirm the user, sign the assertion and retry with `FinBaze-Step-Up: <challengeId>.<jws>`. See [Delegated actions](/concepts/delegated-actions#step-up). |
| `STEP_UP_CONFIG` |  | The platform's `step_up` provider is not configured completely. | Register the provider with `jwksUrl` (https) or `keys`. |
| `STEP_UP_EXPIRED` |  | The challenge or the assertion is past its lifetime (five minutes for a challenge, `maxAgeSeconds` for an assertion). | Start the action again to get a new challenge, and sign the assertion with a short expiry. |
| `STEP_UP_INVALID` |  | The assertion could not be verified: wrong signature, algorithm, issuer, audience or key id. | Sign with `ES256`, `EdDSA` or `RS256`, `iss` = your platform id, `aud` = `finbaze`, and a `kid` your `jwksUrl` or `keys` serves. |
| `STEP_UP_MISMATCH` |  | The assertion names another challenge, nonce, action or user than the one being confirmed. | Copy `challenge_id`, `nonce` and `action` from the challenge and set `sub` to the user it was for. A challenge works once. |
| `FEATURE_NOT_ALLOWED` |  | The feature a provider or action needs (for example `delegated.step_up`) is not in this platform's allowance. | Ask FinBaze to add it to your allowance. |

## Sending data

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `INVALID_LINE` |  | One object of a call or bulk line could not be processed; `path` points at the field. | Fix the field named in `path` and send the line again. In a bulk job the other lines were applied. |
| `INVALID_METADATA` |  | `metadata` is not up to 50 string values. | Send only strings, at most 50 keys. |
| `UNKNOWN_COMPANY` | 404 | The `company` reference matches no company of your platform. | Use the company's `id` or the `externalId` you gave it. |
| `UNKNOWN_REFERENCE` |  | A reference to another object (a relation, product, project, employment) is not found for this company. | Send the referenced object first, or fix the `externalId`. |
| `FEATURE_DISABLED` | 403 | The company's plan or the platform's limits hide this part of FinBaze, or FinBaze for Platforms is not enabled. | Check the company's effective features (`platformCompanyFeatures`). See [Features and limits](/guides/features-and-limits). |
| `OBJECT_FINALISED` | 409 | The object is final (a finalised invoice, approved hours) and accepts `metadata` only. | Correct a finalised invoice with a credit note (`creditOf`). |
| `OBJECT_DELETED` | 409 | You deleted this object earlier. | Add `restore: true` to bring it back. |
| `UNSUPPORTED_OPERATION` |  | The operation or document kind is not supported yet. | See the operation's description or the changelog for what is available. |
| `TOTAL_MISMATCH` |  | `expectedTotalMinor` differs from what your prices and tax codes add up to. | Check the prices and tax codes. Tax is derived from the tax code, never taken from the line. |
| `AMOUNT_OUT_OF_RANGE` |  | An amount is outside the range FinBaze stores. | Check that amounts are in minor units. |
| `CURRENCY_MISMATCH` |  | A transaction or balance has another currency than its account. | Send each account's currency. |
| `EXTERNAL_ID_TAKEN` |  | `externalId` is already used by another company of your platform. | Use a unique `externalId`, or call again with the same id to get the same company. |
| `LEGAL_NAME_REQUIRED` |  | `legalName` is required when the register lookup has no match. | Send `legalName`. |
| `COMPANY_NOT_FOUND` |  | No such company for your platform. | Check the id. Another platform's company looks the same as one that does not exist. |
| `INGESTION_PAUSED` | 503 | Ingestion is paused. Try again later. | Retry later with the same `Idempotency-Key`. |
| `IDEMPOTENCY_KEY_IN_USE` | 409 | An upload with this `Idempotency-Key` is still in progress. | Wait for it, then read the job; do not send it again. |
| `IDEMPOTENCY_KEY_REUSED` | 409 | This `Idempotency-Key` was used with a different body. | Use a new key for a different body. |
| `PAYLOAD_TOO_LARGE` | 413 | The body is larger than the request limit. | Split the file into several bulk jobs. |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | The content type is not accepted. | Send NDJSON (`application/x-ndjson`, optionally gzip), or the file types the endpoint lists. |
| `UNKNOWN_OBJECT` |  | The bulk job's `object` is not one of the supported names. | Use one of the names the message lists: `relations`, `products`, `projects`, `cost_centers`, `sales_invoices`, `purchase_invoices`, `journal_entries`, `employees`, `employments`, `worked_hours`. |
| `INVALID_PARAMETER` |  | A query parameter is missing or not one of the allowed values. | Fix the parameter the message names. |
| `INVALID_INPUT` |  | An argument is invalid; the message says which. | Fix the argument. |
| `BAD_USER_INPUT` | 400 | An argument failed validation. `extensions.param` names the argument. | Fix the input; the message says what is wrong. |
| `INTERNAL` | 500 | FinBaze could not process the line or run. | Retry with the same ids. If it persists, send the `X-Request-Id` to support. |

## Data sources and feeds

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `DATA_SOURCE_KEY_TAKEN` |  | A data source with this key already exists. | Use the existing source, or another key. |
| `SOURCE_INACTIVE` |  | The data source is paused or retired. | Register a new source, or reactivate it in the portal. |
| `NOT_ATTACHED` |  | The source is not attached to this company. | Call `attachDataSource` for the company first. |
| `UNKNOWN_ACCOUNT` | 404 | The feed account is not known for this company. | Create it with `upsertFeedBankAccount` before sending transactions. |
| `PENDING_NOT_BOOKED` |  | Pending transactions are not accepted. | Send a transaction once the bank has booked it. |
| `IMMUTABLE_TRANSACTION` | 409 | A booked transaction changed after it was delivered. | Send a reversal (`reverses`) and a new transaction instead. |
| `EMPTY_FILE` |  | The statement file is empty. | Check the export. |
| `FILE_TOO_LARGE` | 413 | The statement file is over the size limit. | Split the file. |
| `DESTINATION_KEY_TAKEN` |  | An export destination with this key exists. | Use another key, or update the existing destination. |
| `DESTINATION_IN_USE` |  | An active export schedule still writes to this destination. | Delete or pause the schedule first. |
| `SCHEDULE_KEY_TAKEN` |  | An export schedule with this key exists. | Use another key, or update the schedule. |

## Records and flows

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `UNKNOWN_RECORD_TYPE` |  | A flow template or record names a record type that is not defined. | Define it with `definePlatformRecordType` first. |
| `UNKNOWN_STATE` |  | A trigger names a state that is not a state of the record type. | Use the states you defined. |
| `UNKNOWN_TAX_CODE` |  | A template table names a tax code that does not exist. | Use a code from the tax code list. |
| `UNKNOWN_LEDGER` |  | A ledger the template names does not exist in the company's chart. | Fix the ledger code in `ledgers`, or activate the template for companies whose chart has it. |
| `INVALID_TEMPLATE` |  | The flow template is not valid: the message has the path and line. | Fix the template; `testFlowTemplate` checks it without writing anything. |
| `INVALID_TRANSITION` |  | A record or payment request cannot move to that state from where it is. | Send a state the record type allows from the current one. |
| `CUSTOM_FIELDS_INVALID` |  | Custom field values do not match their definitions. | Check the definitions with `customFieldDefinitions`. |
| `CUSTOM_FIELD_LIMIT` |  | The number of custom field definitions reached the limit. | Archive one you do not use. |

## Messages, policies and extensions

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `FIELD_CONTROL_INVALID` |  | A field control (hidden, read-only, required) is not valid. | Fix the control named in the message. |
| `FIELD_LOCKED` |  | A field is locked by the platform's field controls. | Do not change it from this surface, or lift the control. |
| `COPY_TEMPLATE_INVALID` |  | A message copy template has problems (unknown placeholders, too long, links in model text). | Fix what the message lists; `previewPlatformMessageCopy` renders it first. |
| `ROUTING_NOT_ALLOWED` |  | The message type cannot be routed that way (the catalogue lists the allowed routings per type). | Choose one of the type's allowed routings. |
| `PREFERENCE_LOCKED` |  | Account-security email cannot be switched off. | Leave that preference on. |
| `UNKNOWN_PARTNER_ROLE` |  | The platform has no such role in its `roles_mapping` policy. | Add the role to the policy, or send a role it has. |
| `ROUTING_NOT_CHANGEABLE` |  | Lifecycle, billing and account-security messages are never delivered for platform companies and their routing cannot be changed. | Leave the rule out. See the [message catalogue](/reference/message-catalogue). |
| `POLICY_INVALID` |  | A policy in the bundle is not valid. | Fix the policy the message names. |
| `POLICY_NOT_OVERRIDABLE` |  | This kind of policy cannot be overridden per company. | Change it for the whole platform. |
| `QUOTA_EXCEEDED` |  | The monthly quota of the feature is used up. | Wait for the next month or ask for a higher quota. |
| `FILING_APPROVAL_NOT_ENABLED` |  | Approval applies only to companies of a platform with dual approval. | Enable dual approval in the filing policy first. |
| `FILING_APPROVAL_REQUIRED` |  | The person who prepared a filing cannot approve it. | Let a second person approve it. |
| `FILING_NOT_READY` |  | Only a filing that is ready can be approved. | Finish the draft first. |
| `FILING_SUBMIT_ROLE` |  | The user's role cannot approve tax filings for this company. | Use a user with the role the policy requires. |
| `CUSTOM_ACTION_INVALID` |  | A custom action is not valid. | Fix the definition the message describes. |
| `LINK_TEMPLATE_INVALID` |  | A link template is not valid. | Use an https URL with the placeholders the message lists. |
| `SLOT_INVALID` |  | The extension slot does not exist or does not accept this item. | Use a slot from `platformCustomActions` / the slot list. |

## Webhooks and events

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `ALREADY_DELIVERED` |  | This event was already delivered to the endpoint. | Replay that delivery instead of resending the event. |
| `ENDPOINT_DISABLED` |  | The endpoint is disabled. | Enable it (and fix the cause: a `410 Gone` or repeated failures disable it) before replaying. |

## Payments and delegated actions

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `PROVIDER_NOT_REGISTERED` |  | This platform has no enabled provider for the action. | Register one with `upsertPlatformProvider`. |
| `PROVIDER_CONFIG_INVALID` |  | The provider's configuration is not valid (for example `step_up` needs `jwksUrl` or `keys`). | Fix the configuration the message names. |
| `PROVIDER_KIND_NOT_ENABLED` |  | The payments provider does not handle this kind of request. | Add the kind to the provider's `kinds`. |
| `PAYMENT_REQUEST_EMPTY` |  | The batch has no payable lines (held and blocked lines are excluded). | Release or fix the lines. |
| `PAYMENT_REQUEST_INVALID_LINE` |  | Every line needs a verified IBAN snapshot and a positive amount. | Verify the creditor's bank details in FinBaze. |
| `PAYMENT_REQUEST_NOT_PAYABLE` |  | The filing must be submitted or accepted before it can be paid. | Create the request after the filing is submitted. |
| `PAYMENT_REQUEST_UNSUPPORTED` |  | Only NL VAT and wage tax filings can be paid through a request. | Pay other taxes outside FinBaze. |
| `STATUS_NOT_REPORTABLE` |  | A partner can report `sent`, `accepted`, `scheduled`, `failed` or `cancelled`; `paid` comes from the bank. | Push the bank transaction with its `endToEndId`; the request becomes paid by itself. |
| `PAYMENT_LINK_INVALID` |  | The payment link is not an https URL on one of your `allowedHosts`. | Add the host to the provider config or fix the URL. |

## Accounting firms

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `FIRM_ACCESS_DISABLED` |  | `firm_access` is hidden for the company. | Show the key again ([Features and limits](/guides/features-and-limits)). |
| `FIRM_NOT_FOUND` |  | No firm matches the KvK number or connect code. | Check the number; lookups are exact. |
| `FIRM_HAS_NO_BECON` |  | Taxes were chosen, but the firm has no BECON number. | Offer bookkeeping access only. |
| `FIRM_ENGAGEMENT_STATEMENT_OUTDATED` |  | The statement changed since it was shown. | Read `firmEngagementStatement` again and confirm the new text. |
| `ENGAGEMENT_NOT_PENDING` |  | The request was already answered or expired. | Reload the engagement. |
| `ENGAGEMENT_NOT_ACTIVE` |  | The engagement is not active. | Reload the engagement. |
| `COMPANY_ADMIN_REQUIRED` |  | The user is not an admin of the company. | A company admin has to do this. |
| `FIRM_ADMIN_REQUIRED` |  | The user is not an admin of the firm. | A firm admin has to do this. |
| `FIRM_LOOKUP_RATE_LIMITED` |  | Too many firm lookups or requests for this company. | Wait and try again; limits are per hour. |
| `PLATFORM_END_REASON_NOT_ALLOWED` |  | A platform ended an engagement with a reason that is not in its list. | Use `firm_access_hidden`, `company_closed`, `company_transferred` or `platform_request`. |
| `PLATFORM_COMPANY_USE_ENGAGEMENT` |  | A firm tried to connect a platform company through an invite link, onboarding or `createClient`. | Connect it through an accountant connection: the company invites the firm, or the firm requests access. |
| `NOT_A_PLATFORM_COMPANY` |  | The company does not belong to a platform. | Use the operations for direct companies. |

## Company lifecycle and transfers

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `COMPANY_SUSPENDED` |  | The company is suspended and read-only. | Reactivate it with `reactivatePlatformCompany`. |
| `COMPANY_CLOSED` |  | The company stopped trading; only final returns and exports still work. | Reopen it within the reopen window, or leave it. |
| `COMPANY_ARCHIVED` |  | The company is archived; only exports work. | Export what you need. |
| `INVALID_LIFECYCLE_TRANSITION` |  | The company's state does not allow this move. | Read `lifecycle.state` first. |
| `SUSPENDED_BY_FINBAZE` |  | FinBaze suspended the company; only FinBaze can reactivate it. | Contact support. |
| `INVALID_EFFECTIVE_DATE` |  | The closing date is not valid. | Use a date the closing checklist accepts. |
| `REOPEN_WINDOW_PASSED` |  | The reopen window (90 days by default) has passed. | The company cannot be reopened. |
| `ARCHIVE_BLOCKED` |  | A blocking closing checklist item is open. | Complete it; `companyClosingChecklist` lists them. |
| `FORCE_NOT_ALLOWED` |  | Only FinBaze staff can force this move. | Do not pass `force`. |
| `TRANSFER_CODE_INVALID` |  | The transfer code is wrong, used or unknown (they all fail the same way). | Ask the sending platform for a new code. |
| `TRANSFER_CODE_EXPIRED` |  | The transfer code expired (14 days by default). | Start the transfer again. |
| `TRANSFER_ALREADY_PENDING` |  | The company already has a pending transfer. | Cancel it with `cancelCompanyTransfer`. |
| `TRANSFER_TO_SAME_PLATFORM` |  | The target is the platform that owns the company. | Choose another target. |
| `TRANSFER_WRONG_TARGET` |  | The code is for another kind of target. | Use `acceptCompanyTransfer` for platform codes and the claim link for direct transfers. |
| `TRANSFER_STATEMENT_OUTDATED` |  | The transfer statement changed since it was shown. | Show it again and send the new hash. |
| `TRANSFER_EMAIL_REQUIRED` |  | A transfer to direct FinBaze needs an email address. | Send `email`. |
| `TRANSFER_EMAIL_MISMATCH` |  | The account claiming the company does not have the email the transfer was made for. | Sign in with that address. |

## Support access

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `SUPPORT_ESCALATION_DISABLED` |  | Escalation to FinBaze support is not enabled for the platform. | Switch the support mode in the portal. |
| `ESCALATION_CLOSED` |  | The support escalation is closed. | Open a new one. |
| `SUPPORT_MODE_FINBAZE_DIRECT` |  | Support goes to FinBaze directly for this platform; there is no partner-first step. | Use the escalation form or `createSupportEscalation`. |
| `SUPPORT_NOT_A_PLATFORM_COMPANY` |  | Support access applies to platform companies only. | Use the normal support channels. |
| `SUPPORT_COMPANY_ADMIN_REQUIRED` |  | Only a company admin decides on support access. | Ask an admin. |
| `SUPPORT_GRANT_ALREADY_OPEN` |  | A support access request or grant is already open for the company. | Answer or end the open one first. |
| `SUPPORT_GRANT_NOT_FOUND` |  | No such support access grant. | Check the id. |
| `SUPPORT_GRANT_NOT_PENDING` |  | The grant was already answered. | Reload it. |
| `SUPPORT_GRANT_NOT_ACTIVE` |  | The grant is not active (expired, revoked or declined). | Ask for a new one. |
| `SUPPORT_GRANT_REQUIRED` |  | FinBaze staff need the company's consent before viewing it. | Approve the request in `support-access`. |
| `SUPPORT_GRANT_READ_ONLY` |  | Support access is read-only. | Support staff cannot change data. |
| `SUPPORT_GRANT_DENIED_OPERATION` |  | The operation is not available through support access. | Support staff cannot do this on the company's behalf. |
| `SUPPORT_ATTESTATION_REQUIRED` |  | A break-glass access needs the staff member's attestation. | Add the attestation. |
| `SUPPORT_BREAK_GLASS_SECOND_ADMIN_REQUIRED` |  | Break-glass access needs a second FinBaze admin to confirm. | Ask a second admin. |
| `INVALID_DURATION` |  | The access duration is outside the allowed range. | Choose a shorter or longer period. |
| `INVALID_REASON` |  | The reason is missing or not one of the allowed values. | Send a reason. |

## Sandbox

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `TEST_CLOCK_NOT_FOUND` |  | No such test clock for your platform. | List clocks with `testClocks`. |
| `TEST_CLOCK_LIMIT` |  | The platform reached its maximum number of test clocks. | Delete one with `deleteTestClock`. |
| `TEST_CLOCK_BACKWARDS` |  | A test clock only moves forward. | Create a new clock for an earlier time. |
| `TEST_CLOCK_RANGE_TOO_LARGE` |  | The requested advance is longer than the maximum (400 days by default). | Advance in several steps. |
| `TEST_CLOCK_BUSY` |  | The clock is still advancing. | Wait until its status is `ready` again. |
| `SANDBOX_ONLY` |  | This operation (test clocks, demo companies, sample apps, the reset) is available in the sandbox only. | Call the sandbox API (`https://sandbox.api.platform.finbaze.com`) with a test key. |
| `SANDBOX_RESET_RUNNING` |  | A reset of this sandbox is already running. | Wait for it to finish. |
| `SANDBOX_SIGN_IN_ONLY` |  | Sandbox access is through your production FinBaze account. | Sign in with your production account. |
| `MIRRORED_FROM_PRODUCTION` |  | This sandbox object mirrors production and cannot be changed in the sandbox. | Change it in production. |

## Platform, keys and limits

| Code | HTTP | Meaning | What to do |
| --- | --- | --- | --- |
| `KEY_LIMIT_REACHED` |  | A platform can have at most 10 active keys per environment. | Revoke a key you no longer use. |
| `RATE_LIMITED` | 429 | Too many requests in the window (also: 5 sample apps a day). | Back off and retry. |
| `FORBIDDEN` | 403 | The key or token may not do this. | Check the key's scopes and the company's features. |
| `NOT_FOUND` | 404 | The object does not exist for your platform. Another platform's object looks the same. | Check the id. |
| `CONFLICT` | 409 | The request conflicts with the current state. | Read the object and decide again. |
| `UNPROCESSABLE` | 422 | The request is well-formed but cannot be processed. | Read the message. |
| `UNAVAILABLE` | 503 | The service cannot answer now. | Retry with the same idempotency key. |

## In the browser SDK

`FinBazeEmbedError` has the same `code` values plus the `message`. Pass `onError` to `loadFinBaze` to receive them; per-component failures also arrive as the component's `error` event.


---

<!-- /reference/message-catalogue -->
# Message catalogue

Every message FinBaze can send or hand to you, its default routing and what you may change.

Generated from the catalogue the API runs on (61 types). See [Messages](/concepts/messages) for how routing, acknowledgement and quiet hours work.

**Routing values.** `finbaze_sends`: FinBaze emails the user. `partner_delivers`: you receive `message.created` and deliver it in your own channels. `both`. `suppress`. Types marked *fixed* cannot be changed (`ROUTING_NOT_CHANGEABLE`); lifecycle, billing and internal messages are never sent for platform companies.

## Account security

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `account.email_verification` | company_user, firm_user | critical | `finbaze_sends` | *fixed* | `verifyUrl: string`, `locale?: string` |
| `account.membership_invite` | prospect | normal | `suppress` | *fixed* | `inviteUrl: string`, `resourceName: string`, `permissionLabel: string`, `locale: string` |
| `account.password_reset` | company_user, firm_user | critical | `finbaze_sends` | *fixed* | `resetUrl: string`, `locale?: string` |

## Tax deadlines

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `tax_authorisation.revoked` | company_user | normal | `partner_delivers` | any | `companyId: string`, `taxes: string[]`, `revokedVia?: any`, `language: string` |
| `tax.deadline_upcoming` | company_user | normal (or critical) | `partner_delivers` | any | `filingId: string`, `language: string`, `daysLeft: number` |
| `tax.filing_accepted` | company_user | normal | `partner_delivers` | any | `filingId: string`, `language: string` |
| `tax.filing_ready` | company_user | critical | `partner_delivers` | any | `filingId: string`, `language: string` |
| `tax.filing_rejected` | company_user | critical | `partner_delivers` | any | `filingId: string`, `language: string`, `reason?: string` |
| `tax.threshold_approaching` | company_user | normal | `partner_delivers` | any | `language: string`, `obligationLabel: string`, `usedAmount: number`, `limitAmount: number`, `taxesUrl: string` |
| `tax.threshold_exceeded` | company_user | critical | `partner_delivers` | any | `language: string`, `obligationLabel: string`, `usedAmount: number`, `limitAmount: number`, `taxesUrl: string` |

## Documents

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `documents.inbound_unsorted` | external_sender | normal | `finbaze_sends` | `finbaze_sends`, `suppress` | `replyTo: string`, `purchaseEmail: string`, `salesEmail: string`, `lettersEmail: string`, `locale?: any` |
| `documents.receipt_missing` | company_user | digestible | `partner_delivers` | any | `transactionId: string` |
| `documents.received_available` | company_user | normal | `partner_delivers` | any | `documentId: string`, `language: string` |
| `documents.request_digest` | company_user | digestible | `partner_delivers` | any | `language: string`, `isReminder?: boolean`, `requests: object[]` |
| `documents.request_reminder` | company_user | normal | `partner_delivers` | any | `language: string`, `isReminder?: boolean`, `requests: object[]` |

## Approvals

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `agents.task_waiting_approval` | company_user, firm_user | critical | `partner_delivers` | any | `title: string`, `subject: string`, `body: string`, `replyTo?: string` |
| `approvals.pay_run_ready` | company_user | critical | `partner_delivers` | any | `payRunId: string` |

## Sales correspondence

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `sales.invoice_payment_failed` | company_customer | normal | `finbaze_sends` | any | `entityId: string` |
| `sales.invoice_payment_received` | company_customer | normal | `finbaze_sends` | any | `entityId: string` |
| `sales.invoice_sent` | company_customer | normal, evidence | `finbaze_sends` | any | `entityId: string` |
| `sales.quote_sent` | company_customer | normal | `finbaze_sends` | any | `entityId: string` |
| `sales.recurring_invoice` | company_customer | normal | `finbaze_sends` | any | `entityId: string` |
| `sales.reminder_sent` | company_customer | normal, evidence | `finbaze_sends` | any | `entityId: string` |

## Payroll correspondence

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `payroll.payslip_available` | employee | normal, evidence | `finbaze_sends` | any | `entityId: string`, `language: string` |
| `payroll.year_document_available` | employee | normal, evidence | `finbaze_sends` | any | `entityId: string`, `language: string` |

## Ai agents

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `agents.task_budget_exhausted` | company_user, firm_user | normal | `partner_delivers` | any | `title: string`, `subject: string`, `body: string`, `replyTo?: string` |
| `agents.task_completed` | company_user, firm_user | normal | `partner_delivers` | any | `title: string`, `subject: string`, `body: string`, `replyTo?: string` |
| `agents.task_failed` | company_user, firm_user | normal | `partner_delivers` | any | `title: string`, `subject: string`, `body: string`, `replyTo?: string` |
| `agents.task_waiting_input` | company_user, firm_user | normal | `partner_delivers` | any | `title: string`, `subject: string`, `body: string`, `replyTo?: string` |
| `assistant.inbound_reply` | external_sender, company_user | normal | `finbaze_sends` | `finbaze_sends`, `suppress` | `replyTo: string`, `subject: string`, `body: string`, `inReplyTo?: string`, `references?: string[]` |

## Billing

FinBaze's own conversation with its customers. Never delivered for platform companies.

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `billing.firm_client_plan_activated` | firm_user, company_user | normal | `suppress` | *fixed* | `language: string`, `clientName: string`, `planName: string`, `audience: string` |
| `billing.firm_client_plan_cancelled` | company_user | normal | `suppress` | *fixed* | `language: string`, `clientName: string`, `planName: string`, `canceledAt: any`, `accessUntil: any` |
| `billing.firm_client_subscription_cancelled` | firm_user | normal | `suppress` | *fixed* | `clientProfileId: string`, `planName: string`, `canceledAt: any`, `accessUntil: any`, `minimumTermEndsAt: any`, `minimumTermMonths: number` |
| `billing.payroll_addon_enabled` | company_user | normal | `suppress` | *fixed* | `language: string`, `companyName: string`, `payrollUrl: string` |
| `billing.plan_upgrade_request` | company_user | normal | `suppress` | *fixed* | `subject: string`, `body: string` |

## Lifecycle marketing

FinBaze's own conversation with its customers. Never delivered for platform companies.

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `lifecycle.founder_checkin` | company_user | normal | `suppress` | *fixed* | `language: string`, `meetingUrl: string`, `unsubscribeUrl: string`, `signatureName: string`, `from: object` |
| `lifecycle.onboarding_resume` | company_user | normal | `suppress` | *fixed* | `language: string`, `copyKey: string`, `buttonUrl: string`, `unsubscribeUrl: string` |
| `lifecycle.plan_welcome` | company_user | normal | `suppress` | *fixed* | `language: string`, `companyName: string`, `planName: string`, `trialDays: number`, `trialEndsAt: any`, `dashboardUrl: string`, `firstName?: any` |
| `lifecycle.platform_onboarding_invite` | prospect | normal | `suppress` | *fixed* | `inviteUrl: string`, `contactName?: any`, `message?: any`, `locale?: string` |
| `lifecycle.practice_invoice` | company_user | normal | `suppress` | *fixed* | `profileId: string` |
| `lifecycle.setup_step` | company_user | normal | `suppress` | *fixed* | `language: string`, `copyKey: string`, `buttonUrl: string`, `unsubscribeUrl: string` |

## Banking

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `banking.lunchflow_consent` | company_user | normal | `partner_delivers` | any | `language: string`, `variant: string`, `accountNames: string[]`, `reconnectUrl: string` |

## Insights

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `insights.budget_run_rate_digest` | company_user | digestible | `partner_delivers` | any | `language: string`, `items: object[]`, `budgetsUrl: string` |
| `platform_ops.alert` | platform_ops | normal | `suppress` | *fixed* | `platformName: string`, `title: string`, `detail: string`, `severity: string`, `portalUrl: string`, `locale?: string` |

## Firm relations

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `company.transfer_claim` | prospect | normal | `finbaze_sends` | *fixed* | `claimUrl: string`, `companyName: string`, `platformName: string`, `language?: string` |
| `firm.access_requested` | company_user | normal | `partner_delivers` | any | `engagementId: string`, `firmId: string`, `firmName: string`, `message?: any`, `contactEmail?: any`, `expiresAt: any`, `language?: string` |
| `firm.client_connect_invite` | company_user | normal | `partner_delivers` | any | `connectUrl: string`, `language?: string` |
| `firm.client_hmrc_removal_notice` | company_user | normal | `suppress` | *fixed* | `previousBookkeeperName: string`, `newBookkeeperName: string`, `hmrcServices: string[]` |
| `firm.client_onboarding_invite` | prospect | normal | `suppress` | *fixed* | `joinUrl: string`, `language?: string` |
| `firm.client_onboarding_resume` | prospect | normal | `suppress` | *fixed* | `joinUrl: string`, `language?: string` |
| `firm.client_transferred_away` | firm_user | normal | `finbaze_sends` | *fixed* | `clientProfileId: string`, `newBookkeeperName: string`, `hmrcServices?: string[]` |
| `firm.engagement_company_notice` | company_user | normal | `partner_delivers` | any | `kind: string`, `engagementId: string`, `firmId: string`, `firmName: string`, `taxes: string[]`, `reason?: any`, `endsAt?: any`, `hmrcServices?: string[]`, `language?: string` |
| `firm.engagement_firm_notice` | firm_user | normal | `finbaze_sends` | *fixed* | `kind: string`, `engagementId: string`, `companyId: string`, `companyName: string`, `platformName: string`, `taxes: string[]`, `reason?: any`, `endsAt?: any`, `language?: string` |
| `support.access_requested` | company_user | normal | `partner_delivers` | any | `grantId: string`, `reason: string`, `scope: string`, `durationMinutes: number`, `title?: string`, `summary?: string`, `language?: string` |

## Custom

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `custom.automation_email` | company_user, company_customer | normal | `finbaze_sends` | any | `subject: string`, `heading: string`, `body: string` |
| `custom.automation_whatsapp` | company_user, company_customer | normal | `suppress` | `suppress`, `finbaze_sends` | `text: string` |
| `custom.notification` | company_user, firm_user | normal | `partner_delivers` | any | `sender: any`, `subject: string`, `body: string`, `replyTo?: any` |
| `purchase.order_sent` | company_customer | normal, evidence | `finbaze_sends` | `finbaze_sends`, `suppress` | `purchaseOrderId: string`, `subject: string`, `heading: string`, `body: string`, `replyTo?: any` |
| `purchase.supplier_email` | company_customer | normal | `finbaze_sends` | `finbaze_sends`, `suppress` | `subject: string`, `body: string`, `replyTo?: any` |

## Internal

FinBaze's own conversation with its customers. Never delivered for platform companies.

| Type | To | Priority | Default for you | Change | Data |
| --- | --- | --- | --- | --- | --- |
| `internal.plan_subscribed` | finbaze_internal | normal | `suppress` | *fixed* | `companyName: string`, `legalName: string`, `planName: string`, `priceCents: number`, `dashboardUrl: string`, `trialEndsAt: any` |
| `internal.support_escalation` | finbaze_internal | normal | `suppress` | *fixed* | `kind: string`, `escalationId: string`, `platformName: string`, `subject: string`, `severity: string`, `source: string`, `description: string`, `adminUrl: string`, `companyName?: any`, `comment?: any`, `requestIds?: string[]`, `screen?: any`, `contactEmail?: any` |


---

<!-- /reference/webhook-events -->
# Webhook events

The envelope and signature of every webhook, and the catalogue of events with sample payloads.

Generated from the event catalogue the API runs on: 126 events are available, 2 are planned (registered, not sent yet; `platformEventCatalog` shows the status). Concepts, retries and replay: [Events and webhooks](/concepts/events-and-webhooks).

## The envelope

Every delivery is a `POST` with a JSON body:

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "bank_transaction.booked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

| Field |  |
| --- | --- |
| `id` | `evt_…`, the event id. Dedupe on it. |
| `type` | The event type. |
| `apiVersion` | The API version the payload is written in. |
| `created`, `occurredAt` | When FinBaze recorded the event, and when it happened. |
| `sequence` | A string that grows with every event. Use it to order; gaps are normal. |
| `livemode` | `false` in the sandbox. |
| `platform` | Your platform id. |
| `company` | `{ id, externalId }` of the company, or `null` for platform-level events. |
| `request` | `{ id }` of the request that caused it, when there was one (the `X-Request-Id`). |
| `data.object` | A snapshot of the object as of the event, or the event's own fields. |
| `data.details` | Event-specific fields beside the snapshot, for events that define them. |

## Headers and signature

| Header |  |
| --- | --- |
| `X-FinBaze-Signature` | `t=<unix seconds>,v1=<hex>[,v1=<hex>]`: HMAC-SHA256 of `<t>.<raw body>` keyed with the endpoint's `whsec_…` secret. Two `v1` values while a secret rotates. |
| `X-FinBaze-Event`, `X-FinBaze-Event-Id`, `X-FinBaze-Event-Sequence` | Type, id and sequence, so you can route before parsing. |
| `X-FinBaze-Delivery` | The delivery id (one event can have several deliveries). |
| `X-FinBaze-Timestamp` | The unix timestamp used in the signature. |
| `X-FinBaze-Api-Version` | The API version of the payload. |
| `X-FinBaze-Replay` | `1` on a replayed delivery. |

Accept timestamps within 5 minutes. Verification code in Node, Python and PHP: [webhook receivers](/guides/sample-apps).

Planned events are listed so you can see what is coming; you cannot subscribe to them yet.

## [Companies, users and sessions](/reference/webhook-events/companies)

Company lifecycle and transfers, platform users, access requests from your users, embed sessions.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `company.archived` | available | `company` |  | A closed company was archived: users removed, consents revoked, retention date set. |
| `company.closed` | available | `company` |  | A company was closed: obligations end at the effective date; final returns and exports stay possible. |
| `company.created` | available | `company` |  | A company was created for the platform. |
| `company.features.updated` | available | `company` |  | The features available to a company changed (allowance or limits). |
| `company.reactivated` | available | `company` |  | A suspended company was reactivated. |
| `company.reopened` | available | `company` |  | A closed company was reopened (or an archived one restored as closed by FinBaze). |
| `company.requirements.updated` | available | `company` |  | What a company still has to provide changed (for now: its filing authorisation, `tax_*_authorisation`). `data.details.reason` says why. |
| `company.suspended` | available | `company` |  | A company was suspended (read-only; no filings, automations or outbound mail). |
| `company.transfer.cancelled` | available | none |  | A pending transfer was cancelled. |
| `company.transfer.created` | available | none |  | The company admin started a transfer to another platform or to direct FinBaze. |
| `company.transferred_in` | available | `company` |  | A company arrived from another platform. Set up its users and collect consent again. |
| `company.transferred_out` | available | none |  | A company left the platform (to another platform or to direct FinBaze). The last event the platform receives for it. |
| `company.updated` | available | `company` |  | A company's details changed. |
| `embed_session.used` | available | `embed_session` |  | An embed session was exchanged for a token. |
| `platform_user.created` | available | `platform_user` |  | A platform user was created. |
| `platform_user.deactivated` | available | `platform_user` |  | A platform user was deactivated. |
| `platform_user.deprovisioned` | available | `platform_user` |  | A platform user was deprovisioned: access removed and every token revoked. |
| `user.invite_requested` | available | `user_access_request` |  | A company admin asked, in users-and-access, to give someone access. FinBaze sends no invitation and creates no account: the platform decides. |
| `user.removal_requested` | available | `user_access_request` |  | A company admin asked to remove someone’s access. The access stays until the platform calls removePlatformUserAccess. |
| `user.role_change_requested` | available | `user_access_request` |  | A company admin asked to change a person’s role. Nothing changes until the platform calls setPlatformUserAccess. |

## [Bookkeeping](/reference/webhook-events/bookkeeping)

Invoices, quotes, relations and bank transactions.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `attachment.matched` | planned | `process_document` | `process_documents` | A document was matched to a transaction. |
| `bank_account.created` | available | `bank_account` | `banking` | A bank account was added to a company. |
| `bank_account.updated` | available | `bank_account` | `banking` | A bank account changed. |
| `bank_transaction.booked` | available | `bank_transaction` | `banking` | A bank transaction was booked. |
| `bank_transaction.created` | available | `bank_transaction` | `banking` | A bank transaction arrived (feed, file or import). |
| `bank_transaction.needs_receipt` | available | `bank_transaction` | `banking` | A booked transaction still needs a receipt. |
| `bank_transaction.needs_review` | available | `bank_transaction` | `banking` | A transaction needs a person to look at it. |
| `bank_transaction.unbooked` | available | `bank_transaction` | `banking` | The booking of a bank transaction was undone. |
| `journal_entry.created` | available | `journal_entry` | `settlements` | A journal entry was booked through the platform API. |
| `purchase_invoice.approved` | available | `purchase_invoice` | `purchase_invoices` | A purchase invoice was approved. |
| `purchase_invoice.created` | available | `purchase_invoice` | `purchase_invoices` | A purchase invoice was received or created. |
| `purchase_invoice.due` | available | `purchase_invoice` | `purchase_invoices` | A purchase invoice is due. |
| `purchase_invoice.paid` | available | `purchase_invoice` | `purchase_invoices` | A purchase invoice was paid. |
| `purchase_invoice.processed` | available | `purchase_invoice` | `purchase_invoices` | A purchase invoice was processed. |
| `quote.accepted` | available | `quote` | `quotes` | A quote was accepted. |
| `quote.sent` | available | `quote` | `quotes` | A quote was sent. |
| `relation.bank_account_changed` | available | `relation` | `relations` | The bank account of a relation changed. |
| `relation.created` | available | `relation` | `relations` | A relation was created. |
| `relation.updated` | available | `relation` | `relations` | A relation changed. |
| `reminder.paid` | available | `reminder` | `reminders` | A reminder was paid. |
| `reminder.sent` | available | `reminder` | `reminders` | A payment reminder was sent. |
| `sales_invoice.created` | available | `sales_invoice` | `sales_invoices` | A sales invoice was created through the platform API. |
| `sales_invoice.credited` | available | `sales_invoice` | `sales_invoices` | A sales invoice was credited. |
| `sales_invoice.finalised` | available | `sales_invoice` | `sales_invoices` | A sales invoice was numbered and booked. |
| `sales_invoice.overdue` | available | `sales_invoice` | `sales_invoices` | A sales invoice is overdue. |
| `sales_invoice.paid` | available | `sales_invoice` | `sales_invoices` | A sales invoice was paid. |
| `sales_invoice.sent` | available | `sales_invoice` | `sales_invoices` | A sales invoice was sent. |

## [Data in](/reference/webhook-events/data-in)

Bulk jobs, data sources, feed health, records and flow runs.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `bulk_job.completed` | available | `bulk_job` |  | A bulk job finished. |
| `bulk_job.failed` | available | `bulk_job` |  | A bulk job failed. |
| `data_source_file.failed` | available | `data_source_file` |  | A statement file could not be processed. |
| `data_source_file.processed` | available | `data_source_file` |  | A statement file was processed. |
| `data_source.backfill_completed` | available | `data_source_attachment` |  | The history of a data source finished loading. |
| `data_source.resync_requested` | available | `data_source_attachment` |  | A person in the partner portal asked for a period of a company to be delivered again. `data.object.from` and `data.object.to` name the days; deliver them with the usual feed calls. |
| `feed.balance_mismatch` | available | `feed_account` | `banking` | A delivered balance does not match the transactions. |
| `feed.delayed` | available | `feed_account` | `banking` | A bank feed is later than usual. |
| `feed.gap_detected` | available | `feed_account` | `banking` | A bank feed stopped delivering. |
| `feed.recovered` | available | `feed_account` | `banking` | A bank feed is healthy again. |
| `flow_run.failed` | available | `flow_run` | `custom_records` | A flow template failed. |
| `flow_run.succeeded` | available | `flow_run` | `custom_records` | A flow template ran. |
| `record.created` | available | `custom_record` | `custom_records` | A custom record was created. |
| `record.transitioned` | available | `custom_record` | `custom_records` | A custom record moved to another state. |
| `record.updated` | available | `custom_record` | `custom_records` | A custom record changed. |

## [Tax](/reference/webhook-events/tax)

Filings, consent, payments and reservations.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `tax_authorisation.granted` | available | `tax_authorisation` | `tax_filings` | A company user authorised FinBaze to file the listed taxes (`companyId`, `taxes`, `channel`, `stepUp`, `at`). No IP or user agent. |
| `tax_authorisation.revoked` | available | `tax_authorisation` | `tax_filings` | A filing authorisation was revoked for the listed taxes (`channel` is how: embed, headless, platform, admin or lifecycle). |
| `tax_filing.accepted` | available | `tax_filing` | `tax_filings` | A tax return was accepted. |
| `tax_filing.draft_ready` | available | `tax_filing` | `tax_filings` | A tax return draft is ready. |
| `tax_filing.paid` | available | `tax_filing` | `tax_filings` | The payment of a tax return was matched. |
| `tax_filing.ready` | available | `tax_filing` | `tax_filings` | A tax return is ready to be submitted. |
| `tax_filing.rejected` | available | `tax_filing` | `tax_filings` | A tax return was rejected. |
| `tax_filing.submitted` | available | `tax_filing` | `tax_filings` | A tax return was submitted. |
| `tax_payment.due` | available | `tax_filing` | `tax_filings` | A tax payment is due. |
| `tax_payment.overdue` | available | `tax_filing` | `tax_filings` | A tax payment is overdue. |
| `tax_reservation.advised` | available | none |  | A new tax reservation advice was computed. |
| `tax_signal.created` | available | `tax_signal` | `ai.tax.signals` | A tax signal was raised. |

## [Payroll](/reference/webhook-events/payroll)

Pay runs and payslips.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `pay_run.approved` | available | `pay_run` | `payroll` | A pay run was approved. |
| `pay_run.calculated` | available | `pay_run` | `payroll` | A pay run was calculated. |
| `pay_run.paid` | available | `pay_run` | `payroll` | A pay run was paid. |
| `payslip.finalised` | available | `payslip` | `payroll` | A payslip was finalised. |

## [Documents and messages](/reference/webhook-events/documents-messages)

Documents and rendering, messages, exports, domains.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `custom_action.invoked` | available | none |  | A user invoked one of your custom actions. |
| `custom_domain.status_changed` | available | `custom_domain` |  | A custom domain for public pages changed status. |
| `document_request.cancelled` | available | `document_request` | `document_requests` | A document request was cancelled. |
| `document_request.created` | available | `document_request` | `document_requests` | A document request was created. |
| `document_request.fulfilled` | available | `document_request` | `document_requests` | A document request was fulfilled. |
| `document.failed` | available | `process_document` | `process_documents` | A document could not be processed. |
| `document.needs_review` | planned | `process_document` | `process_documents` | A document needs a person to look at it. |
| `document.official_copy_created` | available | none |  | The official copy of a document was stored. |
| `document.processed` | available | `process_document` | `process_documents` | A document was processed. |
| `document.received` | available | `process_document` | `process_documents` | A document was received. |
| `document.render_failed` | available | none |  | A custom template or partner render failed or timed out; FinBaze used its own layout. |
| `document.render_rejected` | available | none |  | A PDF the platform rendered failed the required-content checks; FinBaze used its own layout. |
| `document.render_requested` | available | none |  | A document needs to be rendered by the platform. The payload has the data model and signed links to files that go with it (the invoice UBL), valid 15 minutes. |
| `export.destination_expiring` | available | `export_destination` | `data_export` | Credentials of an export destination expire soon. |
| `export.failed` | available | `export_run` | `data_export` | A scheduled export failed. |
| `export.ready` | available | `export_run` | `data_export` | A scheduled export is ready. |
| `message.created` | available | none |  | A message needs to be delivered by the platform. |
| `message.unacknowledged` | available | none |  | A delivered message was not acknowledged in time. |

## [Delegated actions](/reference/webhook-events/delegated)

Payment requests, payment links and step-up challenges.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `payment_link.requested` | available | none |  | A payment link is needed for an invoice. |
| `payment_request.created` | available | none |  | A payment request was created; pay it and use the end-to-end id. |
| `payment_request.paid` | available | none |  | The bank transaction of a payment request was matched. |
| `payment_request.updated` | available | none |  | A payment request changed status. |
| `step_up.required` | available | none |  | A step-up confirmation is required for a high-risk action. |

## [Accounting firms](/reference/webhook-events/firms)

Accountant connections.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `firm.access_requested` | available | `firm_engagement` |  | An accounting firm asked for access to a company. Show the request in your own UI; the company decides in accountant-connect. |
| `firm.authority_changed` | available | `firm_engagement` |  | The company changed which taxes the firm files. |
| `firm.connected` | available | `firm_engagement` |  | An accounting firm now works the company in the FinBaze firm dashboard. |
| `firm.connection_declined` | available | `firm_engagement` |  | A request between a company and a firm was declined (or withdrawn). |
| `firm.connection_expired` | available | `firm_engagement` |  | A request between a company and a firm expired after 14 days without an answer. |
| `firm.connection_requested` | available | `firm_engagement` |  | A company invited an accounting firm; the firm has not accepted yet. |
| `firm.disconnect_scheduled` | available | `firm_engagement` |  | The engagement ends at a set time because accountant access was hidden for the company; the key can still be shown again to cancel it. |
| `firm.disconnected` | available | `firm_engagement` |  | The engagement ended: firm access, BECON use and HMRC client authorisations stopped; the books stay with the company. |

## [Support](/reference/webhook-events/support)

Support requests, escalations and consented access.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `support.access_expired` | available | `support_access_grant` |  | A support grant reached its end. |
| `support.access_granted` | available | `support_access_grant` |  | A support access request was approved; FinBaze support can view the company until `expiresAt`. |
| `support.access_requested` | available | `support_access_grant` |  | FinBaze support asked to view a company. The company admin decides. |
| `support.access_revoked` | available | `support_access_grant` |  | A live support grant was ended early. |
| `support.break_glass` | available | `support_access_grant` |  | FinBaze opened a company without consent (two admins, read only, at most two hours). |
| `support.escalation.created` | available | `support_escalation` |  | An escalation to FinBaze support was created. |
| `support.escalation.updated` | available | `support_escalation` |  | An escalation changed status or severity, or got a comment. |
| `support.requested` | available | `support_request` |  | A company user asked for help in contact-support and the platform handles support (`partner_first`). |

## [Platform: policies, quotas and agents](/reference/webhook-events/platform)

Policy changes, quotas, usage reports, partner alerts and agent tasks.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `agent_task.completed` | available | `agent_task` | `ai.agents` | An agent task completed. |
| `agent_task.failed` | available | `agent_task` | `ai.agents` | An agent task failed. |
| `agent_task.waiting_approval` | available | `agent_task` | `ai.agents` | An agent task waits for approval. |
| `agent_task.waiting_input` | available | `agent_task` | `ai.agents` | An agent task waits for input. |
| `billing.usage.reported` | available | `platform_usage` |  | The month's usage was closed and reported. |
| `platform.alert` | available | `platform_alert` |  | Something needs the platform's attention: a failing or disabled webhook endpoint, a stalled feed, a rejected filing. |
| `policy.activated` | available | `platform_policy` |  | A policy version was activated (also by a promotion). |
| `quota.reached` | available | none |  | A company reached one of its quotas for the month. |

## [Sandbox](/reference/webhook-events/sandbox)

Test clocks and the sandbox reset.

| Event | Status | Object | Module |  |
| --- | --- | --- | --- | --- |
| `sandbox.reset.completed` | available | `sandbox_reset` |  | The nightly or manual reset of the platform sandbox finished (sandbox only). |
| `test_clock.failed` | available | `test_clock` |  | A test clock stopped because the advance failed (sandbox only). |
| `test_clock.ready` | available | `test_clock` |  | A test clock finished advancing (sandbox only). |


---

<!-- /reference/webhook-events/companies -->
# Webhook events: Companies, users and sessions

Company lifecycle and transfers, platform users, access requests from your users, embed sessions. Payload samples.

Company lifecycle and transfers, platform users, access requests from your users, embed sessions. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## company.archived

A closed company was archived: users removed, consents revoked, retention date set.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "company.archived",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "from": "active",
      "to": "active",
      "retentionUntil": "2026-03-02",
      "forced": false,
      "usersRemoved": 1,
      "engagementsEnded": 1,
      "authorisationsRevoked": 1
    }
  }
}
```

## company.closed

A company was closed: obligations end at the effective date; final returns and exports stay possible.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "company.closed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "from": "active",
      "to": "active",
      "effectiveDate": "2026-03-02",
      "reason": "example",
      "obligationsEnded": 1
    }
  }
}
```

## company.created

A company was created for the platform.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "company.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## company.features.updated

The features available to a company changed (allowance or limits).

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "company.features.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## company.reactivated

A suspended company was reactivated.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "company.reactivated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "from": "active",
      "to": "active"
    }
  }
}
```

## company.reopened

A closed company was reopened (or an archived one restored as closed by FinBaze).

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "company.reopened",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "from": "active",
      "to": "active",
      "obligationsRestored": 1,
      "obligationsSkipped": 1,
      "restored": false
    }
  }
}
```

## company.requirements.updated

What a company still has to provide changed (for now: its filing authorisation, `tax_*_authorisation`). `data.details.reason` says why.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "company.requirements.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## company.suspended

A company was suspended (read-only; no filings, automations or outbound mail).

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "company.suspended",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "from": "active",
      "to": "active",
      "suspendedBy": "platform",
      "reason": "example",
      "displayMessage": "example",
      "takenOverBy": "finbaze"
    }
  }
}
```

## company.transfer.cancelled

A pending transfer was cancelled.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b18",
  "object": "event",
  "type": "company.transfer.cancelled",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1008",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "transferId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "target": "direct"
    }
  }
}
```

## company.transfer.created

The company admin started a transfer to another platform or to direct FinBaze.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b19",
  "object": "event",
  "type": "company.transfer.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1009",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "by": "platform",
      "transferId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "target": "direct",
      "expiresAt": "example"
    }
  }
}
```

## company.transferred_in

A company arrived from another platform. Set up its users and collect consent again.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b20",
  "object": "event",
  "type": "company.transferred_in",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1010",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "transferId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "fromPlatformId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## company.transferred_out

A company left the platform (to another platform or to direct FinBaze). The last event the platform receives for it.

Object: none (the event's own fields) · delivered to the former owner of a company that moved on.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b21",
  "object": "event",
  "type": "company.transferred_out",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1011",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": null,
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "transferId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "target": "direct"
    }
  }
}
```

## company.updated

A company's details changed.

Object: `company`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b22",
  "object": "event",
  "type": "company.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1012",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Company",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## embed_session.used

An embed session was exchanged for a token.

Object: `embed_session`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b23",
  "object": "event",
  "type": "embed_session.used",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1013",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "EmbedSession",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## platform_user.created

A platform user was created.

Object: `platform_user`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b24",
  "object": "event",
  "type": "platform_user.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1014",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PlatformUser",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## platform_user.deactivated

A platform user was deactivated.

Object: `platform_user`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b25",
  "object": "event",
  "type": "platform_user.deactivated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1015",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PlatformUser",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## platform_user.deprovisioned

A platform user was deprovisioned: access removed and every token revoked.

Object: `platform_user`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b26",
  "object": "event",
  "type": "platform_user.deprovisioned",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1016",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PlatformUser",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    },
    "details": {
      "externalUserId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "anonymised": false,
      "companiesRemoved": 1
    }
  }
}
```

## user.invite_requested

A company admin asked, in users-and-access, to give someone access. FinBaze sends no invitation and creates no account: the platform decides.

Object: `user_access_request`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b27",
  "object": "event",
  "type": "user.invite_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1017",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "requestedBy": "example",
      "note": "example",
      "email": "name@example.com",
      "role": "admin"
    }
  }
}
```

## user.removal_requested

A company admin asked to remove someone’s access. The access stays until the platform calls removePlatformUserAccess.

Object: `user_access_request`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b28",
  "object": "event",
  "type": "user.removal_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1018",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "requestedBy": "example",
      "note": "example",
      "userId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "email": "name@example.com"
    }
  }
}
```

## user.role_change_requested

A company admin asked to change a person’s role. Nothing changes until the platform calls setPlatformUserAccess.

Object: `user_access_request`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b29",
  "object": "event",
  "type": "user.role_change_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1019",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "requestedBy": "example",
      "note": "example",
      "userId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "email": "name@example.com",
      "role": "admin"
    }
  }
}
```


---

<!-- /reference/webhook-events/bookkeeping -->
# Webhook events: Bookkeeping

Invoices, quotes, relations and bank transactions. Payload samples.

Invoices, quotes, relations and bank transactions. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## attachment.matched

A document was matched to a transaction.

> **Planned**
>
> Not sent yet; registered so you can see it coming.

Object: `process_document` · module `process_documents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "attachment.matched",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ProcessDocument",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_account.created

A bank account was added to a company.

Object: `bank_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "bank_account.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_account.updated

A bank account changed.

Object: `bank_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "bank_account.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_transaction.booked

A bank transaction was booked.

Object: `bank_transaction` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "bank_transaction.booked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_transaction.created

A bank transaction arrived (feed, file or import).

Object: `bank_transaction` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "bank_transaction.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_transaction.needs_receipt

A booked transaction still needs a receipt.

Object: `bank_transaction` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "bank_transaction.needs_receipt",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_transaction.needs_review

A transaction needs a person to look at it.

Object: `bank_transaction` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "bank_transaction.needs_review",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bank_transaction.unbooked

The booking of a bank transaction was undone.

Object: `bank_transaction` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "bank_transaction.unbooked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BankTransaction",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## journal_entry.created

A journal entry was booked through the platform API.

Object: `journal_entry` · module `settlements`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b18",
  "object": "event",
  "type": "journal_entry.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1008",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "JournalEntry",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## purchase_invoice.approved

A purchase invoice was approved.

Object: `purchase_invoice` · module `purchase_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b19",
  "object": "event",
  "type": "purchase_invoice.approved",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1009",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PurchaseInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## purchase_invoice.created

A purchase invoice was received or created.

Object: `purchase_invoice` · module `purchase_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b20",
  "object": "event",
  "type": "purchase_invoice.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1010",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PurchaseInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## purchase_invoice.due

A purchase invoice is due.

Object: `purchase_invoice` · module `purchase_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b21",
  "object": "event",
  "type": "purchase_invoice.due",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1011",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PurchaseInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## purchase_invoice.paid

A purchase invoice was paid.

Object: `purchase_invoice` · module `purchase_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b22",
  "object": "event",
  "type": "purchase_invoice.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1012",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PurchaseInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## purchase_invoice.processed

A purchase invoice was processed.

Object: `purchase_invoice` · module `purchase_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b23",
  "object": "event",
  "type": "purchase_invoice.processed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1013",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PurchaseInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## quote.accepted

A quote was accepted.

Object: `quote` · module `quotes`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b24",
  "object": "event",
  "type": "quote.accepted",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1014",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Quote",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## quote.sent

A quote was sent.

Object: `quote` · module `quotes`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b25",
  "object": "event",
  "type": "quote.sent",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1015",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Quote",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## relation.bank_account_changed

The bank account of a relation changed.

Object: `relation` · module `relations`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b26",
  "object": "event",
  "type": "relation.bank_account_changed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1016",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Relation",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## relation.created

A relation was created.

Object: `relation` · module `relations`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b27",
  "object": "event",
  "type": "relation.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1017",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Relation",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## relation.updated

A relation changed.

Object: `relation` · module `relations`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b28",
  "object": "event",
  "type": "relation.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1018",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Relation",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## reminder.paid

A reminder was paid.

Object: `reminder` · module `reminders`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b29",
  "object": "event",
  "type": "reminder.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1019",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Reminder",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## reminder.sent

A payment reminder was sent.

Object: `reminder` · module `reminders`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b30",
  "object": "event",
  "type": "reminder.sent",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1020",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Reminder",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.created

A sales invoice was created through the platform API.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b31",
  "object": "event",
  "type": "sales_invoice.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1021",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.credited

A sales invoice was credited.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b32",
  "object": "event",
  "type": "sales_invoice.credited",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1022",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.finalised

A sales invoice was numbered and booked.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b33",
  "object": "event",
  "type": "sales_invoice.finalised",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1023",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.overdue

A sales invoice is overdue.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
  "object": "event",
  "type": "sales_invoice.overdue",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1024",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.paid

A sales invoice was paid.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b35",
  "object": "event",
  "type": "sales_invoice.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1025",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## sales_invoice.sent

A sales invoice was sent.

Object: `sales_invoice` · module `sales_invoices`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b36",
  "object": "event",
  "type": "sales_invoice.sent",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1026",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "SalesInvoice",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/webhook-events/data-in -->
# Webhook events: Data in

Bulk jobs, data sources, feed health, records and flow runs. Payload samples.

Bulk jobs, data sources, feed health, records and flow runs. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## bulk_job.completed

A bulk job finished.

Object: `bulk_job`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "bulk_job.completed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BulkJob",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## bulk_job.failed

A bulk job failed.

Object: `bulk_job`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "bulk_job.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "BulkJob",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## data_source_file.failed

A statement file could not be processed.

Object: `data_source_file`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "data_source_file.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DataSourceFile",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## data_source_file.processed

A statement file was processed.

Object: `data_source_file`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "data_source_file.processed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DataSourceFile",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## data_source.backfill_completed

The history of a data source finished loading.

Object: `data_source_attachment`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "data_source.backfill_completed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DataSourceAttachment",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## data_source.resync_requested

A person in the partner portal asked for a period of a company to be delivered again. `data.object.from` and `data.object.to` name the days; deliver them with the usual feed calls.

Object: `data_source_attachment`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "data_source.resync_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DataSourceAttachment",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## feed.balance_mismatch

A delivered balance does not match the transactions.

Object: `feed_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "feed.balance_mismatch",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FeedAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## feed.delayed

A bank feed is later than usual.

Object: `feed_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "feed.delayed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FeedAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## feed.gap_detected

A bank feed stopped delivering.

Object: `feed_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b18",
  "object": "event",
  "type": "feed.gap_detected",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1008",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FeedAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## feed.recovered

A bank feed is healthy again.

Object: `feed_account` · module `banking`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b19",
  "object": "event",
  "type": "feed.recovered",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1009",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FeedAccount",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## flow_run.failed

A flow template failed.

Object: `flow_run` · module `custom_records`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b20",
  "object": "event",
  "type": "flow_run.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1010",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FlowRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## flow_run.succeeded

A flow template ran.

Object: `flow_run` · module `custom_records`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b21",
  "object": "event",
  "type": "flow_run.succeeded",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1011",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FlowRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## record.created

A custom record was created.

Object: `custom_record` · module `custom_records`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b22",
  "object": "event",
  "type": "record.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1012",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "CustomRecord",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## record.transitioned

A custom record moved to another state.

Object: `custom_record` · module `custom_records`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b23",
  "object": "event",
  "type": "record.transitioned",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1013",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "CustomRecord",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## record.updated

A custom record changed.

Object: `custom_record` · module `custom_records`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b24",
  "object": "event",
  "type": "record.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1014",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "CustomRecord",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/webhook-events/tax -->
# Webhook events: Tax

Filings, consent, payments and reservations. Payload samples.

Filings, consent, payments and reservations. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## tax_authorisation.granted

A company user authorised FinBaze to file the listed taxes (`companyId`, `taxes`, `channel`, `stepUp`, `at`). No IP or user agent.

Object: `tax_authorisation` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "tax_authorisation.granted",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxAuthorisation",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_authorisation.revoked

A filing authorisation was revoked for the listed taxes (`channel` is how: embed, headless, platform, admin or lifecycle).

Object: `tax_authorisation` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "tax_authorisation.revoked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxAuthorisation",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.accepted

A tax return was accepted.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "tax_filing.accepted",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.draft_ready

A tax return draft is ready.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "tax_filing.draft_ready",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.paid

The payment of a tax return was matched.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "tax_filing.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.ready

A tax return is ready to be submitted.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "tax_filing.ready",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.rejected

A tax return was rejected.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "tax_filing.rejected",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_filing.submitted

A tax return was submitted.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "tax_filing.submitted",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_payment.due

A tax payment is due.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b18",
  "object": "event",
  "type": "tax_payment.due",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1008",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_payment.overdue

A tax payment is overdue.

Object: `tax_filing` · module `tax_filings`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b19",
  "object": "event",
  "type": "tax_payment.overdue",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1009",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxFiling",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_reservation.advised

A new tax reservation advice was computed.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b20",
  "object": "event",
  "type": "tax_reservation.advised",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1010",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## tax_signal.created

A tax signal was raised.

Object: `tax_signal` · module `ai.tax.signals`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b21",
  "object": "event",
  "type": "tax_signal.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1011",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "TaxSignal",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/webhook-events/payroll -->
# Webhook events: Payroll

Pay runs and payslips. Payload samples.

Pay runs and payslips. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## pay_run.approved

A pay run was approved.

Object: `pay_run` · module `payroll`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "pay_run.approved",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PayRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## pay_run.calculated

A pay run was calculated.

Object: `pay_run` · module `payroll`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "pay_run.calculated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PayRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## pay_run.paid

A pay run was paid.

Object: `pay_run` · module `payroll`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "pay_run.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PayRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## payslip.finalised

A payslip was finalised.

Object: `payslip` · module `payroll`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "payslip.finalised",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Payslip",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/webhook-events/documents-messages -->
# Webhook events: Documents and messages

Documents and rendering, messages, exports, domains. Payload samples.

Documents and rendering, messages, exports, domains. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## custom_action.invoked

A user invoked one of your custom actions.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "custom_action.invoked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## custom_domain.status_changed

A custom domain for public pages changed status.

Object: `custom_domain`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "custom_domain.status_changed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "CustomDomain",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document_request.cancelled

A document request was cancelled.

Object: `document_request` · module `document_requests`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "document_request.cancelled",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DocumentRequest",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document_request.created

A document request was created.

Object: `document_request` · module `document_requests`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "document_request.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DocumentRequest",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document_request.fulfilled

A document request was fulfilled.

Object: `document_request` · module `document_requests`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "document_request.fulfilled",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "DocumentRequest",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.failed

A document could not be processed.

Object: `process_document` · module `process_documents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "document.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ProcessDocument",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.needs_review

A document needs a person to look at it.

> **Planned**
>
> Not sent yet; registered so you can see it coming.

Object: `process_document` · module `process_documents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "document.needs_review",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ProcessDocument",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.official_copy_created

The official copy of a document was stored.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "document.official_copy_created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.processed

A document was processed.

Object: `process_document` · module `process_documents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b18",
  "object": "event",
  "type": "document.processed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1008",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ProcessDocument",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.received

A document was received.

Object: `process_document` · module `process_documents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b19",
  "object": "event",
  "type": "document.received",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1009",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ProcessDocument",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.render_failed

A custom template or partner render failed or timed out; FinBaze used its own layout.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b20",
  "object": "event",
  "type": "document.render_failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1010",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.render_rejected

A PDF the platform rendered failed the required-content checks; FinBaze used its own layout.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b21",
  "object": "event",
  "type": "document.render_rejected",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1011",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## document.render_requested

A document needs to be rendered by the platform. The payload has the data model and signed links to files that go with it (the invoice UBL), valid 15 minutes.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b22",
  "object": "event",
  "type": "document.render_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1012",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## export.destination_expiring

Credentials of an export destination expire soon.

Object: `export_destination` · module `data_export`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b23",
  "object": "event",
  "type": "export.destination_expiring",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1013",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ExportDestination",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## export.failed

A scheduled export failed.

Object: `export_run` · module `data_export`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b24",
  "object": "event",
  "type": "export.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1014",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ExportRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## export.ready

A scheduled export is ready.

Object: `export_run` · module `data_export`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b25",
  "object": "event",
  "type": "export.ready",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1015",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "ExportRun",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## message.created

A message needs to be delivered by the platform.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b26",
  "object": "event",
  "type": "message.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1016",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## message.unacknowledged

A delivered message was not acknowledged in time.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b27",
  "object": "event",
  "type": "message.unacknowledged",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1017",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/graphql -->
# GraphQL reference

Every operation your backend can call, grouped by area, with the scope and feature each needs.

Endpoint: `POST https://api.platform.finbaze.com/graphql` (sandbox: `https://sandbox.api.platform.finbaze.com/graphql`). Authenticate with `Authorization: Bearer <token>`; see [identity and tokens](/concepts/identity-and-tokens).

> This reference is generated from the schema. It lists 1084 operations. Admin, firm and internal operations are left out. A field's *scope* is what a restricted key or token needs; *feature* is the module that must be visible for the company.

- [Platform, companies and users](/reference/graphql/platform)
- [Agents](/reference/graphql/agents)
- [Assets](/reference/graphql/assets)
- [Automations](/reference/graphql/automations)
- [Budgets](/reference/graphql/budgets)
- [Clients](/reference/graphql/clients)
- [Cost centers](/reference/graphql/cost-centers)
- [Current accounts](/reference/graphql/current-accounts)
- [Dashboard](/reference/graphql/dashboard)
- [Document requests](/reference/graphql/document-requests)
- [Employees](/reference/graphql/employees)
- [Employments](/reference/graphql/employments)
- [Financial years](/reference/graphql/financial-years)
- [General ledger](/reference/graphql/general-ledger)
- [Ledger chart](/reference/graphql/ledger-chart)
- [Loans](/reference/graphql/loans)
- [Messages](/reference/graphql/messages)
- [Monetary accounts](/reference/graphql/monetary-accounts)
- [Pay runs](/reference/graphql/pay-runs)
- [Payment batches](/reference/graphql/payment-batches)
- [Payroll](/reference/graphql/payroll)
- [Payroll filings](/reference/graphql/payroll-filings)
- [Process documents](/reference/graphql/process-documents)
- [Products](/reference/graphql/products)
- [Projects](/reference/graphql/projects)
- [Psp payments](/reference/graphql/psp-payments)
- [Purchase invoices](/reference/graphql/purchase-invoices)
- [Quotes](/reference/graphql/quotes)
- [Relations](/reference/graphql/relations)
- [Reminders](/reference/graphql/reminders)
- [Reports](/reference/graphql/reports)
- [Sales invoices](/reference/graphql/sales-invoices)
- [Settings](/reference/graphql/settings)
- [Settlements](/reference/graphql/settlements)
- [Subscriptions](/reference/graphql/subscriptions)
- [Tax](/reference/graphql/tax)
- [Vehicles](/reference/graphql/vehicles)
- [Work sessions](/reference/graphql/work-sessions)


---

<!-- /reference/webhook-events/delegated -->
# Webhook events: Delegated actions

Payment requests, payment links and step-up challenges. Payload samples.

Payment requests, payment links and step-up challenges. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## payment_link.requested

A payment link is needed for an invoice.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "payment_link.requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## payment_request.created

A payment request was created; pay it and use the end-to-end id.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "payment_request.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## payment_request.paid

The bank transaction of a payment request was matched.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "payment_request.paid",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## payment_request.updated

A payment request changed status.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "payment_request.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## step_up.required

A step-up confirmation is required for a high-risk action.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "step_up.required",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/graphql/platform -->
# Platform, companies and users

GraphQL operations: platform, companies and users.

## Queries

### platformOpsStatus

Requires: platform key or token · scope `platform_usage:read`.

```graphql
platformOpsStatus: PlatformOpsStatus!
```

### platformKeys

Requires: platform key or token.

```graphql
platformKeys(platformId: ID): [PlatformKey!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformCompany

Requires: platform key or token · scope `platform_companies:read`.

```graphql
platformCompany(platformId: ID, profileId: ID, externalId: String): PlatformCompany
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID` |  |
| `externalId` | `String` |  |

### platformCompanies

Requires: platform key or token · scope `platform_companies:read`.

```graphql
platformCompanies(platformId: ID, first: Int, after: String, filter: PlatformCompanyFilter, lifecycleStates: [ProfileLifecycleState!], includeArchived: Boolean): PlatformCompanyConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `first` | `Int` |  |
| `after` | `String` |  |
| `filter` | `PlatformCompanyFilter` |  |
| `lifecycleStates` | `[ProfileLifecycleState!]` | Default: every state except archived. Name `archived` (or pass includeArchived) to see archived companies. |
| `includeArchived` | `Boolean` |  |

### platformUser

Requires: platform key or token · scope `platform_users:read`.

```graphql
platformUser(platformId: ID, userId: ID, externalUserId: String): PlatformUser
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `userId` | `ID` |  |
| `externalUserId` | `String` |  |

### platformUsers

Requires: platform key or token · scope `platform_users:read`.

```graphql
platformUsers(platformId: ID, profileId: ID, first: Int, after: String): PlatformUserConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### platformPortalAccess

Requires: platform key or token.

```graphql
platformPortalAccess(platformId: ID): PlatformPortalAccess!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformPortalMembers

Requires: platform key or token.

```graphql
platformPortalMembers(platformId: ID): [PlatformPortalMember!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformSandboxSettings

Requires: platform key or token · scope `platform_companies:read`.

```graphql
platformSandboxSettings(platformId: ID): PlatformSandboxSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformFeatureAllowance

Requires: platform key or token · scope `platform_features:read`.

```graphql
platformFeatureAllowance(platformId: ID): PlatformFeatureAllowance!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformFeatureLimits

Requires: platform key or token · scope `platform_features:read`.

```graphql
platformFeatureLimits(platformId: ID, profileId: ID): [PlatformFeatureLimit!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID` |  |

### platformCompanyFeatures

Requires: platform key or token · scope `platform_features:read`.

```graphql
platformCompanyFeatures(platformId: ID, profileId: ID!): [PlatformCompanyFeature!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID!` |  |

### platformFeatureExplain

The steps behind a feature key for one of the platform's companies: environment, requires, allowance, platform and company limits. Firm overrides are shown as skipped.

Requires: platform key or token · scope `platform_features:read`.

```graphql
platformFeatureExplain(platformId: ID, profileId: ID!, key: String!): FeatureExplain!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID!` |  |
| `key` | `String!` |  |

### platformMobileApps

Requires: platform key or token · scope `platform_embed:read`.

```graphql
platformMobileApps(platformId: ID): [PlatformMobileApp!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### embedSessions

Requires: platform key or token.

```graphql
embedSessions(filter: EmbedSessionFilterInput, first: Int, after: String): EmbedSessionConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `filter` | `EmbedSessionFilterInput` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### embedSession

Requires: platform key or token.

```graphql
embedSession(id: ID!): EmbedSession
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### embedContext

Embed or headless token only.

```graphql
embedContext: EmbedContext!
```

### platformAllowedOrigins

Requires: platform key or token · scope `platform_embed:read`.

```graphql
platformAllowedOrigins(platformId: ID): [PlatformAllowedOrigin!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformEmbedSettings

Requires: platform key or token · scope `platform_embed:read`.

```graphql
platformEmbedSettings(platformId: ID): PlatformEmbedSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### onboardingRequirements

What the company still has to provide before FinBaze can book and file for it.

```graphql
onboardingRequirements(profileId: ID!): [OnboardingRequirement!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### resolveEmbedIntent

Requires: platform key or token · scope `platform_embed:read`.

```graphql
resolveEmbedIntent(intent: String!): EmbedIntent!
```

| Argument | Type |  |
| --- | --- | --- |
| `intent` | `String!` |  |

### platformEventCatalog

Requires: platform key or token · scope `events:read`.

```graphql
platformEventCatalog(platformId: ID): [PlatformEventType!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformEvents

Requires: platform key or token · scope `events:read`.

```graphql
platformEvents(filter: PlatformEventFilter, after: String, first: Int!, platformId: ID): PlatformEventConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `filter` | `PlatformEventFilter` |  |
| `after` | `String` |  |
| `first` | `Int!` |  |
| `platformId` | `ID` |  |

### platformEvent

Requires: platform key or token · scope `events:read`.

```graphql
platformEvent(id: ID!, platformId: ID): PlatformEvent
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `platformId` | `ID` |  |

### platformWebhookEndpoints

Requires: platform key or token · scope `webhooks:read`.

```graphql
platformWebhookEndpoints(platformId: ID): [PlatformWebhookEndpoint!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformWebhookDeliveries

Requires: platform key or token · scope `webhooks:read`.

```graphql
platformWebhookDeliveries(endpointId: ID!, filter: PlatformDeliveryFilter, after: String, first: Int!, platformId: ID): PlatformWebhookDeliveryConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `endpointId` | `ID!` |  |
| `filter` | `PlatformDeliveryFilter` |  |
| `after` | `String` |  |
| `first` | `Int!` |  |
| `platformId` | `ID` |  |

### bankTransactionBookings

Requires: platform key or token · feature `banking`.

```graphql
bankTransactionBookings(company: CompanyRef!, externalIds: [String!]!): [BankTransactionBooking!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `externalIds` | `[String!]!` |  |

### dataSources

Requires: platform key or token · scope `data_sources:read`.

```graphql
dataSources: [DataSource!]!
```

### dataSource

Requires: platform key or token · scope `data_sources:read`.

```graphql
dataSource(key: String!): DataSource
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |

### feedHealth

Requires: platform key or token · scope `data_sources:read`.

```graphql
feedHealth(status: [FeedHealthStatus!], first: Int!, after: String): FeedAccountConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `status` | `[FeedHealthStatus!]` |  |
| `first` | `Int!` |  |
| `after` | `String` |  |

### dataSourceFiles

Requires: platform key or token · scope `data_sources:read`.

```graphql
dataSourceFiles(key: String!, first: Int!, after: String): DataSourceFileConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |
| `first` | `Int!` |  |
| `after` | `String` |  |

### payoutTransferMatches

Requires: platform key or token · scope `monetary_accounts:read`.

```graphql
payoutTransferMatches(source: String!, company: CompanyRef!, payouts: [String!]!): [PayoutTransferMatch!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `payouts` | `[String!]!` | externalIds of payouts (at most 500). |

### platformObjectByExternalId

Requires: platform key or token.

```graphql
platformObjectByExternalId(company: CompanyRef!, type: PlatformObjectType!, externalId: String!): PlatformObjectRef
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `type` | `PlatformObjectType!` |  |
| `externalId` | `String!` |  |

### platformBulkJob

Requires: platform key or token · scope `bulk:read`.

```graphql
platformBulkJob(id: ID!): PlatformBulkJob
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### platformBulkJobs

Requires: platform key or token · scope `bulk:read`.

```graphql
platformBulkJobs(first: Int!, after: String, status: [PlatformBulkJobStatus!]): PlatformBulkJobConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `first` | `Int!` |  |
| `after` | `String` |  |
| `status` | `[PlatformBulkJobStatus!]` |  |

### policySchemas

JSON Schema per policy kind (portal forms, SDK types).

Requires: platform key or token · scope `platform_policies:read`.

```graphql
policySchemas(platformId: ID): JSONObject!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformPolicies

Requires: platform key or token · scope `platform_policies:read`.

```graphql
platformPolicies(platformId: ID, kind: PolicyKind, status: PolicyStatus): [PlatformPolicyVersion!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `kind` | `PolicyKind` |  |
| `status` | `PolicyStatus` |  |

### effectivePolicy

Requires: platform key or token · scope `platform_policies:read`.

```graphql
effectivePolicy(platformId: ID, kind: PolicyKind!, companyId: ID!): JSONObject!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `kind` | `PolicyKind!` |  |
| `companyId` | `ID!` |  |

### companyPolicyOverrides

Requires: platform key or token · scope `platform_policies:read`.

```graphql
companyPolicyOverrides(platformId: ID, companyId: ID!): [CompanyPolicyOverride!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |

### platformCustomActions

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
platformCustomActions(platformId: ID): [PlatformCustomAction!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### customActions

The actions to show at a placement for one object, resolved on the server.

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
customActions(platformId: ID, placement: String!, contextType: String!, contextId: ID!, locale: String): [ResolvedCustomAction!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `placement` | `String!` |  |
| `contextType` | `String!` |  |
| `contextId` | `ID!` |  |
| `locale` | `String` |  |

### platformLinkTemplates

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
platformLinkTemplates(platformId: ID): [PlatformLinkTemplate!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### partnerLinks

Links from a FinBaze object to the same object in your own system.

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
partnerLinks(platformId: ID, objectType: String!, objectId: ID!, locale: String): [PartnerLink!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `objectType` | `String!` |  |
| `objectId` | `ID!` |  |
| `locale` | `String` |  |

### customFieldDefinitions

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
customFieldDefinitions(platformId: ID, entityType: String!): [CustomFieldDefinition!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `entityType` | `String!` |  |

### customFieldValues

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
customFieldValues(platformId: ID, entityType: String!, entityId: ID!): JSONObject!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `entityType` | `String!` |  |
| `entityId` | `ID!` |  |

### fieldControls

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
fieldControls(platformId: ID, view: String!, companyId: ID): [FieldControl!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `view` | `String!` |  |
| `companyId` | `ID` |  |

### platformRecordTypes

Requires: platform key or token · scope `custom_records:read`.

```graphql
platformRecordTypes(platformId: ID): [PlatformRecordType!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### customRecords

Requires: platform key or token · scope `custom_records:read`.

```graphql
customRecords(company: CompanyRef!, type: String!, status: [String!], first: Int!, after: String): CustomRecordConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `type` | `String!` |  |
| `status` | `[String!]` |  |
| `first` | `Int!` |  |
| `after` | `String` |  |

### customRecord

Requires: platform key or token · scope `custom_records:read`.

```graphql
customRecord(company: CompanyRef!, type: String!, externalId: String!): CustomRecord
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `type` | `String!` |  |
| `externalId` | `String!` |  |

### flowTemplates

Requires: platform key or token · scope `custom_records:read`.

```graphql
flowTemplates(platformId: ID, key: String): [FlowTemplate!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String` |  |

### flowRuns

Requires: platform key or token · scope `custom_records:read`.

```graphql
flowRuns(platformId: ID, status: [String!], first: Int!, after: String): FlowRunConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `status` | `[String!]` |  |
| `first` | `Int!` |  |
| `after` | `String` |  |

### platformReport

Requires: platform key or token · scope `reports:read`.

```graphql
platformReport(company: CompanyRef!, input: PlatformReportInput!): PlatformReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `input` | `PlatformReportInput!` |  |

### platformReportDocument

Requires: platform key or token · scope `reports:read`.

```graphql
platformReportDocument(company: CompanyRef!, input: PlatformReportInput!, format: ReportFormat!): CompanyDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `input` | `PlatformReportInput!` |  |
| `format` | `ReportFormat!` |  |

### companyDocument

Requires: platform key or token · scope `documents:read`.

```graphql
companyDocument(company: CompanyRef!, kind: CompanyDocumentKind!, object: ObjectRef, params: JSON): CompanyDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `kind` | `CompanyDocumentKind!` |  |
| `object` | `ObjectRef` |  |
| `params` | `JSON` |  |

### platformExportDestinations

Requires: platform key or token · scope `exports:read`.

```graphql
platformExportDestinations(platformId: ID): [PlatformExportDestination!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformExportSchedules

Requires: platform key or token · scope `exports:read`.

```graphql
platformExportSchedules(platformId: ID): [PlatformExportSchedule!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformExportRun

Requires: platform key or token · scope `exports:read`.

```graphql
platformExportRun(platformId: ID, id: ID!): PlatformExportRun
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### companyExports

The company's recent exports, newest first: audit files in any state, and reports that are still downloadable.

Requires: platform key or token.

```graphql
companyExports(platformId: ID, companyId: ID!, first: Int): [CompanyExport!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `first` | `Int` |  |

### platformProviders

Requires: platform key or token · scope `platform_payments:read`.

```graphql
platformProviders: [PlatformProvider!]!
```

### paymentRequests

Requires: platform key or token · scope `platform_payments:read`.

```graphql
paymentRequests(company: CompanyRef, status: [PaymentRequestStatus!], first: Int, after: String): PaymentRequestConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef` |  |
| `status` | `[PaymentRequestStatus!]` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### paymentRequest

Requires: platform key or token · scope `platform_payments:read`.

```graphql
paymentRequest(id: ID!): PaymentRequest
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### taxReservationAdvice

Requires: platform key or token · scope `platform_payments:read`.

```graphql
taxReservationAdvice(company: CompanyRef!): [TaxReservationAdvice!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |

### stepUpChallenge

Requires: platform key or token.

```graphql
stepUpChallenge(id: ID!): StepUpChallenge
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### platformUsage

Requires: platform key or token · scope `platform_usage:read`.

```graphql
platformUsage(platformId: ID, month: String): PlatformUsage!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `month` | `String` |  |

### platformContract

Requires: platform key or token · scope `platform_usage:read`.

```graphql
platformContract(platformId: ID): PlatformContractView
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### testClocks

Requires: platform key or token · scope `platform_companies:read`.

```graphql
testClocks(platformId: ID): [TestClock!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### companyClosingChecklist

Requires: platform key or token · scope `platform_companies:read`.

```graphql
companyClosingChecklist(companyId: ID!, platformId: ID, effectiveDate: String): [ClosingChecklistItem!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |
| `effectiveDate` | `String` | Preview for an active company: what closing on this day would need. |

### companyTransferStatement

Requires: platform key or token · scope `platform_companies:read`.

```graphql
companyTransferStatement(companyId: ID!, target: CompanyTransferTarget!, locale: String): CompanyTransferStatement!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `target` | `CompanyTransferTarget!` |  |
| `locale` | `String` |  |

### companyTransfers

Requires: platform key or token · scope `platform_companies:read`.

```graphql
companyTransfers(companyId: ID!): [CompanyTransfer!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |

### platformAuditLogs

Requires: platform key or token · scope `audit:read`.

```graphql
platformAuditLogs(platformId: ID, filter: PlatformAuditLogFilter, first: Int, after: String): PlatformAuditLogConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `filter` | `PlatformAuditLogFilter` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### platformSupportSettings

Requires: platform key or token · scope `support:read`.

```graphql
platformSupportSettings(platformId: ID): PlatformSupportSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### supportEscalations

Requires: platform key or token · scope `support:read`.

```graphql
supportEscalations(platformId: ID, status: [SupportEscalationStatus!], first: Int, after: String): [SupportEscalation!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `status` | `[SupportEscalationStatus!]` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### supportAccessGrants

Requires: platform key or token · scope `support:read`.

```graphql
supportAccessGrants(platformId: ID, companyId: ID!, includeEnded: Boolean): [SupportAccessGrant!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `includeEnded` | `Boolean` |  |

### platformRequestLogs

Requires: platform key or token · scope `request_logs:read`.

```graphql
platformRequestLogs(platformId: ID, filter: PlatformRequestLogFilter, first: Int, after: String): PlatformRequestLogConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `filter` | `PlatformRequestLogFilter` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### platformOverview

Requires: platform key or token · scope `platform_usage:read`.

```graphql
platformOverview(platformId: ID, month: String): PlatformOverview!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `month` | `String` |  |

### platformAlerts

Open or resolved alerts of the platform, newest first.

Requires: platform key or token · scope `request_logs:read`.

```graphql
platformAlerts(platformId: ID, status: PlatformAlertStatus, first: Int): [PlatformAlert!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `status` | `PlatformAlertStatus` |  |
| `first` | `Int` |  |

### platformDataSourceHealth

Per data source: companies, last event, lag, gaps, error rate, backfill status and the last errors.

Requires: platform key or token · scope `data_sources:read`.

```graphql
platformDataSourceHealth(platformId: ID, key: String): [PlatformDataSourceHealth!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String` |  |

## Mutations

### createPlatformKey

Requires: platform key or token.

```graphql
createPlatformKey(input: CreatePlatformKeyInput!): PlatformKeyWithSecret!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreatePlatformKeyInput!` |  |

### rollPlatformKey

Requires: platform key or token.

```graphql
rollPlatformKey(platformId: ID, id: ID!, expireOldInSeconds: Int): PlatformKeyWithSecret!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |
| `expireOldInSeconds` | `Int` |  |

### revokePlatformKey

Requires: platform key or token.

```graphql
revokePlatformKey(platformId: ID, id: ID!): PlatformKey!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### createPlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
createPlatformCompany(input: CreatePlatformCompanyInput!): PlatformCompanyResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreatePlatformCompanyInput!` |  |

### updatePlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
updatePlatformCompany(input: UpdatePlatformCompanyInput!): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdatePlatformCompanyInput!` |  |

### upsertPlatformUser

Requires: platform key or token · scope `platform_users:write`.

```graphql
upsertPlatformUser(input: UpsertPlatformUserInput!): PlatformUser!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertPlatformUserInput!` |  |

### setPlatformUserAccess

Requires: platform key or token · scope `platform_users:write`.

```graphql
setPlatformUserAccess(input: SetPlatformUserAccessInput!): PlatformUserAccess!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetPlatformUserAccessInput!` |  |

### removePlatformUserAccess

Requires: platform key or token · scope `platform_users:write`.

```graphql
removePlatformUserAccess(platformId: ID, userId: ID!, profileId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `userId` | `ID!` |  |
| `profileId` | `ID!` |  |

### revokePlatformUserTokens

Refuses every token issued to the user so far and ends their embed sessions. The user and their access stay; the platform mints new tokens as usual.

Requires: platform key or token · scope `platform_users:write`.

```graphql
revokePlatformUserTokens(platformId: ID, userId: ID!): PlatformUser!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `userId` | `ID!` |  |

### disablePlatformUser

Requires: platform key or token · scope `platform_users:write`.

```graphql
disablePlatformUser(platformId: ID, userId: ID!): PlatformUser!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `userId` | `ID!` |  |

### requestUserAccessChange

Asks the platform to invite someone, change a role or remove access (webhook `user.invite_requested`, `user.role_change_requested`, `user.removal_requested`). Company admins only. Nothing is created or sent by FinBaze; returns the event name.

Requires: platform key or token.

```graphql
requestUserAccessChange(platformId: ID, companyId: ID!, input: UserAccessRequestInput!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `input` | `UserAccessRequestInput!` |  |

### createPlatformUserToken

Requires: platform key or token · scope `platform_tokens:write`.

```graphql
createPlatformUserToken(input: CreatePlatformUserTokenInput!): PlatformUserToken!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreatePlatformUserTokenInput!` |  |

### setPlatformPortalRole

Requires: platform key or token.

```graphql
setPlatformPortalRole(input: SetPlatformPortalRoleInput!): PlatformPortalMember!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetPlatformPortalRoleInput!` |  |

### seedTestCompany

Creates a demo company from a template (sandbox only). Seeding the same externalId again returns the existing company.

Requires: platform key or token · scope `platform_companies:write`.

```graphql
seedTestCompany(input: SeedTestCompanyInput!): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SeedTestCompanyInput!` |  |

### updatePlatformSandboxSettings

Requires: platform key or token · scope `platform_companies:write`.

```graphql
updatePlatformSandboxSettings(input: UpdatePlatformSandboxSettingsInput!): PlatformSandboxSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdatePlatformSandboxSettingsInput!` |  |

### resetPlatformSandbox

Deletes every sandbox company that is not marked preserve, deletes empty test clocks and seeds the configured templates again.

Requires: platform key or token · scope `platform_companies:write`.

```graphql
resetPlatformSandbox(platformId: ID): SandboxResetResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### bootstrapSampleApp

Sandbox only. Sets up a sample app: a restricted test key and publishable key, a webhook endpoint at webhookUrl and its demo company. Portal sign-in only; 5 per day.

Requires: platform key or token.

```graphql
bootstrapSampleApp(sample: String!, webhookUrl: String): SampleAppBootstrap!
```

| Argument | Type |  |
| --- | --- | --- |
| `sample` | `String!` |  |
| `webhookUrl` | `String` |  |

### setPlatformFeatureLimit

Requires: platform key or token · scope `platform_features:write`.

```graphql
setPlatformFeatureLimit(input: SetPlatformFeatureLimitInput!): PlatformFeatureLimit!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetPlatformFeatureLimitInput!` |  |

### clearPlatformFeatureLimit

Requires: platform key or token · scope `platform_features:write`.

```graphql
clearPlatformFeatureLimit(platformId: ID, key: String!, profileId: ID): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `profileId` | `ID` |  |

### registerPlatformMobileApp

Requires: platform key or token · scope `platform_embed:write`.

```graphql
registerPlatformMobileApp(platformId: ID, input: PlatformMobileAppInput!): PlatformMobileApp!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `PlatformMobileAppInput!` |  |

### removePlatformMobileApp

Requires: platform key or token · scope `platform_embed:write`.

```graphql
removePlatformMobileApp(platformId: ID, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### createEmbedSession

Requires: platform key or token.

```graphql
createEmbedSession(input: CreateEmbedSessionInput!): CreateEmbedSessionResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateEmbedSessionInput!` |  |

### revokeEmbedSession

Requires: platform key or token.

```graphql
revokeEmbedSession(id: ID!): EmbedSession!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### revokeEmbedSessionsForUser

Revokes every open or exchanged session of the user (optionally for one company). Returns the count.

Requires: platform key or token · scope `platform_embed:write`.

```graphql
revokeEmbedSessionsForUser(platformUserId: ID!, companyId: ID): Int!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformUserId` | `ID!` |  |
| `companyId` | `ID` |  |

### exchangeEmbedSession

```graphql
exchangeEmbedSession(input: ExchangeEmbedSessionInput!): EmbedToken!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ExchangeEmbedSessionInput!` |  |

### addPlatformAllowedOrigin

Requires: platform key or token · scope `platform_embed:write`.

```graphql
addPlatformAllowedOrigin(platformId: ID, origin: String!, kind: PlatformOriginKind!): PlatformAllowedOrigin!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `origin` | `String!` |  |
| `kind` | `PlatformOriginKind!` |  |

### removePlatformAllowedOrigin

Requires: platform key or token · scope `platform_embed:write`.

```graphql
removePlatformAllowedOrigin(platformId: ID, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### updatePlatformEmbedSettings

Requires: platform key or token · scope `platform_embed:write`.

```graphql
updatePlatformEmbedSettings(platformId: ID, input: UpdatePlatformEmbedSettingsInput!): PlatformEmbedSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `UpdatePlatformEmbedSettingsInput!` |  |

### acknowledgeMessageIntent

Requires: platform key or token.

```graphql
acknowledgeMessageIntent(id: ID!, outcome: MessageIntentOutcome!): AcknowledgedMessageIntent!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `outcome` | `MessageIntentOutcome!` |  |

### createPlatformWebhookEndpoint

Requires: platform key or token · scope `webhooks:write`.

```graphql
createPlatformWebhookEndpoint(input: CreatePlatformWebhookEndpointInput!, platformId: ID): PlatformWebhookEndpointWithSecret!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreatePlatformWebhookEndpointInput!` |  |
| `platformId` | `ID` |  |

### updatePlatformWebhookEndpoint

Requires: platform key or token · scope `webhooks:write`.

```graphql
updatePlatformWebhookEndpoint(id: ID!, input: UpdatePlatformWebhookEndpointInput!, platformId: ID): PlatformWebhookEndpoint!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `UpdatePlatformWebhookEndpointInput!` |  |
| `platformId` | `ID` |  |

### rotatePlatformWebhookSecret

Requires: platform key or token · scope `webhooks:write`.

```graphql
rotatePlatformWebhookSecret(id: ID!, keepPreviousHours: Int!, platformId: ID): PlatformWebhookEndpointWithSecret!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `keepPreviousHours` | `Int!` |  |
| `platformId` | `ID` |  |

### deletePlatformWebhookEndpoint

Requires: platform key or token · scope `webhooks:write`.

```graphql
deletePlatformWebhookEndpoint(id: ID!, platformId: ID): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `platformId` | `ID` |  |

### pingPlatformWebhookEndpoint

Requires: platform key or token · scope `webhooks:write`.

```graphql
pingPlatformWebhookEndpoint(id: ID!, platformId: ID): PlatformWebhookDelivery!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `platformId` | `ID` |  |

### sendPlatformTestEvent

Posts a signed example event of an available type to the endpoint and reports the answer. Nothing is stored.

Requires: platform key or token · scope `webhooks:write`.

```graphql
sendPlatformTestEvent(endpointId: ID!, type: String!, platformId: ID): PlatformWebhookDelivery!
```

| Argument | Type |  |
| --- | --- | --- |
| `endpointId` | `ID!` |  |
| `type` | `String!` |  |
| `platformId` | `ID` |  |

### replayPlatformWebhookDelivery

Requires: platform key or token · scope `webhooks:write`.

```graphql
replayPlatformWebhookDelivery(id: ID!, platformId: ID): PlatformWebhookDelivery!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `platformId` | `ID` |  |

### replayPlatformWebhookDeliveries

Requires: platform key or token · scope `webhooks:write`.

```graphql
replayPlatformWebhookDeliveries(endpointId: ID!, filter: PlatformDeliveryFilter!, platformId: ID): PlatformReplayJob!
```

| Argument | Type |  |
| --- | --- | --- |
| `endpointId` | `ID!` |  |
| `filter` | `PlatformDeliveryFilter!` |  |
| `platformId` | `ID` |  |

### resendPlatformEvent

Requires: platform key or token · scope `webhooks:write`.

```graphql
resendPlatformEvent(eventId: ID!, endpointId: ID!, platformId: ID): PlatformWebhookDelivery!
```

| Argument | Type |  |
| --- | --- | --- |
| `eventId` | `ID!` |  |
| `endpointId` | `ID!` |  |
| `platformId` | `ID` |  |

### registerDataSource

Requires: platform key or token · scope `data_sources:write`.

```graphql
registerDataSource(input: RegisterDataSourceInput!): DataSource!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `RegisterDataSourceInput!` |  |

### updateDataSource

Requires: platform key or token · scope `data_sources:write`.

```graphql
updateDataSource(key: String!, input: UpdateDataSourceInput!): DataSource!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |
| `input` | `UpdateDataSourceInput!` |  |

### retireDataSource

Requires: platform key or token · scope `data_sources:write`.

```graphql
retireDataSource(key: String!): DataSource!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |

### attachDataSource

Requires: platform key or token · scope `data_sources:write`.

```graphql
attachDataSource(key: String!, company: CompanyRef!, backfillFrom: String): DataSourceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `backfillFrom` | `String` |  |

### pauseDataSourceAttachment

Requires: platform key or token · scope `data_sources:write`.

```graphql
pauseDataSourceAttachment(key: String!, company: CompanyRef!): DataSourceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |
| `company` | `CompanyRef!` |  |

### detachDataSource

Requires: platform key or token · scope `data_sources:write`.

```graphql
detachDataSource(key: String!, company: CompanyRef!): DataSourceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `key` | `String!` |  |
| `company` | `CompanyRef!` |  |

### upsertFeedBankAccount

Requires: platform key or token · scope `monetary_accounts:write`.

```graphql
upsertFeedBankAccount(source: String!, company: CompanyRef!, account: BankAccountFeedInput!): FeedAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `account` | `BankAccountFeedInput!` |  |

### ingestBankTransactions

Requires: platform key or token · feature `banking`.

```graphql
ingestBankTransactions(source: String!, company: CompanyRef!, account: String!, transactions: [BankTransactionFeedInput!]!): [FeedIngestResult!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `account` | `String!` |  |
| `transactions` | `[BankTransactionFeedInput!]!` |  |

### reportBankBalances

Requires: platform key or token · scope `monetary_accounts:write`.

```graphql
reportBankBalances(source: String!, company: CompanyRef!, account: String!, balances: [BankBalanceInput!]!): [BankBalanceAssertion!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `account` | `String!` |  |
| `balances` | `[BankBalanceInput!]!` |  |

### reportFeedWatermark

Requires: platform key or token · scope `monetary_accounts:write`.

```graphql
reportFeedWatermark(source: String!, company: CompanyRef!, account: String, completeThrough: String!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `account` | `String` |  |
| `completeThrough` | `String!` |  |

### ingestWorkedHours

Requires: platform key or token · scope `payroll:write` · feature `payroll`.

```graphql
ingestWorkedHours(source: String!, company: CompanyRef!, entries: [WorkedHoursFeedInput!]!): [FeedIngestResult!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `entries` | `[WorkedHoursFeedInput!]!` |  |

### ingestPayoutTransactions

Requires: platform key or token · scope `monetary_accounts:write`.

```graphql
ingestPayoutTransactions(source: String!, company: CompanyRef!, account: String!, payouts: [PayoutFeedInput!]!): [FeedIngestResult!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `account` | `String!` | externalId of the PSP account the payouts leave. |
| `payouts` | `[PayoutFeedInput!]!` |  |

### ingestSalesInvoices

Requires: platform key or token · feature `sales_invoices`.

```graphql
ingestSalesInvoices(source: String!, company: CompanyRef!, invoices: [SalesInvoiceFeedInput!]!): [FeedIngestResult!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `invoices` | `[SalesInvoiceFeedInput!]!` |  |

### ingestPurchaseInvoices

Requires: platform key or token · feature `purchase_invoices`.

```graphql
ingestPurchaseInvoices(source: String!, company: CompanyRef!, invoices: [PurchaseInvoiceFeedInput!]!): [FeedIngestResult!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `source` | `String!` |  |
| `company` | `CompanyRef!` |  |
| `invoices` | `[PurchaseInvoiceFeedInput!]!` |  |

### upsertRelation

Requires: platform key or token · feature `relations`.

```graphql
upsertRelation(input: UpsertRelationInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertRelationInput!` |  |

### upsertProduct

Requires: platform key or token · feature `products`.

```graphql
upsertProduct(input: UpsertProductInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertProductInput!` |  |

### upsertProject

Requires: platform key or token · feature `projects`.

```graphql
upsertProject(input: UpsertProjectInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertProjectInput!` |  |

### upsertCostCenter

Requires: platform key or token · feature `cost_centers`.

```graphql
upsertCostCenter(input: UpsertCostCenterInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertCostCenterInput!` |  |

### upsertSalesInvoice

Requires: platform key or token · feature `sales_invoices`.

```graphql
upsertSalesInvoice(input: UpsertSalesInvoiceInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertSalesInvoiceInput!` |  |

### upsertPurchaseInvoice

Requires: platform key or token · feature `purchase_invoices`.

```graphql
upsertPurchaseInvoice(input: UpsertPurchaseInvoiceInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertPurchaseInvoiceInput!` |  |

### upsertQuote

Requires: platform key or token · feature `quotes`.

```graphql
upsertQuote(input: UpsertQuoteInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertQuoteInput!` |  |

### upsertJournalEntry

Requires: platform key or token.

```graphql
upsertJournalEntry(input: UpsertJournalEntryInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertJournalEntryInput!` |  |

### upsertEmployee

Requires: platform key or token · feature `payroll`.

```graphql
upsertEmployee(input: UpsertEmployeeInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertEmployeeInput!` |  |

### upsertEmployment

Requires: platform key or token · feature `payroll`.

```graphql
upsertEmployment(input: UpsertEmploymentInput!): UpsertPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertEmploymentInput!` |  |

### setObjectMetadata

Requires: platform key or token.

```graphql
setObjectMetadata(type: PlatformObjectType!, id: ID!, metadata: JSON!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `type` | `PlatformObjectType!` |  |
| `id` | `ID!` |  |
| `metadata` | `JSON!` |  |

### cancelPlatformBulkJob

Requires: platform key or token · scope `bulk:write`.

```graphql
cancelPlatformBulkJob(id: ID!): PlatformBulkJob!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createPolicyDraft

Requires: platform key or token · scope `platform_policies:write`.

```graphql
createPolicyDraft(platformId: ID, kind: PolicyKind!, payload: JSONObject!): PlatformPolicyVersion!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `kind` | `PolicyKind!` |  |
| `payload` | `JSONObject!` |  |

### activatePolicyVersion

Requires: platform key or token · scope `platform_policies:write`.

```graphql
activatePolicyVersion(platformId: ID, id: ID!): PlatformPolicyVersion!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### setCompanyPolicyOverride

Requires: platform key or token · scope `platform_policies:write`.

```graphql
setCompanyPolicyOverride(platformId: ID, companyId: ID!, kind: PolicyKind!, payload: JSONObject!): JSONObject!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `kind` | `PolicyKind!` |  |
| `payload` | `JSONObject!` |  |

### clearCompanyPolicyOverride

Requires: platform key or token · scope `platform_policies:write`.

```graphql
clearCompanyPolicyOverride(platformId: ID, companyId: ID!, kind: PolicyKind!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `kind` | `PolicyKind!` |  |

### applyChartTemplate

Adds the platform chart template to an existing company: new accounts and hidden accounts. Never removes an account.

Requires: platform key or token · scope `platform_policies:write`.

```graphql
applyChartTemplate(platformId: ID, companyId: ID!): ChartTemplateApplied!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |

### promotePlatformPolicies

Sandbox only. Snapshots the active policies and returns a bundle id for production.

Requires: platform key or token.

```graphql
promotePlatformPolicies(platformId: ID, kinds: [PolicyKind!]): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `kinds` | `[PolicyKind!]` |  |

### previewPolicyImport

Production only. Fetches the sandbox bundle, verifies it and shows what would change.

Requires: platform key or token.

```graphql
previewPolicyImport(platformId: ID, bundleId: String!): PolicyImportPreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `bundleId` | `String!` |  |

### confirmPolicyImport

Requires: platform key or token.

```graphql
confirmPolicyImport(platformId: ID, importId: ID!): [PlatformPolicyVersion!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `importId` | `ID!` |  |

### upsertCustomAction

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
upsertCustomAction(platformId: ID, input: UpsertCustomActionInput!): PlatformCustomAction!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `UpsertCustomActionInput!` |  |

### deleteCustomAction

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
deleteCustomAction(platformId: ID, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### invokeCustomAction

A user clicked a custom action. Emits custom_action.invoked when the action delivers by webhook.

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
invokeCustomAction(platformId: ID, key: String!, contextType: String!, contextId: ID!): InvokedCustomAction!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `contextType` | `String!` |  |
| `contextId` | `ID!` |  |

### invokeSlotItem

A user clicked an item in a slot you rendered (headerActions, rowActions, ...). Same path as a custom action: emits custom_action.invoked.

Requires: platform key or token · scope `platform_extensions:read`.

```graphql
invokeSlotItem(platformId: ID, slot: String!, key: String!, contextType: String!, contextId: ID!): InvokedCustomAction!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `slot` | `String!` |  |
| `key` | `String!` |  |
| `contextType` | `String!` |  |
| `contextId` | `ID!` |  |

### upsertLinkTemplate

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
upsertLinkTemplate(platformId: ID, input: UpsertLinkTemplateInput!): PlatformLinkTemplate!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `UpsertLinkTemplateInput!` |  |

### deleteLinkTemplate

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
deleteLinkTemplate(platformId: ID, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### upsertCustomFieldDefinition

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
upsertCustomFieldDefinition(platformId: ID, input: UpsertCustomFieldDefinitionInput!): CustomFieldDefinition!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `UpsertCustomFieldDefinitionInput!` |  |

### archiveCustomFieldDefinition

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
archiveCustomFieldDefinition(platformId: ID, id: ID!): CustomFieldDefinition!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### setCustomFieldValues

Merges values into the object’s custom fields; null removes a key.

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
setCustomFieldValues(platformId: ID, entityType: String!, entityId: ID!, values: JSONObject!): JSONObject!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `entityType` | `String!` |  |
| `entityId` | `ID!` |  |
| `values` | `JSONObject!` |  |

### setFieldControl

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
setFieldControl(platformId: ID, input: SetFieldControlInput!): FieldControl!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `SetFieldControlInput!` |  |

### clearFieldControl

Requires: platform key or token · scope `platform_extensions:write`.

```graphql
clearFieldControl(platformId: ID, view: String!, field: String!, companyId: ID): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `view` | `String!` |  |
| `field` | `String!` |  |
| `companyId` | `ID` |  |

### definePlatformRecordType

Requires: platform key or token · scope `custom_records:write`.

```graphql
definePlatformRecordType(platformId: ID, input: DefineRecordTypeInput!): PlatformRecordType!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `DefineRecordTypeInput!` |  |

### upsertCustomRecord

Requires: platform key or token · scope `custom_records:write`.

```graphql
upsertCustomRecord(input: UpsertCustomRecordInput!): UpsertCustomRecordPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertCustomRecordInput!` |  |

### deleteCustomRecord

Requires: platform key or token · scope `custom_records:write`.

```graphql
deleteCustomRecord(company: CompanyRef!, type: String!, externalId: String!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `type` | `String!` |  |
| `externalId` | `String!` |  |

### saveFlowTemplate

Requires: platform key or token · scope `custom_records:write`.

```graphql
saveFlowTemplate(platformId: ID, source: String!, format: FlowTemplateFormat!): FlowTemplate!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `source` | `String!` |  |
| `format` | `FlowTemplateFormat!` |  |

### activateFlowTemplate

Requires: platform key or token · scope `custom_records:write`.

```graphql
activateFlowTemplate(platformId: ID, key: String!, version: Int!): FlowTemplate!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `version` | `Int!` |  |

### retireFlowTemplate

Requires: platform key or token · scope `custom_records:write`.

```graphql
retireFlowTemplate(platformId: ID, key: String!): FlowTemplate!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |

### testFlowTemplate

Requires: platform key or token · scope `custom_records:write`.

```graphql
testFlowTemplate(platformId: ID, source: String!, format: FlowTemplateFormat!, records: [JSON!]!, company: CompanyRef): FlowTemplateTestResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `source` | `String!` |  |
| `format` | `FlowTemplateFormat!` |  |
| `records` | `[JSON!]!` |  |
| `company` | `CompanyRef` |  |

### retryFlowRun

Requires: platform key or token · scope `custom_records:write`.

```graphql
retryFlowRun(platformId: ID, id: ID!): FlowRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### requestXafExport

Requires: platform key or token · scope `exports:write`.

```graphql
requestXafExport(company: CompanyRef!, financialYear: Int, from: String, to: String, version: String): PlatformExportRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `financialYear` | `Int` |  |
| `from` | `String` |  |
| `to` | `String` |  |
| `version` | `String` | Auditfile Financieel version: "4.0" (default; the only version the Belastingdienst accepts from 2027) or "3.2". |

### requestAuditLogExport

Requires: platform key or token · scope `exports:write`.

```graphql
requestAuditLogExport(filter: PlatformAuditLogFilter): PlatformExportRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `filter` | `PlatformAuditLogFilter` |  |

### createPlatformExportDestination

Requires: platform key or token · scope `exports:write`.

```graphql
createPlatformExportDestination(platformId: ID, input: CreateExportDestinationInput!): PlatformExportDestination!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `CreateExportDestinationInput!` |  |

### updatePlatformExportDestinationCredentials

Requires: platform key or token · scope `exports:write`.

```graphql
updatePlatformExportDestinationCredentials(platformId: ID, key: String!, credentials: JSON!, credentialsExpireAt: DateTime): PlatformExportDestination!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `credentials` | `JSON!` |  |
| `credentialsExpireAt` | `DateTime` |  |

### deletePlatformExportDestination

Requires: platform key or token · scope `exports:write`.

```graphql
deletePlatformExportDestination(platformId: ID, key: String!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |

### createPlatformExportSchedule

Requires: platform key or token · scope `exports:write`.

```graphql
createPlatformExportSchedule(platformId: ID, input: CreateExportScheduleInput!): PlatformExportSchedule!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `CreateExportScheduleInput!` |  |

### updatePlatformExportSchedule

Requires: platform key or token · scope `exports:write`.

```graphql
updatePlatformExportSchedule(platformId: ID, key: String!, input: UpdateExportScheduleInput!): PlatformExportSchedule!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `input` | `UpdateExportScheduleInput!` |  |

### runPlatformExportNow

Requires: platform key or token · scope `exports:write`.

```graphql
runPlatformExportNow(platformId: ID, key: String!, companies: [CompanyRef!]): PlatformExportRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `companies` | `[CompanyRef!]` | Limit this run to these companies (within the schedule's own scope). Watermarks of the other companies stay where they are, so their next run still carries their changes. |

### requestCompanyExport

Starts an export of the company for a calendar year: the audit file (XAF, built in the background; poll `companyExports`) or the profit and loss as PDF or Excel (ready at once).

Requires: platform key or token.

```graphql
requestCompanyExport(platformId: ID, companyId: ID!, kind: CompanyExportKind!, financialYear: Int): CompanyExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `kind` | `CompanyExportKind!` |  |
| `financialYear` | `Int` |  |

### upsertPlatformProvider

Requires: platform key or token · scope `platform_payments:write`.

```graphql
upsertPlatformProvider(input: UpsertPlatformProviderInput!): PlatformProvider!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertPlatformProviderInput!` |  |

### createTaxPaymentRequest

Requires: platform key or token · scope `platform_payments:write`.

```graphql
createTaxPaymentRequest(company: CompanyRef!, taxFilingId: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `taxFilingId` | `ID!` |  |

### createPaymentRequestFromBatch

Requires: platform key or token · scope `platform_payments:write`.

```graphql
createPaymentRequestFromBatch(company: CompanyRef!, paymentBatchId: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `company` | `CompanyRef!` |  |
| `paymentBatchId` | `ID!` |  |

### reportPaymentRequestStatus

Requires: platform key or token · scope `platform_payments:write`.

```graphql
reportPaymentRequestStatus(input: ReportPaymentRequestStatusInput!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ReportPaymentRequestStatusInput!` |  |

### cancelPaymentRequest

Requires: platform key or token · scope `platform_payments:write`.

```graphql
cancelPaymentRequest(id: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### providePaymentLink

Requires: platform key or token · scope `platform_payments:write` · feature `online_payments`.

```graphql
providePaymentLink(requestId: ID!, url: String!, expiresAt: DateTime): PaymentLinkRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `requestId` | `ID!` |  |
| `url` | `String!` |  |
| `expiresAt` | `DateTime` |  |

### reportTaxReservation

Requires: platform key or token · scope `platform_payments:write`.

```graphql
reportTaxReservation(adviceId: ID!, reservedMinor: Int!, accountRef: String): TaxReservationAdvice!
```

| Argument | Type |  |
| --- | --- | --- |
| `adviceId` | `ID!` |  |
| `reservedMinor` | `Int!` |  |
| `accountRef` | `String` |  |

### completeStepUpChallengeWithDeviceAssertion

Requires: platform key or token.

```graphql
completeStepUpChallengeWithDeviceAssertion(challengeId: ID!): StepUpChallenge!
```

| Argument | Type |  |
| --- | --- | --- |
| `challengeId` | `ID!` |  |

### approvePaymentRequest

Requires: platform key or token.

```graphql
approvePaymentRequest(id: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### previewPlatformPromotion

Production only. Fetches the sandbox config, validates it against the production allowance.

Requires: platform key or token.

```graphql
previewPlatformPromotion(platformId: ID!): PlatformPromotionPreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID!` |  |

### applyPlatformPromotion

Requires: platform key or token.

```graphql
applyPlatformPromotion(platformId: ID!, previewId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID!` |  |
| `previewId` | `ID!` |  |

### createTestClock

Requires: platform key or token · scope `platform_companies:write`.

```graphql
createTestClock(name: String!, frozenTime: DateTime!, platformId: ID): TestClock!
```

| Argument | Type |  |
| --- | --- | --- |
| `name` | `String!` |  |
| `frozenTime` | `DateTime!` |  |
| `platformId` | `ID` |  |

### advanceTestClock

Moves the clock to `to`, day by day, running the per-company jobs. Returns at once; the platform webhooks test_clock.ready and test_clock.failed report the end.

Requires: platform key or token · scope `platform_companies:write`.

```graphql
advanceTestClock(id: ID!, to: DateTime!, options: AdvanceTestClockOptionsInput, platformId: ID): TestClock!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `to` | `DateTime!` |  |
| `options` | `AdvanceTestClockOptionsInput` |  |
| `platformId` | `ID` |  |

### deleteTestClock

Deletes the clock and its companies.

Requires: platform key or token · scope `platform_companies:write`.

```graphql
deleteTestClock(id: ID!, platformId: ID): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `platformId` | `ID` |  |

### suspendPlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
suspendPlatformCompany(companyId: ID!, platformId: ID, reason: String, displayMessage: String): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |
| `reason` | `String` |  |
| `displayMessage` | `String` |  |

### reactivatePlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
reactivatePlatformCompany(companyId: ID!, platformId: ID): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |

### closePlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
closePlatformCompany(companyId: ID!, platformId: ID, effectiveDate: String!, reason: String): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |
| `effectiveDate` | `String!` | YYYY-MM-DD: the day the company stops trading. |
| `reason` | `String` |  |

### reopenPlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
reopenPlatformCompany(companyId: ID!, platformId: ID): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |

### archivePlatformCompany

Requires: platform key or token · scope `platform_companies:write`.

```graphql
archivePlatformCompany(companyId: ID!, platformId: ID): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `platformId` | `ID` | Portal callers: the platform. Tokens: omit. |

### createCompanyTransfer

Requires: platform key or token.

```graphql
createCompanyTransfer(companyId: ID!, target: CompanyTransferTarget!, email: String, statementVersion: String!, statementHash: String!, stepUpAssertionId: ID): CompanyTransferCreated!
```

| Argument | Type |  |
| --- | --- | --- |
| `companyId` | `ID!` |  |
| `target` | `CompanyTransferTarget!` |  |
| `email` | `String` |  |
| `statementVersion` | `String!` |  |
| `statementHash` | `String!` |  |
| `stepUpAssertionId` | `ID` |  |

### cancelCompanyTransfer

Requires: platform key or token · scope `platform_companies:write`.

```graphql
cancelCompanyTransfer(transferId: ID!): CompanyTransfer!
```

| Argument | Type |  |
| --- | --- | --- |
| `transferId` | `ID!` |  |

### acceptCompanyTransfer

Requires: platform key or token · scope `platform_companies:write`.

```graphql
acceptCompanyTransfer(code: String!, externalId: String): PlatformCompany!
```

| Argument | Type |  |
| --- | --- | --- |
| `code` | `String!` |  |
| `externalId` | `String` |  |

### deprovisionPlatformUser

Requires: platform key or token · scope `platform_users:write`.

```graphql
deprovisionPlatformUser(userId: ID!, anonymise: Boolean): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `userId` | `ID!` |  |
| `anonymise` | `Boolean` |  |

### updatePlatformSupportSettings

Requires: platform key or token · scope `support:write`.

```graphql
updatePlatformSupportSettings(input: PlatformSupportSettingsInput!): PlatformSupportSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `PlatformSupportSettingsInput!` |  |

### createSupportEscalation

Requires: platform key or token · scope `support:write`.

```graphql
createSupportEscalation(platformId: ID, input: CreateSupportEscalationInput!): SupportEscalation!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `CreateSupportEscalationInput!` |  |

### requestPlatformSupport

Requires: platform key or token.

```graphql
requestPlatformSupport(platformId: ID, companyId: ID!, screen: String, requestIds: [String!], componentVersion: String): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `companyId` | `ID!` |  |
| `screen` | `String` |  |
| `requestIds` | `[String!]` |  |
| `componentVersion` | `String` |  |

### addSupportEscalationComment

Requires: platform key or token · scope `support:write`.

```graphql
addSupportEscalationComment(platformId: ID, escalationId: ID!, body: String!): SupportEscalationComment!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `escalationId` | `ID!` |  |
| `body` | `String!` |  |

### decideSupportAccess

Requires: platform key or token · scope `support:write`.

```graphql
decideSupportAccess(platformId: ID, grantId: ID!, approve: Boolean!, attestation: String, stepUpAssertionId: ID): SupportAccessGrant!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `grantId` | `ID!` |  |
| `approve` | `Boolean!` |  |
| `attestation` | `String` |  |
| `stepUpAssertionId` | `ID` | Informational: the step-up proof travels in the FinBaze-Step-Up header (Wave 4.5). |

### revokeSupportAccess

Requires: platform key or token · scope `support:write`.

```graphql
revokeSupportAccess(platformId: ID, grantId: ID!): SupportAccessGrant!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `grantId` | `ID!` |  |

### setPlatformDataSourceStatus

Pause or resume a data source (portal).

Requires: platform key or token · scope `data_sources:write`.

```graphql
setPlatformDataSourceStatus(platformId: ID, key: String!, status: String!): PlatformDataSourceHealth!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `key` | `String!` |  |
| `status` | `String!` |  |

### requestPlatformDataSourceResync

Asks the platform to deliver a period of one company again: the attachment goes back to backfill pending and a data_source.resync_requested event is sent.

Requires: platform key or token · scope `data_sources:write`.

```graphql
requestPlatformDataSourceResync(input: RequestDataSourceResyncInput!): PlatformDataSourceHealth!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `RequestDataSourceResyncInput!` |  |


---

<!-- /reference/webhook-events/firms -->
# Webhook events: Accounting firms

Accountant connections. Payload samples.

Accountant connections. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## firm.access_requested

An accounting firm asked for access to a company. Show the request in your own UI; the company decides in accountant-connect.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "firm.access_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.authority_changed

The company changed which taxes the firm files.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "firm.authority_changed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.connected

An accounting firm now works the company in the FinBaze firm dashboard.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "firm.connected",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.connection_declined

A request between a company and a firm was declined (or withdrawn).

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "firm.connection_declined",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.connection_expired

A request between a company and a firm expired after 14 days without an answer.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "firm.connection_expired",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.connection_requested

A company invited an accounting firm; the firm has not accepted yet.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "firm.connection_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.disconnect_scheduled

The engagement ends at a set time because accountant access was hidden for the company; the key can still be shown again to cancel it.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "firm.disconnect_scheduled",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## firm.disconnected

The engagement ended: firm access, BECON use and HMRC client authorisations stopped; the books stay with the company.

Object: `firm_engagement`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "firm.disconnected",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "FirmEngagement",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/graphql/agents -->
# Agents

GraphQL operations: agents.

## Mutations

### createAgentTask

Requires: scope `agents:write`.

```graphql
createAgentTask(input: CreateAgentTaskInput!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateAgentTaskInput!` |  |

### cancelAgentTask

Requires: scope `agents:write`.

```graphql
cancelAgentTask(taskId: ID!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `taskId` | `ID!` |  |

### pauseAgentTask

Requires: scope `agents:write`.

```graphql
pauseAgentTask(taskId: ID!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `taskId` | `ID!` |  |

### resumeAgentTask

Requires: scope `agents:write`.

```graphql
resumeAgentTask(taskId: ID!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `taskId` | `ID!` |  |

### replyToAgentTask

Requires: scope `agents:write`.

```graphql
replyToAgentTask(taskId: ID!, body: String!): AgentTaskMessage!
```

| Argument | Type |  |
| --- | --- | --- |
| `taskId` | `ID!` |  |
| `body` | `String!` |  |

### updateAgentTaskAutonomy

Requires: scope `agents:write`.

```graphql
updateAgentTaskAutonomy(taskId: ID!, autonomy: AgentAutonomy!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `taskId` | `ID!` |  |
| `autonomy` | `AgentAutonomy!` |  |

### createRecurringAgentTask

Repeat a task on a schedule. Creates a private agent with the goal and installs it; manage it like any installed agent.

Requires: scope `agents:write` · feature `subscription_invoices`.

```graphql
createRecurringAgentTask(input: CreateRecurringAgentTaskInput!): AgentInstallation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateRecurringAgentTaskInput!` |  |

### createComputerAgentTask

Requires: scope `agents:write`.

```graphql
createComputerAgentTask(input: CreateComputerAgentTaskInput!): AgentTask!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateComputerAgentTaskInput!` |  |

### planComputerAgentTask

Draft a computer task from a plain-language description (uses a few AI credits). Nothing runs until the draft is confirmed.

Requires: scope `agents:write`.

```graphql
planComputerAgentTask(input: PlanComputerAgentTaskInput!): AgentComputerPlan!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `PlanComputerAgentTaskInput!` |  |

### scheduleComputerAgentTask

Run a computer task on a schedule. Shows up under "Your agents" like other recurring tasks.

Requires: scope `agents:write`.

```graphql
scheduleComputerAgentTask(input: ScheduleComputerAgentTaskInput!): AgentInstallation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ScheduleComputerAgentTaskInput!` |  |


---

<!-- /reference/webhook-events/support -->
# Webhook events: Support

Support requests, escalations and consented access. Payload samples.

Support requests, escalations and consented access. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## support.access_expired

A support grant reached its end.

Object: `support_access_grant`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "support.access_expired",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "reason": "example",
      "scope": "read",
      "status": "requested",
      "durationMinutes": 1,
      "requestedAt": "2026-03-02T10:00:00.000Z",
      "activatedAt": "2026-03-02T10:00:00.000Z",
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "escalationId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "breakGlass": false,
      "requestedBy": "finbaze_support"
    }
  }
}
```

## support.access_granted

A support access request was approved; FinBaze support can view the company until `expiresAt`.

Object: `support_access_grant`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "support.access_granted",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "reason": "example",
      "scope": "read",
      "status": "requested",
      "durationMinutes": 1,
      "requestedAt": "2026-03-02T10:00:00.000Z",
      "activatedAt": "2026-03-02T10:00:00.000Z",
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "escalationId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "breakGlass": false,
      "requestedBy": "finbaze_support",
      "decidedVia": "embed"
    }
  }
}
```

## support.access_requested

FinBaze support asked to view a company. The company admin decides.

Object: `support_access_grant`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "support.access_requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "reason": "example",
      "scope": "read",
      "status": "requested",
      "durationMinutes": 1,
      "requestedAt": "2026-03-02T10:00:00.000Z",
      "activatedAt": "2026-03-02T10:00:00.000Z",
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "escalationId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "breakGlass": false,
      "requestedBy": "finbaze_support"
    }
  }
}
```

## support.access_revoked

A live support grant was ended early.

Object: `support_access_grant`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "support.access_revoked",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "reason": "example",
      "scope": "read",
      "status": "requested",
      "durationMinutes": 1,
      "requestedAt": "2026-03-02T10:00:00.000Z",
      "activatedAt": "2026-03-02T10:00:00.000Z",
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "escalationId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "breakGlass": false,
      "requestedBy": "finbaze_support",
      "revokedAt": "2026-03-02T10:00:00.000Z",
      "revokedBy": "company"
    }
  }
}
```

## support.break_glass

FinBaze opened a company without consent (two admins, read only, at most two hours).

Object: `support_access_grant`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "support.break_glass",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "reason": "example",
      "scope": "read",
      "status": "requested",
      "durationMinutes": 1,
      "requestedAt": "2026-03-02T10:00:00.000Z",
      "activatedAt": "2026-03-02T10:00:00.000Z",
      "expiresAt": "2026-03-02T10:00:00.000Z",
      "escalationId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "breakGlass": true,
      "requestedBy": "finbaze_support",
      "twoAdminApproval": true
    }
  }
}
```

## support.escalation.created

An escalation to FinBaze support was created.

Object: `support_escalation`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "support.escalation.created",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "subject": "example",
      "severity": "low",
      "status": "open",
      "source": "platform",
      "requestIds": [
        "example"
      ],
      "screen": "example",
      "created": "2026-03-02T10:00:00.000Z",
      "updated": "2026-03-02T10:00:00.000Z"
    }
  }
}
```

## support.escalation.updated

An escalation changed status or severity, or got a comment.

Object: `support_escalation`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "support.escalation.updated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "subject": "example",
      "severity": "low",
      "status": "open",
      "source": "platform",
      "requestIds": [
        "example"
      ],
      "screen": "example",
      "created": "2026-03-02T10:00:00.000Z",
      "updated": "2026-03-02T10:00:00.000Z",
      "change": "status",
      "commentId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "commentAuthor": "platform"
    }
  }
}
```

## support.requested

A company user asked for help in contact-support and the platform handles support (`partner_first`).

Object: `support_request`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "support.requested",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "screen": "example",
      "requestIds": [
        "example"
      ],
      "componentVersion": "example",
      "userId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/graphql/assets -->
# Assets

GraphQL operations: assets.

## Queries

### assetTypes

Requires: scope `assets:read` · feature `assets`.

```graphql
assetTypes(profileId: ID!): [AssetTypeOption!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### asset

Requires: scope `assets:read` · feature `assets`.

```graphql
asset(id: ID!): Asset!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### assets

Requires: scope `assets:read` · feature `assets`.

```graphql
assets(paging: CursorPaging!, filter: AssetFilter!, sorting: [AssetSort!]!): AssetConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `AssetFilter!` | Specify to filter the records returned. |
| `sorting` | `[AssetSort!]!` | Specify to sort results. |

### assetWriteoff

Requires: scope `assets:read` · feature `assets`.

```graphql
assetWriteoff(id: ID!): AssetWriteoff!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### assetWriteoffs

Requires: scope `assets:read` · feature `assets`.

```graphql
assetWriteoffs(paging: CursorPaging!, filter: AssetWriteoffFilter!, sorting: [AssetWriteoffSort!]!): AssetWriteoffConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `AssetWriteoffFilter!` | Specify to filter the records returned. |
| `sorting` | `[AssetWriteoffSort!]!` | Specify to sort results. |

### assetRevaluation

Requires: scope `assets:read` · feature `assets`.

```graphql
assetRevaluation(id: ID!): AssetRevaluation!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### assetRevaluations

Requires: scope `assets:read` · feature `assets`.

```graphql
assetRevaluations(paging: CursorPaging!, filter: AssetRevaluationFilter!, sorting: [AssetRevaluationSort!]!): AssetRevaluationConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `AssetRevaluationFilter!` | Specify to filter the records returned. |
| `sorting` | `[AssetRevaluationSort!]!` | Specify to sort results. |

## Mutations

### createOneAsset

Requires: scope `assets:write` · feature `assets`.

```graphql
createOneAsset(profileId: ID!, input: CreateAssetInput!): Asset!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateAssetInput!` |  |

### createManyAssets

Requires: scope `assets:write` · feature `assets`.

```graphql
createManyAssets(profileId: ID!, input: [CreateAssetInput!]!): [Asset!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateAssetInput!]!` |  |

### createOneAssetWriteoff

Requires: scope `assets:write` · feature `assets`.

```graphql
createOneAssetWriteoff(assetId: ID!, input: CreateAssetWriteoffInput!): AssetWriteoff!
```

| Argument | Type |  |
| --- | --- | --- |
| `assetId` | `ID!` |  |
| `input` | `CreateAssetWriteoffInput!` |  |

### createManyAssetWriteoffs

Requires: scope `assets:write` · feature `assets`.

```graphql
createManyAssetWriteoffs(assetId: ID!, input: [CreateAssetWriteoffInput!]!): [AssetWriteoff!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `assetId` | `ID!` |  |
| `input` | `[CreateAssetWriteoffInput!]!` |  |

### createOneAssetRevaluation

Requires: scope `assets:write` · feature `assets`.

```graphql
createOneAssetRevaluation(assetId: ID!, input: CreateAssetRevaluationInput!): AssetRevaluation!
```

| Argument | Type |  |
| --- | --- | --- |
| `assetId` | `ID!` |  |
| `input` | `CreateAssetRevaluationInput!` |  |

### createManyAssetRevaluations

Requires: scope `assets:write` · feature `assets`.

```graphql
createManyAssetRevaluations(assetId: ID!, input: [CreateAssetRevaluationInput!]!): [AssetRevaluation!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `assetId` | `ID!` |  |
| `input` | `[CreateAssetRevaluationInput!]!` |  |

### updateOneAsset

Requires: scope `assets:write` · feature `assets`.

```graphql
updateOneAsset(input: UpdateOneAssetInput!): Asset!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneAssetInput!` |  |

### updateManyAssets

Requires: scope `assets:write` · feature `assets`.

```graphql
updateManyAssets(input: UpdateManyAssetsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyAssetsInput!` |  |

### deleteOneAsset

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteOneAsset(input: DeleteOneAssetInput!): AssetDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneAssetInput!` |  |

### deleteManyAssets

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteManyAssets(input: DeleteManyAssetsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyAssetsInput!` |  |

### updateOneAssetWriteoff

Requires: scope `assets:write` · feature `assets`.

```graphql
updateOneAssetWriteoff(input: UpdateOneAssetWriteoffInput!): AssetWriteoff!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneAssetWriteoffInput!` |  |

### updateManyAssetWriteoffs

Requires: scope `assets:write` · feature `assets`.

```graphql
updateManyAssetWriteoffs(input: UpdateManyAssetWriteoffsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyAssetWriteoffsInput!` |  |

### deleteOneAssetWriteoff

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteOneAssetWriteoff(input: DeleteOneAssetWriteoffInput!): AssetWriteoffDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneAssetWriteoffInput!` |  |

### deleteManyAssetWriteoffs

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteManyAssetWriteoffs(input: DeleteManyAssetWriteoffsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyAssetWriteoffsInput!` |  |

### updateOneAssetRevaluation

Requires: scope `assets:write` · feature `assets`.

```graphql
updateOneAssetRevaluation(input: UpdateOneAssetRevaluationInput!): AssetRevaluation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneAssetRevaluationInput!` |  |

### updateManyAssetRevaluations

Requires: scope `assets:write` · feature `assets`.

```graphql
updateManyAssetRevaluations(input: UpdateManyAssetRevaluationsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyAssetRevaluationsInput!` |  |

### deleteOneAssetRevaluation

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteOneAssetRevaluation(input: DeleteOneAssetRevaluationInput!): AssetRevaluationDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneAssetRevaluationInput!` |  |

### deleteManyAssetRevaluations

Requires: scope `assets:write` · feature `assets`.

```graphql
deleteManyAssetRevaluations(input: DeleteManyAssetRevaluationsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyAssetRevaluationsInput!` |  |


---

<!-- /reference/webhook-events/platform -->
# Webhook events: Platform: policies, quotas and agents

Policy changes, quotas, usage reports, partner alerts and agent tasks. Payload samples.

Policy changes, quotas, usage reports, partner alerts and agent tasks. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## agent_task.completed

An agent task completed.

Object: `agent_task` · module `ai.agents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "agent_task.completed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "AgentTask",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## agent_task.failed

An agent task failed.

Object: `agent_task` · module `ai.agents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "agent_task.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "AgentTask",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## agent_task.waiting_approval

An agent task waits for approval.

Object: `agent_task` · module `ai.agents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "agent_task.waiting_approval",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "AgentTask",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## agent_task.waiting_input

An agent task waits for input.

Object: `agent_task` · module `ai.agents`: no event is published for a company where it is hidden or off.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b13",
  "object": "event",
  "type": "agent_task.waiting_input",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1003",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "AgentTask",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## billing.usage.reported

The month's usage was closed and reported.

Object: `platform_usage`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b14",
  "object": "event",
  "type": "billing.usage.reported",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1004",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PlatformUsage",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## platform.alert

Something needs the platform's attention: a failing or disabled webhook endpoint, a stalled feed, a rejected filing.

Object: `platform_alert`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b15",
  "object": "event",
  "type": "platform.alert",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1005",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "kind": "webhook_endpoint_failing",
      "severity": "info",
      "status": "open",
      "title": "example",
      "subject": {
        "type": "webhook_endpoint",
        "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
      },
      "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "detail": {},
      "raisedAt": "2026-03-02T10:00:00.000Z",
      "resolvedAt": "2026-03-02T10:00:00.000Z"
    }
  }
}
```

## policy.activated

A policy version was activated (also by a promotion).

Object: `platform_policy`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b16",
  "object": "event",
  "type": "policy.activated",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1006",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "PlatformPolicy",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```

## quota.reached

A company reached one of its quotas for the month.

Object: none (the event's own fields).

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b17",
  "object": "event",
  "type": "quota.reached",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1007",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "__typename": "Event",
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
    }
  }
}
```


---

<!-- /reference/graphql/automations -->
# Automations

GraphQL operations: automations.

## Mutations

### draftAutomation

Drafts an automation from a plain-language description. Nothing is saved: the editor opens the draft for review.

Requires: scope `automations:write` · feature `automations`.

```graphql
draftAutomation(ownerType: AutomationOwnerType!, ownerId: ID!, request: String!): AutomationDraftModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `ownerType` | `AutomationOwnerType!` |  |
| `ownerId` | `ID!` |  |
| `request` | `String!` |  |

### createAutomation

Requires: scope `automations:write` · feature `automations`.

```graphql
createAutomation(input: CreateAutomationInput!): AutomationModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateAutomationInput!` |  |

### updateAutomation

Requires: scope `automations:write` · feature `automations`.

```graphql
updateAutomation(id: ID!, input: UpdateAutomationInput!): AutomationModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `UpdateAutomationInput!` |  |

### setAutomationEnabled

Requires: scope `automations:write` · feature `automations`.

```graphql
setAutomationEnabled(id: ID!, enabled: Boolean!): AutomationModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `enabled` | `Boolean!` |  |

### deleteAutomation

Requires: scope `automations:write` · feature `automations`.

```graphql
deleteAutomation(id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### simulateAutomation

Requires: scope `automations:write` · feature `automations`.

```graphql
simulateAutomation(id: ID!, input: SimulateAutomationInput): AutomationRunDetail!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `SimulateAutomationInput` |  |


---

<!-- /reference/webhook-events/sandbox -->
# Webhook events: Sandbox

Test clocks and the sandbox reset. Payload samples.

Test clocks and the sandbox reset. Samples show the envelope; `data.object` of an event that has a snapshot carries the object's fields as of the event (shown here with its type and id). See the [envelope](/reference/webhook-events).

## sandbox.reset.completed

The nightly or manual reset of the platform sandbox finished (sandbox only).

Object: `sandbox_reset`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b10",
  "object": "event",
  "type": "sandbox.reset.completed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1000",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "trigger": "nightly",
      "companiesDeleted": 1,
      "companiesKept": 1,
      "clocksDeleted": 1,
      "companiesSeeded": [
        {
          "template": "example",
          "externalId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
          "companyId": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34"
        }
      ],
      "errors": [
        "example"
      ],
      "startedAt": "2026-03-02T10:00:00.000Z",
      "finishedAt": "2026-03-02T10:00:00.000Z"
    }
  }
}
```

## test_clock.failed

A test clock stopped because the advance failed (sandbox only).

Object: `test_clock`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b11",
  "object": "event",
  "type": "test_clock.failed",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1001",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "name": "example",
      "status": "failed",
      "testClockTime": "2026-03-02T10:00:00.000Z",
      "__typename": "Event",
      "error": {
        "message": "example"
      }
    }
  }
}
```

## test_clock.ready

A test clock finished advancing (sandbox only).

Object: `test_clock`.

```json
{
  "id": "evt_3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b12",
  "object": "event",
  "type": "test_clock.ready",
  "apiVersion": "2026-11-01",
  "created": "2026-03-02T10:00:00.000Z",
  "occurredAt": "2026-03-02T09:59:58.000Z",
  "sequence": "1002",
  "livemode": false,
  "platform": "00000000-0000-4000-8000-0000000000aa",
  "company": {
    "id": "00000000-0000-4000-8000-0000000000bb",
    "externalId": "biz-1001"
  },
  "request": null,
  "data": {
    "object": {
      "id": "3f2b1c9e-5a47-4d1e-9c0b-2a6d8e7f1b34",
      "name": "example",
      "status": "ready",
      "testClockTime": "2026-03-02T10:00:00.000Z",
      "__typename": "Event",
      "advancedFrom": "2026-03-02T10:00:00.000Z",
      "days": 3,
      "warnings": [
        "example"
      ]
    }
  }
}
```


---

<!-- /reference/graphql/budgets -->
# Budgets

GraphQL operations: budgets.

## Queries

### budgets

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgets(profileId: ID!, financialYearId: ID!): [BudgetModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `financialYearId` | `ID!` |  |

### budget

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budget(id: ID!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### budgetActiveLedgers

Profit-and-loss ledger codes in use: prior book-year activity and/or non-zero working budget lines.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetActiveLedgers(id: ID!, language: String): [String!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `language` | `String` |  |

### budgetCanSeedFromPriorYear

Whether any other book year on the profile has profit and loss to seed a budget from.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetCanSeedFromPriorYear(profileId: ID!, financialYearId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `financialYearId` | `ID!` |  |

### budgetSeedSourceYears

Book years on the profile (other than the target year) that have matching months and profit-and-loss actuals.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetSeedSourceYears(profileId: ID!, financialYearId: ID!): [BudgetSeedSourceYearModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `financialYearId` | `ID!` |  |

### suggestKnownBudgetSources

Preview plan lines FinBaze can fill from asset depreciation schedules and loan interest for a book year.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
suggestKnownBudgetSources(profileId: ID!, financialYearId: ID!): BudgetKnownSourcesPreviewModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `financialYearId` | `ID!` |  |

### budgetComparison

Locked baseline, working forecast, and live P&L actuals. Actuals use the same windows as the profit-and-loss statement.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetComparison(id: ID!, asOf: DateTime, language: String): BudgetComparisonModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `asOf` | `DateTime` |  |
| `language` | `String` |  |

### budgetVsActual

Budget, actual, committed and available for cost ledgers over a period range (YYYY-MM, default the whole book year), per cost center or per ledger. Cost-center budget comes from budget sub-lines; actuals from cost centers on purchase invoice lines and P&L bank/settlement lines. Costs without a cost center (including payroll) are under "none". Committed is the open commitments (approved requests and purchase orders not invoiced yet); null when committed spend is off for the company.

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetVsActual(id: ID!, groupBy: BudgetVsActualGroupBy!, fromPeriod: String, toPeriod: String, language: String): BudgetVsActualModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `groupBy` | `BudgetVsActualGroupBy!` |  |
| `fromPeriod` | `String` |  |
| `toPeriod` | `String` |  |
| `language` | `String` |  |

### budgetLiquidity

Liquidity projection for a budget (P&L→cash with DSO/DPO, VAT, payroll, events).

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetLiquidity(id: ID!, horizon: BudgetLiquidityHorizon): BudgetLiquidityModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `horizon` | `BudgetLiquidityHorizon` |  |

### budgetCashEvents

Dated cash events on a budget (financing schedule or liquidity layers).

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetCashEvents(id: ID!): [BudgetCashEventModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### budgetVarianceActions

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetVarianceActions(id: ID!): [BudgetVarianceActionModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### budgetVarianceActionSummary

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetVarianceActionSummary(id: ID!): BudgetVarianceActionSummaryModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### budgetPrognoseOverrides

Requires: scope `budgets:read` · feature `budgets`.

```graphql
budgetPrognoseOverrides(id: ID!): [BudgetPrognoseOverrideModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### summarizeBudgetVariance

On-demand natural-language summary of budget vs actuals (categories off green + year-end landing).

Requires: scope `budgets:read` · feature `budgets`.

```graphql
summarizeBudgetVariance(id: ID!, asOf: DateTime, language: String): BudgetVarianceNlSummaryModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `asOf` | `DateTime` |  |
| `language` | `String` |  |

### compareBudgets

Side-by-side P&L category year totals for budgets in the same book year (scenarios).

Requires: scope `budgets:read` · feature `budgets`.

```graphql
compareBudgets(ids: [ID!]!, language: String): BudgetScenarioCompareModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `ids` | `[ID!]!` |  |
| `language` | `String` |  |

### budgetAvailability

Budget left for a ledger and/or cost center: budget − actual − open commitments over the book year that contains period (YYYY-MM), or over period..toPeriod. Budget and actuals per ledger (RGS); until budgets per cost center exist, a cost center gets its ledger figures with scope "ledger". A ledger without a budget gives budget null (no budget set; nothing is over budget). Cents of the company currency.

Requires: scope `budgets:read` · feature `commitments`.

```graphql
budgetAvailability(profileId: ID!, period: String!, ledger: String, costCenterId: ID, toPeriod: String): BudgetAvailabilityResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `period` | `String!` |  |
| `ledger` | `String` |  |
| `costCenterId` | `ID` |  |
| `toPeriod` | `String` |  |

## Mutations

### createBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
createBudget(profileId: ID!, financialYearId: ID!, name: String!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `financialYearId` | `ID!` |  |
| `name` | `String!` |  |

### updateBudgetSettings

Requires: scope `budgets:write` · feature `budgets`.

```graphql
updateBudgetSettings(id: ID!, name: String, thresholdAmountCents: Int, thresholdBps: Int, horizonEndPeriod: String): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `name` | `String` |  |
| `thresholdAmountCents` | `Int` |  |
| `thresholdBps` | `Int` |  |
| `horizonEndPeriod` | `String` |  |

### replaceBudgetThresholds

Requires: scope `budgets:write` · feature `budgets`.

```graphql
replaceBudgetThresholds(id: ID!, thresholds: [BudgetThresholdInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `thresholds` | `[BudgetThresholdInput!]!` |  |

### approveBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
approveBudget(id: ID!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### lockBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
lockBudget(id: ID!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### reviseBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
reviseBudget(id: ID!, effectiveFrom: String!, reason: String!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `effectiveFrom` | `String!` |  |
| `reason` | `String!` |  |

### copyBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
copyBudget(id: ID!, name: String!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `name` | `String!` |  |

### seedBudgetFromPriorYear

Requires: scope `budgets:write` · feature `budgets`.

```graphql
seedBudgetFromPriorYear(id: ID!, factorBps: Int!, language: String, sourceFinancialYearId: ID): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `factorBps` | `Int!` |  |
| `language` | `String` |  |
| `sourceFinancialYearId` | `ID` |  |

### applyKnownBudgetSources

Fill plan lines from asset depreciation and loan interest schedules for the budget book year.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
applyKnownBudgetSources(id: ID!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### replaceBudgetDrivers

Requires: scope `budgets:write` · feature `budgets`.

```graphql
replaceBudgetDrivers(id: ID!, drivers: [BudgetDriverInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `drivers` | `[BudgetDriverInput!]!` |  |

### regenerateBudgetDrivers

Recompute driver-owned plan lines on the editable working version. Manual edits on those accounts are replaced.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
regenerateBudgetDrivers(id: ID!, language: String): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `language` | `String` |  |

### replaceBudgetVariables

Requires: scope `budgets:write` · feature `budgets`.

```graphql
replaceBudgetVariables(id: ID!, variables: [BudgetVariableInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `variables` | `[BudgetVariableInput!]!` |  |

### replaceBudgetFormulas

Requires: scope `budgets:write` · feature `budgets`.

```graphql
replaceBudgetFormulas(id: ID!, formulas: [BudgetFormulaInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `formulas` | `[BudgetFormulaInput!]!` |  |

### replaceBudgetSublines

Requires: scope `budgets:write` · feature `budgets`.

```graphql
replaceBudgetSublines(id: ID!, sublines: [BudgetSublineInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `sublines` | `[BudgetSublineInput!]!` |  |

### regenerateBudgetFormulas

Recompute formula-owned plan lines on the editable working version. Manual edits on those rows are replaced.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
regenerateBudgetFormulas(id: ID!, language: String): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `language` | `String` |  |

### migrateBudgetPercentDriversToFormulas

Create or update row formulas from percent-of-revenue drivers. Product volume drivers are unchanged.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
migrateBudgetPercentDriversToFormulas(id: ID!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### upsertBudgetSublineLines

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetSublineLines(id: ID!, lines: [UpsertBudgetSublineLineInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `lines` | `[UpsertBudgetSublineLineInput!]!` |  |

### upsertBudgetLines

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetLines(id: ID!, lines: [UpsertBudgetLineInput!]!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `lines` | `[UpsertBudgetLineInput!]!` |  |

### deleteBudget

Requires: scope `budgets:write` · feature `budgets`.

```graphql
deleteBudget(id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### upsertBudgetLiquiditySettings

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetLiquiditySettings(id: ID!, settings: UpsertBudgetLiquiditySettingsInput!): BudgetLiquiditySettingsModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `settings` | `UpsertBudgetLiquiditySettingsInput!` |  |

### upsertBudgetCashEvents

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetCashEvents(id: ID!, events: [BudgetCashEventInput!]!): [BudgetCashEventModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `events` | `[BudgetCashEventInput!]!` |  |

### upsertBudgetVarianceAction

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetVarianceAction(id: ID!, input: UpsertBudgetVarianceActionInput!): BudgetVarianceActionModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `UpsertBudgetVarianceActionInput!` |  |

### deleteBudgetVarianceAction

Requires: scope `budgets:write` · feature `budgets`.

```graphql
deleteBudgetVarianceAction(id: ID!, actionId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `actionId` | `ID!` |  |

### upsertBudgetPrognoseOverrides

Requires: scope `budgets:write` · feature `budgets`.

```graphql
upsertBudgetPrognoseOverrides(id: ID!, overrides: [BudgetPrognoseOverrideInput!]!): [BudgetPrognoseOverrideModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `overrides` | `[BudgetPrognoseOverrideInput!]!` |  |

### redistributeBudgetLines

Re-spread editable months evenly or proportionally (herverdelen).

Requires: scope `budgets:write` · feature `budgets`.

```graphql
redistributeBudgetLines(id: ID!, input: RedistributeBudgetLinesInput!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `RedistributeBudgetLinesInput!` |  |

### distributeBudgetTopDown

Distribute a category/section year target down to leaf months.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
distributeBudgetTopDown(id: ID!, input: DistributeBudgetTopDownInput!): BudgetModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `DistributeBudgetTopDownInput!` |  |

### generateBudgetDraft

Seed the working plan from a prior book year (deterministic), optionally fill empty chart leaves with AI proposals.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
generateBudgetDraft(id: ID!, factorBps: Int!, language: String, sourceFinancialYearId: ID, fillGapsWithAi: Boolean, hint: String): BudgetAiDraftResultModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `factorBps` | `Int!` |  |
| `language` | `String` |  |
| `sourceFinancialYearId` | `ID` |  |
| `fillGapsWithAi` | `Boolean` |  |
| `hint` | `String` |  |

### applyBudgetNlAdjustment

Parse a natural-language instruction into line/formula upserts. Formulas are cycle-checked before save.

Requires: scope `budgets:write` · feature `budgets`.

```graphql
applyBudgetNlAdjustment(id: ID!, instruction: String!, language: String): BudgetNlAdjustmentResultModel!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `instruction` | `String!` |  |
| `language` | `String` |  |


---

<!-- /reference/graphql/clients -->
# Clients

GraphQL operations: clients.

## Mutations

### setBookkeeperClientServiceMode

Set what the firm delivers for a client administration: bookkeeping, bookkeeping + payroll, or payroll only (no client fee, payroll access only).

Requires: scope `clients:write`.

```graphql
setBookkeeperClientServiceMode(bookkeeperId: ID!, profileId: ID!, mode: BookkeeperServiceMode!): Profile!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |
| `mode` | `BookkeeperServiceMode!` |  |

### createBookkeeperClientBillingPlan

Requires: scope `clients:write`.

```graphql
createBookkeeperClientBillingPlan(bookkeeperId: ID!, input: CreateBookkeeperClientBillingPlanInput!): BookkeeperClientBillingPlanDto!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `input` | `CreateBookkeeperClientBillingPlanInput!` |  |

### updateBookkeeperClientBillingPlan

Requires: scope `clients:write`.

```graphql
updateBookkeeperClientBillingPlan(bookkeeperId: ID!, planId: ID!, input: UpdateBookkeeperClientBillingPlanInput!): BookkeeperClientBillingPlanDto!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `planId` | `ID!` |  |
| `input` | `UpdateBookkeeperClientBillingPlanInput!` |  |

### deleteBookkeeperClientBillingPlan

Requires: scope `clients:write`.

```graphql
deleteBookkeeperClientBillingPlan(bookkeeperId: ID!, planId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `planId` | `ID!` |  |

### duplicateBookkeeperClientBillingPlan

Requires: scope `clients:write`.

```graphql
duplicateBookkeeperClientBillingPlan(bookkeeperId: ID!, planId: ID!): BookkeeperClientBillingPlanDto!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `planId` | `ID!` |  |

### createBookkeeperClientProfile

Requires: scope `clients:write`.

```graphql
createBookkeeperClientProfile(bookkeeperId: ID!, input: CreateBookkeeperClientProfileInput!): Profile!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `input` | `CreateBookkeeperClientProfileInput!` |  |

### deactivateBookkeeperClientProfile

Requires: scope `clients:write`.

```graphql
deactivateBookkeeperClientProfile(bookkeeperId: ID!, profileId: ID!): Profile!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |

### reactivateBookkeeperClientProfile

Requires: scope `clients:write`.

```graphql
reactivateBookkeeperClientProfile(bookkeeperId: ID!, profileId: ID!): Profile!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |

### createBookkeeperClientConnectInvite

Requires: scope `clients:write`.

```graphql
createBookkeeperClientConnectInvite(input: CreateBookkeeperClientConnectInviteInput!): CreateBookkeeperClientConnectInviteResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateBookkeeperClientConnectInviteInput!` |  |

### cancelBookkeeperClientConnectInvite

Requires: scope `clients:write`.

```graphql
cancelBookkeeperClientConnectInvite(inviteId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `inviteId` | `ID!` |  |

### acceptBookkeeperClientConnectInvite

Requires: scope `clients:write`.

```graphql
acceptBookkeeperClientConnectInvite(token: String!, profileId: ID!): AcceptBookkeeperClientConnectInviteResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `token` | `String!` |  |
| `profileId` | `ID!` |  |

### completeBookkeeperClientConnectBilling

Requires: scope `clients:write`.

```graphql
completeBookkeeperClientConnectBilling(token: String!, planId: ID): ClientBillingSubscriptionSetup!
```

| Argument | Type |  |
| --- | --- | --- |
| `token` | `String!` |  |
| `planId` | `ID` |  |


---

<!-- /reference/graphql/cost-centers -->
# Cost centers

GraphQL operations: cost centers.

## Queries

### costCenter

Requires: scope `cost_centers:read` · feature `cost_centers`.

```graphql
costCenter(id: ID!): CostCenter!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### costCenters

Requires: scope `cost_centers:read` · feature `cost_centers`.

```graphql
costCenters(paging: CursorPaging!, filter: CostCenterFilter!, sorting: [CostCenterSort!]!): CostCenterConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `CostCenterFilter!` | Specify to filter the records returned. |
| `sorting` | `[CostCenterSort!]!` | Specify to sort results. |

### spendRequestCostCenters

Active cost centers a purchase request can be put on (number, name, owner). Open to requesters, who cannot list cost centers otherwise.

Requires: scope `cost_centers:read` · feature `spend_requests`.

```graphql
spendRequestCostCenters(profileId: ID!): [SpendCostCenterOption!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

## Mutations

### createOneCostCenter

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
createOneCostCenter(profileId: ID!, input: CreateCostCenterInput!): CostCenter!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateCostCenterInput!` |  |

### createManyCostCenters

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
createManyCostCenters(profileId: ID!, input: [CreateCostCenterInput!]!): [CostCenter!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateCostCenterInput!]!` |  |

### updateOneCostCenter

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
updateOneCostCenter(input: UpdateOneCostCenterInput!): CostCenter!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneCostCenterInput!` |  |

### updateManyCostCenters

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
updateManyCostCenters(input: UpdateManyCostCentersInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyCostCentersInput!` |  |

### deleteOneCostCenter

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
deleteOneCostCenter(input: DeleteOneCostCenterInput!): CostCenterDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneCostCenterInput!` |  |

### deleteManyCostCenters

Requires: scope `cost_centers:write` · feature `cost_centers`.

```graphql
deleteManyCostCenters(input: DeleteManyCostCentersInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyCostCentersInput!` |  |


---

<!-- /reference/graphql/current-accounts -->
# Current accounts

GraphQL operations: current accounts.

## Queries

### currentAccount

Requires: scope `current_accounts:read` · feature `current_accounts`.

```graphql
currentAccount(id: ID!): CurrentAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### currentAccounts

Requires: scope `current_accounts:read` · feature `current_accounts`.

```graphql
currentAccounts(paging: CursorPaging!, filter: CurrentAccountFilter!, sorting: [CurrentAccountSort!]!): CurrentAccountConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `CurrentAccountFilter!` | Specify to filter the records returned. |
| `sorting` | `[CurrentAccountSort!]!` | Specify to sort results. |

## Mutations

### createOneCurrentAccount

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
createOneCurrentAccount(profileId: ID!, input: CreateCurrentAccountInput!): CurrentAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateCurrentAccountInput!` |  |

### createManyCurrentAccounts

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
createManyCurrentAccounts(profileId: ID!, input: [CreateCurrentAccountInput!]!): [CurrentAccount!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateCurrentAccountInput!]!` |  |

### updateOneCurrentAccount

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
updateOneCurrentAccount(input: UpdateOneCurrentAccountInput!): CurrentAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneCurrentAccountInput!` |  |

### updateManyCurrentAccounts

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
updateManyCurrentAccounts(input: UpdateManyCurrentAccountsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyCurrentAccountsInput!` |  |

### deleteOneCurrentAccount

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
deleteOneCurrentAccount(input: DeleteOneCurrentAccountInput!): CurrentAccountDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneCurrentAccountInput!` |  |

### deleteManyCurrentAccounts

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
deleteManyCurrentAccounts(input: DeleteManyCurrentAccountsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyCurrentAccountsInput!` |  |

### registerIntercompanyCurrentAccounts

Requires: scope `current_accounts:write` · feature `current_accounts`.

```graphql
registerIntercompanyCurrentAccounts(profileIdA: ID!, profileIdB: ID!, currency: Currency): RegisterIntercompanyCurrentAccountsResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileIdA` | `ID!` |  |
| `profileIdB` | `ID!` |  |
| `currency` | `Currency` |  |


---

<!-- /reference/graphql/dashboard -->
# Dashboard

GraphQL operations: dashboard.

## Queries

### profileDashboard

Requires: scope `dashboard:read`.

```graphql
profileDashboard(profileId: ID!, start: DateTime, end: DateTime, language: String): ProfileDashboard!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `start` | `DateTime` |  |
| `end` | `DateTime` |  |
| `language` | `String` |  |


---

<!-- /reference/graphql/document-requests -->
# Document requests

GraphQL operations: document requests.

## Queries

### documentRequestsInbox

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequestsInbox(profileId: ID!, status: DocumentRequestInboxStatus!, search: String, after: String): DocumentRequestPage!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `status` | `DocumentRequestInboxStatus!` |  |
| `search` | `String` |  |
| `after` | `String` |  |

### documentRequestDetail

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequestDetail(id: ID!): DocumentRequestDetail!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### documentRequestMessage

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequestMessage(id: ID!): DocumentRequestMessage!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### documentRequestMessages

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequestMessages(paging: CursorPaging!, filter: DocumentRequestMessageFilter!, sorting: [DocumentRequestMessageSort!]!): DocumentRequestMessageConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `DocumentRequestMessageFilter!` | Specify to filter the records returned. |
| `sorting` | `[DocumentRequestMessageSort!]!` | Specify to sort results. |

### documentRequest

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequest(id: ID!): DocumentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### documentRequests

Requires: scope `document_requests:read` · feature `document_requests`.

```graphql
documentRequests(paging: CursorPaging!, filter: DocumentRequestFilter!, sorting: [DocumentRequestSort!]!): DocumentRequestConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `DocumentRequestFilter!` | Specify to filter the records returned. |
| `sorting` | `[DocumentRequestSort!]!` | Specify to sort results. |

## Mutations

### createDocumentRequests

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
createDocumentRequests(profileId: ID!, input: [CreateDocumentRequestItemInput!]!): [DocumentRequest!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateDocumentRequestItemInput!]!` |  |

### addDocumentRequestMessage

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
addDocumentRequestMessage(documentRequestId: ID!, message: String!, attachments: [String!]): DocumentRequestMessage!
```

| Argument | Type |  |
| --- | --- | --- |
| `documentRequestId` | `ID!` |  |
| `message` | `String!` |  |
| `attachments` | `[String!]` |  |

### fulfillDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
fulfillDocumentRequest(documentRequestId: ID!, files: [DocumentRequestFileUploadInput!]!, message: String): DocumentRequestDetail!
```

| Argument | Type |  |
| --- | --- | --- |
| `documentRequestId` | `ID!` |  |
| `files` | `[DocumentRequestFileUploadInput!]!` |  |
| `message` | `String` |  |

### answerDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
answerDocumentRequest(input: AnswerDocumentRequestInput!): DocumentRequestDetail!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `AnswerDocumentRequestInput!` |  |

### cancelDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
cancelDocumentRequest(id: ID!): DocumentRequestDetail!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createOneDocumentRequestMessage

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
createOneDocumentRequestMessage(documentRequestId: ID!, input: CreateDocumentRequestMessageInput!): DocumentRequestMessage!
```

| Argument | Type |  |
| --- | --- | --- |
| `documentRequestId` | `ID!` |  |
| `input` | `CreateDocumentRequestMessageInput!` |  |

### createManyDocumentRequestMessages

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
createManyDocumentRequestMessages(documentRequestId: ID!, input: [CreateDocumentRequestMessageInput!]!): [DocumentRequestMessage!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `documentRequestId` | `ID!` |  |
| `input` | `[CreateDocumentRequestMessageInput!]!` |  |

### createOneDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
createOneDocumentRequest(profileId: ID!, input: CreateDocumentRequestInput!): DocumentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateDocumentRequestInput!` |  |

### createManyDocumentRequests

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
createManyDocumentRequests(profileId: ID!, input: [CreateDocumentRequestInput!]!): [DocumentRequest!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateDocumentRequestInput!]!` |  |

### updateOneDocumentRequestMessage

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
updateOneDocumentRequestMessage(input: UpdateOneDocumentRequestMessageInput!): DocumentRequestMessage!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneDocumentRequestMessageInput!` |  |

### updateManyDocumentRequestMessages

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
updateManyDocumentRequestMessages(input: UpdateManyDocumentRequestMessagesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyDocumentRequestMessagesInput!` |  |

### deleteOneDocumentRequestMessage

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
deleteOneDocumentRequestMessage(input: DeleteOneDocumentRequestMessageInput!): DocumentRequestMessageDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneDocumentRequestMessageInput!` |  |

### deleteManyDocumentRequestMessages

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
deleteManyDocumentRequestMessages(input: DeleteManyDocumentRequestMessagesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyDocumentRequestMessagesInput!` |  |

### updateOneDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
updateOneDocumentRequest(input: UpdateOneDocumentRequestInput!): DocumentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneDocumentRequestInput!` |  |

### updateManyDocumentRequests

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
updateManyDocumentRequests(input: UpdateManyDocumentRequestsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyDocumentRequestsInput!` |  |

### deleteOneDocumentRequest

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
deleteOneDocumentRequest(input: DeleteOneDocumentRequestInput!): DocumentRequestDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneDocumentRequestInput!` |  |

### deleteManyDocumentRequests

Requires: scope `document_requests:write` · feature `document_requests`.

```graphql
deleteManyDocumentRequests(input: DeleteManyDocumentRequestsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyDocumentRequestsInput!` |  |


---

<!-- /reference/graphql/employees -->
# Employees

GraphQL operations: employees.

## Queries

### employeeAttachment

Requires: scope `employees:read` · feature `payroll`.

```graphql
employeeAttachment(id: ID!): EmployeeAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### employee

Requires: scope `employees:read` · feature `payroll`.

```graphql
employee(id: ID!): Employee!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### employees

Requires: scope `employees:read` · feature `payroll`.

```graphql
employees(paging: CursorPaging!, filter: EmployeeFilter!, sorting: [EmployeeSort!]!): EmployeeConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `EmployeeFilter!` | Specify to filter the records returned. |
| `sorting` | `[EmployeeSort!]!` | Specify to sort results. |

### employeeBsn

Requires: scope `employees:read` · feature `payroll`.

```graphql
employeeBsn(employeeId: ID!): EmployeeBsn!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |

### employeeIdDocument

Requires: scope `employees:read` · feature `payroll`.

```graphql
employeeIdDocument(employeeId: ID!): EmployeeIdDocument
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |

### nlEmployeeWageTaxCreditPeriod

Requires: scope `employees:read` · feature `payroll`.

```graphql
nlEmployeeWageTaxCreditPeriod(id: ID!): NlEmployeeWageTaxCreditPeriod!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### nlEmployeeWageTaxCreditPeriods

Requires: scope `employees:read` · feature `payroll`.

```graphql
nlEmployeeWageTaxCreditPeriods(paging: CursorPaging!, filter: NlEmployeeWageTaxCreditPeriodFilter!, sorting: [NlEmployeeWageTaxCreditPeriodSort!]!): NlEmployeeWageTaxCreditPeriodConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `NlEmployeeWageTaxCreditPeriodFilter!` | Specify to filter the records returned. |
| `sorting` | `[NlEmployeeWageTaxCreditPeriodSort!]!` | Specify to sort results. |

## Mutations

### createOneEmployeeAttachment

Requires: scope `employees:write` · feature `payroll`.

```graphql
createOneEmployeeAttachment(employeeId: ID!, input: CreateEmployeeAttachmentInput!): EmployeeAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |
| `input` | `CreateEmployeeAttachmentInput!` |  |

### deleteOneEmployeeAttachment

Requires: scope `employees:write` · feature `payroll`.

```graphql
deleteOneEmployeeAttachment(input: DeleteOneEmployeeAttachmentInput!): EmployeeAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEmployeeAttachmentInput!` |  |

### setEmployeeNetPayIban

Requires: scope `employees:write` · feature `payroll`.

```graphql
setEmployeeNetPayIban(input: SetEmployeeNetPayIbanInput!): Employee!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetEmployeeNetPayIbanInput!` |  |

### createOneEmployee

Requires: scope `employees:write` · feature `payroll`.

```graphql
createOneEmployee(profileId: ID!, input: CreateEmployeeInput!): Employee!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateEmployeeInput!` |  |

### createManyEmployees

Requires: scope `employees:write` · feature `payroll`.

```graphql
createManyEmployees(profileId: ID!, input: [CreateEmployeeInput!]!): [Employee!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateEmployeeInput!]!` |  |

### updateOneEmployee

Requires: scope `employees:write` · feature `payroll`.

```graphql
updateOneEmployee(input: UpdateOneEmployeeInput!): Employee!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneEmployeeInput!` |  |

### updateManyEmployees

Requires: scope `employees:write` · feature `payroll`.

```graphql
updateManyEmployees(input: UpdateManyEmployeesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyEmployeesInput!` |  |

### deleteOneEmployee

Requires: scope `employees:write` · feature `payroll`.

```graphql
deleteOneEmployee(input: DeleteOneEmployeeInput!): EmployeeDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEmployeeInput!` |  |

### deleteManyEmployees

Requires: scope `employees:write` · feature `payroll`.

```graphql
deleteManyEmployees(input: DeleteManyEmployeesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyEmployeesInput!` |  |

### setEmployeeBsn

Requires: scope `employees:write` · feature `payroll`.

```graphql
setEmployeeBsn(input: SetEmployeeBsnInput!): EmployeeBsn!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetEmployeeBsnInput!` |  |

### clearEmployeeBsn

Requires: scope `employees:write` · feature `payroll`.

```graphql
clearEmployeeBsn(employeeId: ID!): EmployeeBsn!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |

### setEmployeeIdDocument

Requires: scope `employees:write` · feature `payroll`.

```graphql
setEmployeeIdDocument(input: SetEmployeeIdDocumentInput!): EmployeeIdDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetEmployeeIdDocumentInput!` |  |

### verifyEmployeeIdDocument

Requires: scope `employees:write` · feature `payroll`.

```graphql
verifyEmployeeIdDocument(employeeId: ID!): EmployeeIdDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |

### clearEmployeeIdDocument

Requires: scope `employees:write` · feature `payroll`.

```graphql
clearEmployeeIdDocument(employeeId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `ID!` |  |

### createOneNlEmployeeWageTaxCreditPeriod

Requires: scope `employees:write` · feature `payroll`.

```graphql
createOneNlEmployeeWageTaxCreditPeriod(profileId: ID!, input: CreateNlEmployeeWageTaxCreditPeriodInput!): NlEmployeeWageTaxCreditPeriod!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateNlEmployeeWageTaxCreditPeriodInput!` |  |

### createManyNlEmployeeWageTaxCreditPeriods

Requires: scope `employees:write` · feature `payroll`.

```graphql
createManyNlEmployeeWageTaxCreditPeriods(profileId: ID!, input: [CreateNlEmployeeWageTaxCreditPeriodInput!]!): [NlEmployeeWageTaxCreditPeriod!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateNlEmployeeWageTaxCreditPeriodInput!]!` |  |

### updateOneNlEmployeeWageTaxCreditPeriod

Requires: scope `employees:write` · feature `payroll`.

```graphql
updateOneNlEmployeeWageTaxCreditPeriod(input: UpdateOneNlEmployeeWageTaxCreditPeriodInput!): NlEmployeeWageTaxCreditPeriod!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneNlEmployeeWageTaxCreditPeriodInput!` |  |

### updateManyNlEmployeeWageTaxCreditPeriods

Requires: scope `employees:write` · feature `payroll`.

```graphql
updateManyNlEmployeeWageTaxCreditPeriods(input: UpdateManyNlEmployeeWageTaxCreditPeriodsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyNlEmployeeWageTaxCreditPeriodsInput!` |  |

### deleteOneNlEmployeeWageTaxCreditPeriod

Requires: scope `employees:write` · feature `payroll`.

```graphql
deleteOneNlEmployeeWageTaxCreditPeriod(input: DeleteOneNlEmployeeWageTaxCreditPeriodInput!): NlEmployeeWageTaxCreditPeriodDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneNlEmployeeWageTaxCreditPeriodInput!` |  |

### deleteManyNlEmployeeWageTaxCreditPeriods

Requires: scope `employees:write` · feature `payroll`.

```graphql
deleteManyNlEmployeeWageTaxCreditPeriods(input: DeleteManyNlEmployeeWageTaxCreditPeriodsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyNlEmployeeWageTaxCreditPeriodsInput!` |  |


---

<!-- /reference/versions -->
# Versions

The versions of the API, the webhook payloads and the SDKs at the time of the last docs build.

Generated at build time from the code. How versions work and what each release asks of you: [Upgrading](/guides/upgrading). Every change: [Changelog](/changelog).

| Surface | Version | Notes |
| --- | --- | --- |
| Webhook payloads and events API | `2026-11-01` | In every delivery as `apiVersion` and `X-FinBaze-Api-Version`. Pinning per platform is not available yet. |
| GraphQL schema | one schema | Changes are announced in the [changelog](/changelog). 1084 operations are reachable with a platform key or token. |
| `@finbaze/embed-js` | 0.1.0 | Browser SDK, semver, `0.x`. |
| `@finbaze/embed-react` | 0.1.0 | React components and `/headless` hooks, semver, `0.x`. |
| `@finbaze/platform-sdk` | 1.0 | Node server SDK; built and tested against the sandbox, npm release pending. |
| Components | 80 | See [component props](/components/reference). |
| Webhook events | 126 available, 2 planned | See [webhook events](/reference/webhook-events). |
| Error codes | 159 | See [errors](/reference/errors). |
| Sandbox API | `https://sandbox.api.platform.finbaze.com` | Test keys (`fb_sk_test_…`). |
| Live API | `https://api.platform.finbaze.com` | Live keys (`fb_sk_live_…`). |


---

<!-- /reference/graphql/employments -->
# Employments

GraphQL operations: employments.

## Queries

### employmentAttachment

Requires: scope `employments:read` · feature `payroll`.

```graphql
employmentAttachment(id: ID!): EmploymentAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### nlEmploymentAttrs

Requires: scope `employments:read` · feature `payroll`.

```graphql
nlEmploymentAttrs(paging: CursorPaging!, filter: NlEmploymentAttrsFilter!, sorting: [NlEmploymentAttrsSort!]!): NlEmploymentAttrsConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `NlEmploymentAttrsFilter!` | Specify to filter the records returned. |
| `sorting` | `[NlEmploymentAttrsSort!]!` | Specify to sort results. |

### employment

Requires: scope `employments:read` · feature `payroll`.

```graphql
employment(id: ID!): Employment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### employments

Requires: scope `employments:read` · feature `payroll`.

```graphql
employments(paging: CursorPaging!, filter: EmploymentFilter!, sorting: [EmploymentSort!]!): EmploymentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `EmploymentFilter!` | Specify to filter the records returned. |
| `sorting` | `[EmploymentSort!]!` | Specify to sort results. |

### vehicleEmploymentAssignment

Requires: scope `employments:read` · feature `vehicles`.

```graphql
vehicleEmploymentAssignment(id: ID!): VehicleEmploymentAssignment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### vehicleEmploymentAssignments

Requires: scope `employments:read` · feature `vehicles`.

```graphql
vehicleEmploymentAssignments(paging: CursorPaging!, filter: VehicleEmploymentAssignmentFilter!, sorting: [VehicleEmploymentAssignmentSort!]!): VehicleEmploymentAssignmentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `VehicleEmploymentAssignmentFilter!` | Specify to filter the records returned. |
| `sorting` | `[VehicleEmploymentAssignmentSort!]!` | Specify to sort results. |

### employmentWorkSchedule

Requires: scope `employments:read` · feature `payroll`.

```graphql
employmentWorkSchedule(id: ID!): EmploymentWorkSchedule!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### employmentWorkSchedules

Requires: scope `employments:read` · feature `payroll`.

```graphql
employmentWorkSchedules(paging: CursorPaging!, filter: EmploymentWorkScheduleFilter!, sorting: [EmploymentWorkScheduleSort!]!): EmploymentWorkScheduleConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `EmploymentWorkScheduleFilter!` | Specify to filter the records returned. |
| `sorting` | `[EmploymentWorkScheduleSort!]!` | Specify to sort results. |

## Mutations

### createOneEmploymentAttachment

Requires: scope `employments:write` · feature `payroll`.

```graphql
createOneEmploymentAttachment(employmentId: ID!, input: CreateEmploymentAttachmentInput!): EmploymentAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `employmentId` | `ID!` |  |
| `input` | `CreateEmploymentAttachmentInput!` |  |

### deleteOneEmploymentAttachment

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteOneEmploymentAttachment(input: DeleteOneEmploymentAttachmentInput!): EmploymentAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEmploymentAttachmentInput!` |  |

### finalizeEmploymentTerms

Requires: scope `employments:write` · feature `payroll`.

```graphql
finalizeEmploymentTerms(employmentId: ID!): Employment!
```

| Argument | Type |  |
| --- | --- | --- |
| `employmentId` | `ID!` |  |

### applyEmploymentTermsChange

Requires: scope `employments:write` · feature `payroll`.

```graphql
applyEmploymentTermsChange(input: ApplyEmploymentTermsChangeInput!): EmploymentTermsRevision!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ApplyEmploymentTermsChangeInput!` |  |

### extendEmployment

Requires: scope `employments:write` · feature `payroll`.

```graphql
extendEmployment(input: ExtendEmploymentInput!): Employment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ExtendEmploymentInput!` |  |

### createOneNlEmploymentAttrs

Requires: scope `employments:write` · feature `payroll`.

```graphql
createOneNlEmploymentAttrs(profileId: ID!, input: CreateNlEmploymentAttrsInput!): NlEmploymentAttrs!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateNlEmploymentAttrsInput!` |  |

### createManyNlEmploymentAttrs

Requires: scope `employments:write` · feature `payroll`.

```graphql
createManyNlEmploymentAttrs(profileId: ID!, input: [CreateNlEmploymentAttrsInput!]!): [NlEmploymentAttrs!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateNlEmploymentAttrsInput!]!` |  |

### createOneEmployment

Requires: scope `employments:write` · feature `payroll`.

```graphql
createOneEmployment(profileId: ID!, input: CreateEmploymentInput!): Employment!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateEmploymentInput!` |  |

### createManyEmployments

Requires: scope `employments:write` · feature `payroll`.

```graphql
createManyEmployments(profileId: ID!, input: [CreateEmploymentInput!]!): [Employment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateEmploymentInput!]!` |  |

### createOneVehicleEmploymentAssignment

Requires: scope `employments:write` · feature `vehicles`.

```graphql
createOneVehicleEmploymentAssignment(profileId: ID!, input: CreateVehicleEmploymentAssignmentInput!): VehicleEmploymentAssignment!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateVehicleEmploymentAssignmentInput!` |  |

### createManyVehicleEmploymentAssignments

Requires: scope `employments:write` · feature `vehicles`.

```graphql
createManyVehicleEmploymentAssignments(profileId: ID!, input: [CreateVehicleEmploymentAssignmentInput!]!): [VehicleEmploymentAssignment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateVehicleEmploymentAssignmentInput!]!` |  |

### updateOneNlEmploymentAttrs

Requires: scope `employments:write` · feature `payroll`.

```graphql
updateOneNlEmploymentAttrs(input: UpdateOneNlEmploymentAttrsInput!): NlEmploymentAttrs!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneNlEmploymentAttrsInput!` |  |

### deleteOneNlEmploymentAttrs

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteOneNlEmploymentAttrs(input: DeleteOneNlEmploymentAttrsInput!): NlEmploymentAttrsDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneNlEmploymentAttrsInput!` |  |

### deleteManyNlEmploymentAttrs

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteManyNlEmploymentAttrs(input: DeleteManyNlEmploymentAttrsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyNlEmploymentAttrsInput!` |  |

### updateOneEmployment

Requires: scope `employments:write` · feature `payroll`.

```graphql
updateOneEmployment(input: UpdateOneEmploymentInput!): Employment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneEmploymentInput!` |  |

### updateManyEmployments

Requires: scope `employments:write` · feature `payroll`.

```graphql
updateManyEmployments(input: UpdateManyEmploymentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyEmploymentsInput!` |  |

### deleteOneEmployment

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteOneEmployment(input: DeleteOneEmploymentInput!): EmploymentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEmploymentInput!` |  |

### deleteManyEmployments

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteManyEmployments(input: DeleteManyEmploymentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyEmploymentsInput!` |  |

### updateOneVehicleEmploymentAssignment

Requires: scope `employments:write` · feature `vehicles`.

```graphql
updateOneVehicleEmploymentAssignment(input: UpdateOneVehicleEmploymentAssignmentInput!): VehicleEmploymentAssignment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneVehicleEmploymentAssignmentInput!` |  |

### updateManyVehicleEmploymentAssignments

Requires: scope `employments:write` · feature `vehicles`.

```graphql
updateManyVehicleEmploymentAssignments(input: UpdateManyVehicleEmploymentAssignmentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyVehicleEmploymentAssignmentsInput!` |  |

### deleteOneVehicleEmploymentAssignment

Requires: scope `employments:write` · feature `vehicles`.

```graphql
deleteOneVehicleEmploymentAssignment(input: DeleteOneVehicleEmploymentAssignmentInput!): VehicleEmploymentAssignmentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneVehicleEmploymentAssignmentInput!` |  |

### deleteManyVehicleEmploymentAssignments

Requires: scope `employments:write` · feature `vehicles`.

```graphql
deleteManyVehicleEmploymentAssignments(input: DeleteManyVehicleEmploymentAssignmentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyVehicleEmploymentAssignmentsInput!` |  |

### createOneEmploymentWorkSchedule

Requires: scope `employments:write` · feature `payroll`.

```graphql
createOneEmploymentWorkSchedule(profileId: ID!, input: CreateEmploymentWorkScheduleInput!): EmploymentWorkSchedule!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateEmploymentWorkScheduleInput!` |  |

### createManyEmploymentWorkSchedules

Requires: scope `employments:write` · feature `payroll`.

```graphql
createManyEmploymentWorkSchedules(profileId: ID!, input: [CreateEmploymentWorkScheduleInput!]!): [EmploymentWorkSchedule!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateEmploymentWorkScheduleInput!]!` |  |

### updateOneEmploymentWorkSchedule

Requires: scope `employments:write` · feature `payroll`.

```graphql
updateOneEmploymentWorkSchedule(input: UpdateOneEmploymentWorkScheduleInput!): EmploymentWorkSchedule!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneEmploymentWorkScheduleInput!` |  |

### updateManyEmploymentWorkSchedules

Requires: scope `employments:write` · feature `payroll`.

```graphql
updateManyEmploymentWorkSchedules(input: UpdateManyEmploymentWorkSchedulesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyEmploymentWorkSchedulesInput!` |  |

### deleteOneEmploymentWorkSchedule

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteOneEmploymentWorkSchedule(input: DeleteOneEmploymentWorkScheduleInput!): EmploymentWorkScheduleDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEmploymentWorkScheduleInput!` |  |

### deleteManyEmploymentWorkSchedules

Requires: scope `employments:write` · feature `payroll`.

```graphql
deleteManyEmploymentWorkSchedules(input: DeleteManyEmploymentWorkSchedulesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyEmploymentWorkSchedulesInput!` |  |


---

<!-- /reference/graphql/financial-years -->
# Financial years

GraphQL operations: financial years.

## Queries

### financialYear

Requires: scope `financial_years:read`.

```graphql
financialYear(id: ID!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### financialYears

Requires: scope `financial_years:read`.

```graphql
financialYears(paging: CursorPaging!, filter: FinancialYearFilter!, sorting: [FinancialYearSort!]!): FinancialYearConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `FinancialYearFilter!` | Specify to filter the records returned. |
| `sorting` | `[FinancialYearSort!]!` | Specify to sort results. |

## Mutations

### createFinancialYear

Requires: scope `financial_years:write`.

```graphql
createFinancialYear(input: FinancialYearInput!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `FinancialYearInput!` |  |

### regenerateFinancialYearPeriods

Requires: scope `financial_years:write`.

```graphql
regenerateFinancialYearPeriods(id: ID!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### closeFinancialYear

Requires: scope `financial_years:write`.

```graphql
closeFinancialYear(id: ID!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### deleteFinancialYear

Requires: scope `financial_years:write`.

```graphql
deleteFinancialYear(id: ID!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### reopenFinancialYear

Requires: scope `financial_years:write`.

```graphql
reopenFinancialYear(id: ID!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createOneFinancialYear

Requires: scope `financial_years:write`.

```graphql
createOneFinancialYear(profileId: ID!, input: CreateFinancialYearInput!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateFinancialYearInput!` |  |

### createManyFinancialYears

Requires: scope `financial_years:write`.

```graphql
createManyFinancialYears(profileId: ID!, input: [CreateFinancialYearInput!]!): [FinancialYear!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateFinancialYearInput!]!` |  |

### updateOneFinancialYear

Requires: scope `financial_years:write`.

```graphql
updateOneFinancialYear(input: UpdateOneFinancialYearInput!): FinancialYear!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneFinancialYearInput!` |  |

### updateManyFinancialYears

Requires: scope `financial_years:write`.

```graphql
updateManyFinancialYears(input: UpdateManyFinancialYearsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyFinancialYearsInput!` |  |

### deleteOneFinancialYear

Requires: scope `financial_years:write`.

```graphql
deleteOneFinancialYear(input: DeleteOneFinancialYearInput!): FinancialYearDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneFinancialYearInput!` |  |

### deleteManyFinancialYears

Requires: scope `financial_years:write`.

```graphql
deleteManyFinancialYears(input: DeleteManyFinancialYearsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyFinancialYearsInput!` |  |


---

<!-- /reference/graphql/general-ledger -->
# General ledger

GraphQL operations: general ledger.

## Mutations

### createEnterpriseMemorial

Requires: scope `general_ledger:write`.

```graphql
createEnterpriseMemorial(enterpriseId: ID!, input: CreateEnterpriseMemorialInput!): EnterpriseMemorial!
```

| Argument | Type |  |
| --- | --- | --- |
| `enterpriseId` | `ID!` |  |
| `input` | `CreateEnterpriseMemorialInput!` |  |

### updateEnterpriseMemorial

Requires: scope `general_ledger:write`.

```graphql
updateEnterpriseMemorial(enterpriseId: ID!, input: UpdateEnterpriseMemorialInput!): EnterpriseMemorial!
```

| Argument | Type |  |
| --- | --- | --- |
| `enterpriseId` | `ID!` |  |
| `input` | `UpdateEnterpriseMemorialInput!` |  |

### deleteEnterpriseMemorial

Requires: scope `general_ledger:write`.

```graphql
deleteEnterpriseMemorial(id: ID!): EnterpriseMemorialDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |


---

<!-- /reference/graphql/ledger-chart -->
# Ledger chart

GraphQL operations: ledger chart.

## Queries

### ledgerChart

Requires: scope `ledger_chart:read`.

```graphql
ledgerChart(profileId: ID!, language: String): LedgerChart!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `language` | `String` |  |


---

<!-- /reference/graphql/loans -->
# Loans

GraphQL operations: loans.

## Queries

### loanAttachment

Requires: scope `loans:read` · feature `loans`.

```graphql
loanAttachment(id: ID!): LoanAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### loan

Requires: scope `loans:read` · feature `loans`.

```graphql
loan(id: ID!): Loan!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### loans

Requires: scope `loans:read` · feature `loans`.

```graphql
loans(paging: CursorPaging!, filter: LoanFilter!, sorting: [LoanSort!]!): LoanConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `LoanFilter!` | Specify to filter the records returned. |
| `sorting` | `[LoanSort!]!` | Specify to sort results. |

### loanInstallment

Requires: scope `loans:read` · feature `loans`.

```graphql
loanInstallment(id: ID!): LoanInstallment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### loanInstallments

Requires: scope `loans:read` · feature `loans`.

```graphql
loanInstallments(paging: CursorPaging!, filter: LoanInstallmentFilter!, sorting: [LoanInstallmentSort!]!): LoanInstallmentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `LoanInstallmentFilter!` | Specify to filter the records returned. |
| `sorting` | `[LoanInstallmentSort!]!` | Specify to sort results. |

## Mutations

### createOneLoanAttachment

Requires: scope `loans:write` · feature `loans`.

```graphql
createOneLoanAttachment(loanId: ID!, input: CreateLoanAttachmentInput!): LoanAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `loanId` | `ID!` |  |
| `input` | `CreateLoanAttachmentInput!` |  |

### deleteOneLoanAttachment

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteOneLoanAttachment(input: DeleteOneLoanAttachmentInput!): LoanAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneLoanAttachmentInput!` |  |

### seedFinancingBudgetFromLoans

Replace loan-seeded financing cash events on a budget from loan installments in the book year. Manual events are kept.

Requires: scope `loans:write` · feature `budgets`.

```graphql
seedFinancingBudgetFromLoans(id: ID!): [BudgetCashEventModel!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### deleteLoan

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteLoan(id: ID!): ID!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### updateLoanInstallmentAmounts

Requires: scope `loans:write` · feature `loans`.

```graphql
updateLoanInstallmentAmounts(input: UpdateLoanInstallmentAmountsInput!): LoanInstallment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateLoanInstallmentAmountsInput!` |  |

### createOneLoan

Requires: scope `loans:write` · feature `loans`.

```graphql
createOneLoan(profileId: ID!, input: CreateLoanInput!): Loan!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateLoanInput!` |  |

### createManyLoans

Requires: scope `loans:write` · feature `loans`.

```graphql
createManyLoans(profileId: ID!, input: [CreateLoanInput!]!): [Loan!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateLoanInput!]!` |  |

### createOneLoanInstallment

Requires: scope `loans:write` · feature `loans`.

```graphql
createOneLoanInstallment(loanId: ID!, input: CreateLoanInstallmentInput!): LoanInstallment!
```

| Argument | Type |  |
| --- | --- | --- |
| `loanId` | `ID!` |  |
| `input` | `CreateLoanInstallmentInput!` |  |

### createManyLoanInstallments

Requires: scope `loans:write` · feature `loans`.

```graphql
createManyLoanInstallments(loanId: ID!, input: [CreateLoanInstallmentInput!]!): [LoanInstallment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `loanId` | `ID!` |  |
| `input` | `[CreateLoanInstallmentInput!]!` |  |

### updateOneLoan

Requires: scope `loans:write` · feature `loans`.

```graphql
updateOneLoan(input: UpdateOneLoanInput!): Loan!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneLoanInput!` |  |

### updateManyLoans

Requires: scope `loans:write` · feature `loans`.

```graphql
updateManyLoans(input: UpdateManyLoansInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyLoansInput!` |  |

### deleteOneLoan

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteOneLoan(input: DeleteOneLoanInput!): LoanDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneLoanInput!` |  |

### deleteManyLoans

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteManyLoans(input: DeleteManyLoansInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyLoansInput!` |  |

### updateOneLoanInstallment

Requires: scope `loans:write` · feature `loans`.

```graphql
updateOneLoanInstallment(input: UpdateOneLoanInstallmentInput!): LoanInstallment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneLoanInstallmentInput!` |  |

### updateManyLoanInstallments

Requires: scope `loans:write` · feature `loans`.

```graphql
updateManyLoanInstallments(input: UpdateManyLoanInstallmentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyLoanInstallmentsInput!` |  |

### deleteOneLoanInstallment

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteOneLoanInstallment(input: DeleteOneLoanInstallmentInput!): LoanInstallmentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneLoanInstallmentInput!` |  |

### deleteManyLoanInstallments

Requires: scope `loans:write` · feature `loans`.

```graphql
deleteManyLoanInstallments(input: DeleteManyLoanInstallmentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyLoanInstallmentsInput!` |  |


---

<!-- /reference/graphql/messages -->
# Messages

GraphQL operations: messages.

## Queries

### messageCatalogue

Requires: scope `messages:read`.

```graphql
messageCatalogue(platformId: ID): [MessageTypeView!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformMessages

Requires: scope `messages:read`.

```graphql
platformMessages(platformId: ID, filter: PlatformMessageFilter): [PlatformMessageView!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `filter` | `PlatformMessageFilter` |  |

### platformMessageRouting

Requires: scope `messages:read`.

```graphql
platformMessageRouting(platformId: ID, profileId: ID): [MessageRoutingRuleView!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `profileId` | `ID` |  |

### platformMessageSettings

Requires: scope `messages:read`.

```graphql
platformMessageSettings(platformId: ID): PlatformMessageSettingsView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### platformMessageCopy

Requires: scope `messages:read`.

```graphql
platformMessageCopy(type: String): [PlatformMessageCopy!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `type` | `String` |  |

### previewPlatformMessageCopy

Requires: scope `messages:read`.

```graphql
previewPlatformMessageCopy(type: String!, variant: String!, template: String!, data: JSONObject!): PlatformMessageCopyPreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `type` | `String!` |  |
| `variant` | `String!` |  |
| `template` | `String!` |  |
| `data` | `JSONObject!` |  |

## Mutations

### sendAssistantMessage

Requires: scope `messages:write` · feature `ai_assistant`.

```graphql
sendAssistantMessage(profileId: ID, bookkeeperId: ID, enterpriseId: ID, conversationId: ID!, input: SendAssistantMessageInput!): AssistantMessageView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID` |  |
| `bookkeeperId` | `ID` |  |
| `enterpriseId` | `ID` |  |
| `conversationId` | `ID!` |  |
| `input` | `SendAssistantMessageInput!` |  |

### rateAssistantMessage

Requires: scope `messages:write` · feature `ai_assistant`.

```graphql
rateAssistantMessage(profileId: ID, bookkeeperId: ID, enterpriseId: ID, messageId: ID!, input: RateAssistantMessageInput!): AssistantMessageView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID` |  |
| `bookkeeperId` | `ID` |  |
| `enterpriseId` | `ID` |  |
| `messageId` | `ID!` |  |
| `input` | `RateAssistantMessageInput!` |  |

### requestBookkeeperMessageChannel

Requires: scope `messages:write`.

```graphql
requestBookkeeperMessageChannel(bookkeeperId: ID!, type: MessageChannelType): RequestBookkeeperMessageChannelResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `type` | `MessageChannelType` |  |

### updateBookkeeperMessageChannel

Requires: scope `messages:write`.

```graphql
updateBookkeeperMessageChannel(bookkeeperId: ID!, input: UpdateBookkeeperMessageChannelInput!, type: MessageChannelType): BookkeeperMessageChannelConfigView!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `input` | `UpdateBookkeeperMessageChannelInput!` |  |
| `type` | `MessageChannelType` |  |

### disableBookkeeperMessageChannel

Requires: scope `messages:write`.

```graphql
disableBookkeeperMessageChannel(bookkeeperId: ID!, type: MessageChannelType): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `type` | `MessageChannelType` |  |

### acknowledgeMessage

Requires: scope `messages:write`.

```graphql
acknowledgeMessage(platformId: ID, input: AcknowledgeMessageInput!): PlatformMessageView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `AcknowledgeMessageInput!` |  |

### acknowledgeMessages

Requires: scope `messages:write`.

```graphql
acknowledgeMessages(platformId: ID, inputs: [AcknowledgeMessageInput!]!): [PlatformMessageView!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `inputs` | `[AcknowledgeMessageInput!]!` |  |

### markMessageRead

Requires: scope `messages:write`.

```graphql
markMessageRead(platformId: ID, id: ID!): PlatformMessageView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### resendPlatformMessage

Requires: scope `messages:write`.

```graphql
resendPlatformMessage(platformId: ID, id: ID!): PlatformMessageView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### setPlatformMessageRouting

Requires: scope `messages:write`.

```graphql
setPlatformMessageRouting(platformId: ID, input: SetMessageRoutingInput!): MessageRoutingRuleView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `SetMessageRoutingInput!` |  |

### clearPlatformMessageRouting

Requires: scope `messages:write`.

```graphql
clearPlatformMessageRouting(platformId: ID, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `id` | `ID!` |  |

### updatePlatformMessageSettings

Requires: scope `messages:write`.

```graphql
updatePlatformMessageSettings(platformId: ID, input: UpdatePlatformMessageSettingsInput!): PlatformMessageSettingsView!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |
| `input` | `UpdatePlatformMessageSettingsInput!` |  |

### setPlatformMessageCopy

Requires: scope `messages:write`.

```graphql
setPlatformMessageCopy(input: SetPlatformMessageCopyInput!): PlatformMessageCopy!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SetPlatformMessageCopyInput!` |  |

### clearPlatformMessageCopy

Requires: scope `messages:write`.

```graphql
clearPlatformMessageCopy(id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |


---

<!-- /reference/graphql/monetary-accounts -->
# Monetary accounts

GraphQL operations: monetary accounts.

## Queries

### aiBankRules

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
aiBankRules(profileId: ID!): [BankRuleView!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### bankRules

The company's own rules in the order they apply, then its platform's (read only).

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
bankRules(profileId: ID!): [BankRule!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### bankRulePreview

Recent payments a rule would book, without booking them (at most 50).

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
bankRulePreview(profileId: ID!, input: BankRuleInput!, limit: Int): [MonetaryAccountPayment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `BankRuleInput!` |  |
| `limit` | `Int` |  |

### bankReconciliation

Per day, the bank's closing balance against the books for one bank account (at most 400 days).

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
bankReconciliation(profileId: ID!, monetaryAccountId: ID!, from: String!, to: String!): [ReconciliationDay!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `monetaryAccountId` | `ID!` |  |
| `from` | `String!` | YYYY-MM-DD |
| `to` | `String!` | YYYY-MM-DD |

### monetaryAccountSpreadsheetImportTemplate

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccountSpreadsheetImportTemplate(format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `format` | `SpreadsheetFormat!` |  |

### monetaryAccountPayment

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccountPayment(id: ID!): MonetaryAccountPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### monetaryAccountPayments

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccountPayments(paging: CursorPaging!, filter: MonetaryAccountPaymentFilter!, sorting: [MonetaryAccountPaymentSort!]!): MonetaryAccountPaymentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `MonetaryAccountPaymentFilter!` | Specify to filter the records returned. |
| `sorting` | `[MonetaryAccountPaymentSort!]!` | Specify to sort results. |

### monetaryAccount

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccount(id: ID!): MonetaryAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### monetaryAccounts

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccounts(paging: CursorPaging!, filter: MonetaryAccountFilter!, sorting: [MonetaryAccountSort!]!): MonetaryAccountConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `MonetaryAccountFilter!` | Specify to filter the records returned. |
| `sorting` | `[MonetaryAccountSort!]!` | Specify to sort results. |

### monetaryAccountAutoProcess

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccountAutoProcess(id: ID!): MonetaryAccountAutoProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### monetaryAccountAutoProcesses

Requires: scope `monetary_accounts:read` · feature `banking`.

```graphql
monetaryAccountAutoProcesses(paging: CursorPaging!, filter: MonetaryAccountAutoProcessFilter!, sorting: [MonetaryAccountAutoProcessSort!]!): MonetaryAccountAutoProcessConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `MonetaryAccountAutoProcessFilter!` | Specify to filter the records returned. |
| `sorting` | `[MonetaryAccountAutoProcessSort!]!` | Specify to sort results. |

## Mutations

### createAiBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createAiBankRule(profileId: ID!, input: CreateBankRuleInput!): BankRuleView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateBankRuleInput!` |  |

### updateAiBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateAiBankRule(profileId: ID!, id: ID!, input: UpdateBankRuleInput!): BankRuleView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `id` | `ID!` |  |
| `input` | `UpdateBankRuleInput!` |  |

### deleteAiBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteAiBankRule(profileId: ID!, id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `id` | `ID!` |  |

### suggestAiBankRules

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
suggestAiBankRules(profileId: ID!): SuggestBankRulesResultView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### deleteMonetaryAccount

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteMonetaryAccount(id: ID!): ID!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### processMonetaryAccountPayment

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
processMonetaryAccountPayment(id: ID!, input: ProcessMonetaryAccountPaymentInput!): MonetaryAccountPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `ProcessMonetaryAccountPaymentInput!` |  |

### unprocessMonetaryAccountPayment

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
unprocessMonetaryAccountPayment(id: ID!): MonetaryAccountPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createBankRule(profileId: ID!, input: BankRuleInput!): BankRule!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `BankRuleInput!` |  |

### updateBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateBankRule(id: ID!, input: BankRuleInput!): BankRule!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `BankRuleInput!` |  |

### deleteBankRule

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteBankRule(id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### applyBankRules

Books the unprocessed payments the rules match (at most 2000 per call). Returns how many were booked.

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
applyBankRules(profileId: ID!, monetaryAccountId: ID, from: DateTime, to: DateTime): Int!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `monetaryAccountId` | `ID` |  |
| `from` | `DateTime` |  |
| `to` | `DateTime` |  |

### importMonetaryAccountSpreadsheet

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
importMonetaryAccountSpreadsheet(monetaryAccountId: ID!, format: SpreadsheetFormat!, file: String!): SpreadsheetImportResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `monetaryAccountId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |
| `file` | `String!` |  |

### importMonetaryAccountPayments

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
importMonetaryAccountPayments(input: ImportMonetaryAccountPaymentsInput!): ImportMonetaryAccountPaymentsResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ImportMonetaryAccountPaymentsInput!` |  |

### createOneMonetaryAccountPayment

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createOneMonetaryAccountPayment(settlementId: ID, monetaryAccountId: ID, input: CreateMonetaryAccountPaymentInput!): MonetaryAccountPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `settlementId` | `ID` |  |
| `monetaryAccountId` | `ID` |  |
| `input` | `CreateMonetaryAccountPaymentInput!` |  |

### createManyMonetaryAccountPayments

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createManyMonetaryAccountPayments(settlementId: ID, monetaryAccountId: ID, input: [CreateMonetaryAccountPaymentInput!]!): [MonetaryAccountPayment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `settlementId` | `ID` |  |
| `monetaryAccountId` | `ID` |  |
| `input` | `[CreateMonetaryAccountPaymentInput!]!` |  |

### createOneMonetaryAccount

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createOneMonetaryAccount(profileId: ID!, input: CreateMonetaryAccountInput!): MonetaryAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateMonetaryAccountInput!` |  |

### createManyMonetaryAccounts

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createManyMonetaryAccounts(profileId: ID!, input: [CreateMonetaryAccountInput!]!): [MonetaryAccount!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateMonetaryAccountInput!]!` |  |

### createOneMonetaryAccountAutoProcess

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createOneMonetaryAccountAutoProcess(monetaryAccountId: ID!, input: CreateMonetaryAccountAutoProcessInput!): MonetaryAccountAutoProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `monetaryAccountId` | `ID!` |  |
| `input` | `CreateMonetaryAccountAutoProcessInput!` |  |

### createManyMonetaryAccountAutoProcesses

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
createManyMonetaryAccountAutoProcesses(monetaryAccountId: ID!, input: [CreateMonetaryAccountAutoProcessInput!]!): [MonetaryAccountAutoProcess!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `monetaryAccountId` | `ID!` |  |
| `input` | `[CreateMonetaryAccountAutoProcessInput!]!` |  |

### updateOneMonetaryAccountPayment

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateOneMonetaryAccountPayment(input: UpdateOneMonetaryAccountPaymentInput!): MonetaryAccountPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneMonetaryAccountPaymentInput!` |  |

### updateManyMonetaryAccountPayments

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateManyMonetaryAccountPayments(input: UpdateManyMonetaryAccountPaymentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyMonetaryAccountPaymentsInput!` |  |

### deleteOneMonetaryAccountPayment

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteOneMonetaryAccountPayment(input: DeleteOneMonetaryAccountPaymentInput!): MonetaryAccountPaymentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneMonetaryAccountPaymentInput!` |  |

### deleteManyMonetaryAccountPayments

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteManyMonetaryAccountPayments(input: DeleteManyMonetaryAccountPaymentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyMonetaryAccountPaymentsInput!` |  |

### updateOneMonetaryAccount

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateOneMonetaryAccount(input: UpdateOneMonetaryAccountInput!): MonetaryAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneMonetaryAccountInput!` |  |

### updateManyMonetaryAccounts

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateManyMonetaryAccounts(input: UpdateManyMonetaryAccountsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyMonetaryAccountsInput!` |  |

### deleteOneMonetaryAccount

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteOneMonetaryAccount(input: DeleteOneMonetaryAccountInput!): MonetaryAccountDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneMonetaryAccountInput!` |  |

### deleteManyMonetaryAccounts

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteManyMonetaryAccounts(input: DeleteManyMonetaryAccountsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyMonetaryAccountsInput!` |  |

### updateOneMonetaryAccountAutoProcess

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateOneMonetaryAccountAutoProcess(input: UpdateOneMonetaryAccountAutoProcessInput!): MonetaryAccountAutoProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneMonetaryAccountAutoProcessInput!` |  |

### updateManyMonetaryAccountAutoProcesses

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
updateManyMonetaryAccountAutoProcesses(input: UpdateManyMonetaryAccountAutoProcessesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyMonetaryAccountAutoProcessesInput!` |  |

### deleteOneMonetaryAccountAutoProcess

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteOneMonetaryAccountAutoProcess(input: DeleteOneMonetaryAccountAutoProcessInput!): MonetaryAccountAutoProcessDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneMonetaryAccountAutoProcessInput!` |  |

### deleteManyMonetaryAccountAutoProcesses

Requires: scope `monetary_accounts:write` · feature `banking`.

```graphql
deleteManyMonetaryAccountAutoProcesses(input: DeleteManyMonetaryAccountAutoProcessesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyMonetaryAccountAutoProcessesInput!` |  |


---

<!-- /reference/graphql/pay-runs -->
# Pay runs

GraphQL operations: pay runs.

## Queries

### payRun

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### payRuns

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRuns(paging: CursorPaging!, filter: PayRunFilter!, sorting: [PayRunSort!]!): PayRunConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PayRunFilter!` | Specify to filter the records returned. |
| `sorting` | `[PayRunSort!]!` | Specify to sort results. |

### payRunEmploymentInput

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunEmploymentInput(id: ID!): PayRunEmploymentInput!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### payRunEmploymentInputs

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunEmploymentInputs(paging: CursorPaging!, filter: PayRunEmploymentInputFilter!, sorting: [PayRunEmploymentInputSort!]!): PayRunEmploymentInputConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PayRunEmploymentInputFilter!` | Specify to filter the records returned. |
| `sorting` | `[PayRunEmploymentInputSort!]!` | Specify to sort results. |

### payRunInclusion

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunInclusion(payRunId: ID!): PayRunInclusionPreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunDriveFolderPath

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunDriveFolderPath(payRunId: ID!): String
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunJournalPdf

Loonjournaalpost PDF for an approved+ pay run (base64). Same memorial as payRunMemorialJournal.

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunJournalPdf(payRunId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunJournalCsv

Loonjournaalpost CSV for an approved+ pay run. Same memorial as payRunMemorialJournal.

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunJournalCsv(payRunId: ID!): PaymentBatchExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunContractsCsv

Overzicht van contracten CSV — employments active in the pay period.

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunContractsCsv(payRunId: ID!): PaymentBatchExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunLoonstaatPdf

Period loonstaat / PeriodeOverzicht PDF for a calculated+ pay run (base64).

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunLoonstaatPdf(payRunId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunEmployerCumulativesPdf

Cumulatieven werkgever / employer cumulatives PDF for a calculated+ pay run (base64).

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunEmployerCumulativesPdf(payRunId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### payRunMemorialJournal

Virtual memorial for an approved+ pay run (preview). Financials includes the booking only after lockPayRun / finalize. Null when not postable or no legs.

Requires: scope `pay_runs:read` · feature `payroll`.

```graphql
payRunMemorialJournal(payRunId: ID!): JournalBooking
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

## Mutations

### createOnePayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
createOnePayRun(profileId: ID!, input: CreatePayRunInput!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePayRunInput!` |  |

### createManyPayRuns

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
createManyPayRuns(profileId: ID!, input: [CreatePayRunInput!]!): [PayRun!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePayRunInput!]!` |  |

### createOnePayRunEmploymentInput

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
createOnePayRunEmploymentInput(profileId: ID!, input: CreatePayRunEmploymentInputInput!): PayRunEmploymentInput!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePayRunEmploymentInputInput!` |  |

### createManyPayRunEmploymentInputs

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
createManyPayRunEmploymentInputs(profileId: ID!, input: [CreatePayRunEmploymentInputInput!]!): [PayRunEmploymentInput!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePayRunEmploymentInputInput!]!` |  |

### updateOnePayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
updateOnePayRun(input: UpdateOnePayRunInput!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePayRunInput!` |  |

### updateManyPayRuns

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
updateManyPayRuns(input: UpdateManyPayRunsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPayRunsInput!` |  |

### updateOnePayRunEmploymentInput

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
updateOnePayRunEmploymentInput(input: UpdateOnePayRunEmploymentInputInput!): PayRunEmploymentInput!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePayRunEmploymentInputInput!` |  |

### updateManyPayRunEmploymentInputs

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
updateManyPayRunEmploymentInputs(input: UpdateManyPayRunEmploymentInputsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPayRunEmploymentInputsInput!` |  |

### deleteOnePayRunEmploymentInput

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
deleteOnePayRunEmploymentInput(input: DeleteOnePayRunEmploymentInputInput!): PayRunEmploymentInputDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePayRunEmploymentInputInput!` |  |

### deleteManyPayRunEmploymentInputs

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
deleteManyPayRunEmploymentInputs(input: DeleteManyPayRunEmploymentInputsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPayRunEmploymentInputsInput!` |  |

### calculatePayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
calculatePayRun(id: ID!): CalculatePayRunPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### approvePayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
approvePayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### markPaidPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
markPaidPayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### markFiledPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
markFiledPayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### lockPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
lockPayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### cancelPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
cancelPayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### deletePayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
deletePayRun(id: ID!): ID!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### correctPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
correctPayRun(id: ID!): PayRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createPayrollUpaFilingFromPayRun

Requires: scope `pay_runs:write` · feature `payroll`.

```graphql
createPayrollUpaFilingFromPayRun(payRunId: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |


---

<!-- /reference/graphql/payment-batches -->
# Payment batches

GraphQL operations: payment batches.

## Queries

### paymentBatchPaymentRequests

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatchPaymentRequests(profileId: ID!, paymentBatchId: ID!): [PaymentRequest!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `paymentBatchId` | `ID!` |  |

### paymentBatchExport

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatchExport(id: ID!, format: PaymentBatchExportFormat): PaymentBatchExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `format` | `PaymentBatchExportFormat` |  |

### paymentBatch

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatch(id: ID!): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### paymentBatches

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatches(paging: CursorPaging!, filter: PaymentBatchFilter!, sorting: [PaymentBatchSort!]!): PaymentBatchConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PaymentBatchFilter!` | Specify to filter the records returned. |
| `sorting` | `[PaymentBatchSort!]!` | Specify to sort results. |

### paymentBatchLine

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatchLine(id: ID!): PaymentBatchLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### paymentBatchLines

Requires: scope `payment_batches:read` · feature `payment_batches`.

```graphql
paymentBatchLines(paging: CursorPaging!, filter: PaymentBatchLineFilter!, sorting: [PaymentBatchLineSort!]!): PaymentBatchLineConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PaymentBatchLineFilter!` | Specify to filter the records returned. |
| `sorting` | `[PaymentBatchLineSort!]!` | Specify to sort results. |

## Mutations

### createPaymentBatchPaymentRequest

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createPaymentBatchPaymentRequest(profileId: ID!, paymentBatchId: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `paymentBatchId` | `ID!` |  |

### createPaymentBatchFromPayRun

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createPaymentBatchFromPayRun(payRunId: ID!, debitMonetaryAccountId: ID): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |
| `debitMonetaryAccountId` | `ID` |  |

### addPayRunToPaymentBatch

Requires: scope `payment_batches:write` · feature `payroll`.

```graphql
addPayRunToPaymentBatch(paymentBatchId: ID!, payRunId: ID!): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `paymentBatchId` | `ID!` |  |
| `payRunId` | `ID!` |  |

### exportPaymentBatch

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
exportPaymentBatch(id: ID!, format: PaymentBatchExportFormat): PaymentBatchExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `format` | `PaymentBatchExportFormat` |  |

### createOnePaymentBatch

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createOnePaymentBatch(profileId: ID!, input: CreatePaymentBatchInput!): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePaymentBatchInput!` |  |

### createManyPaymentBatches

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createManyPaymentBatches(profileId: ID!, input: [CreatePaymentBatchInput!]!): [PaymentBatch!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePaymentBatchInput!]!` |  |

### createOnePaymentBatchLine

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createOnePaymentBatchLine(paymentBatchId: ID!, input: CreatePaymentBatchLineInput!): PaymentBatchLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `paymentBatchId` | `ID!` |  |
| `input` | `CreatePaymentBatchLineInput!` |  |

### createManyPaymentBatchLines

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
createManyPaymentBatchLines(paymentBatchId: ID!, input: [CreatePaymentBatchLineInput!]!): [PaymentBatchLine!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `paymentBatchId` | `ID!` |  |
| `input` | `[CreatePaymentBatchLineInput!]!` |  |

### updateOnePaymentBatch

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
updateOnePaymentBatch(input: UpdateOnePaymentBatchInput!): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePaymentBatchInput!` |  |

### updateManyPaymentBatches

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
updateManyPaymentBatches(input: UpdateManyPaymentBatchesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPaymentBatchesInput!` |  |

### deleteOnePaymentBatch

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
deleteOnePaymentBatch(input: DeleteOnePaymentBatchInput!): PaymentBatchDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePaymentBatchInput!` |  |

### deleteManyPaymentBatches

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
deleteManyPaymentBatches(input: DeleteManyPaymentBatchesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPaymentBatchesInput!` |  |

### updateOnePaymentBatchLine

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
updateOnePaymentBatchLine(input: UpdateOnePaymentBatchLineInput!): PaymentBatchLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePaymentBatchLineInput!` |  |

### updateManyPaymentBatchLines

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
updateManyPaymentBatchLines(input: UpdateManyPaymentBatchLinesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPaymentBatchLinesInput!` |  |

### deleteOnePaymentBatchLine

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
deleteOnePaymentBatchLine(input: DeleteOnePaymentBatchLineInput!): PaymentBatchLineDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePaymentBatchLineInput!` |  |

### deleteManyPaymentBatchLines

Requires: scope `payment_batches:write` · feature `payment_batches`.

```graphql
deleteManyPaymentBatchLines(input: DeleteManyPaymentBatchLinesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPaymentBatchLinesInput!` |  |


---

<!-- /reference/graphql/payroll -->
# Payroll

GraphQL operations: payroll.

## Queries

### payrollEmployerSettings

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollEmployerSettings(paging: CursorPaging!, filter: PayrollEmployerSettingsFilter!, sorting: [PayrollEmployerSettingsSort!]!): PayrollEmployerSettingsConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PayrollEmployerSettingsFilter!` | Specify to filter the records returned. |
| `sorting` | `[PayrollEmployerSettingsSort!]!` | Specify to sort results. |

### nlPayrollEmployerSettings

Requires: scope `payroll:read` · feature `payroll`.

```graphql
nlPayrollEmployerSettings(paging: CursorPaging!, filter: NlPayrollEmployerSettingsFilter!, sorting: [NlPayrollEmployerSettingsSort!]!): NlPayrollEmployerSettingsConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `NlPayrollEmployerSettingsFilter!` | Specify to filter the records returned. |
| `sorting` | `[NlPayrollEmployerSettingsSort!]!` | Specify to sort results. |

### vehiclePayrollAttrs

Requires: scope `payroll:read` · feature `vehicles`.

```graphql
vehiclePayrollAttrs(paging: CursorPaging!, filter: VehiclePayrollAttrsFilter!, sorting: [VehiclePayrollAttrsSort!]!): VehiclePayrollAttrsConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `VehiclePayrollAttrsFilter!` | Specify to filter the records returned. |
| `sorting` | `[VehiclePayrollAttrsSort!]!` | Specify to sort results. |

### payrollDeliveryLog

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollDeliveryLog(profileId: ID!, limit: Int): [PayrollDeliveryLogEntry!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `limit` | `Int` |  |

### myPayslips

The finalised payslips of the employee the session is bound to, newest first.

Requires: scope `payroll:read` · feature `employee_self_service`.

```graphql
myPayslips(profileId: ID!): [MyPayslip!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### myPayslipPdf

The PDF (base64) of one of the employee's own finalised payslips.

Requires: scope `payroll:read` · feature `employee_self_service`.

```graphql
myPayslipPdf(id: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### myYearDocuments

The annual statements (jaaropgaaf) of the employee the session is bound to.

Requires: scope `payroll:read` · feature `employee_self_service`.

```graphql
myYearDocuments(profileId: ID!): [MyYearDocument!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### myYearDocumentPdf

The PDF (base64) of one of the employee's own annual statements.

Requires: scope `payroll:read` · feature `employee_self_service`.

```graphql
myYearDocumentPdf(id: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### payrollYtdImport

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollYtdImport(id: ID!): PayrollYtdImport!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### payrollYtdImports

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollYtdImports(paging: CursorPaging!, filter: PayrollYtdImportFilter!, sorting: [PayrollYtdImportSort!]!): PayrollYtdImportConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PayrollYtdImportFilter!` | Specify to filter the records returned. |
| `sorting` | `[PayrollYtdImportSort!]!` | Specify to sort results. |

### payrollRuleKb

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollRuleKb(ruleRef: String!, asOf: String): PayrollRuleKbEntry
```

| Argument | Type |  |
| --- | --- | --- |
| `ruleRef` | `String!` |  |
| `asOf` | `String` |  |

### payrollRuleKbEntries

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollRuleKbEntries(asOf: String): [PayrollRuleKbEntry!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `asOf` | `String` |  |

### payrollPeriodAuditExport

Requires: scope `payroll:read` · feature `payroll`.

```graphql
payrollPeriodAuditExport(payPeriodId: ID!): PayrollPeriodAuditExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `payPeriodId` | `ID!` |  |

## Mutations

### setProfilePayrollAddon

Requires: scope `payroll:write` · feature `payroll`.

```graphql
setProfilePayrollAddon(profileId: ID!, enabled: Boolean!): ProfileSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `enabled` | `Boolean!` |  |

### setBookkeeperPayrollModule

Turn the firm payroll module (€75 / month) on or off. Needed before any client can be set to bookkeeping + payroll or payroll only.

Requires: scope `payroll:write` · feature `payroll`.

```graphql
setBookkeeperPayrollModule(bookkeeperId: ID!, enabled: Boolean!): BookkeeperSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `enabled` | `Boolean!` |  |

### createOnePayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createOnePayrollEmployerSettings(profileId: ID!, input: CreatePayrollEmployerSettingsInput!): PayrollEmployerSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePayrollEmployerSettingsInput!` |  |

### createManyPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createManyPayrollEmployerSettings(profileId: ID!, input: [CreatePayrollEmployerSettingsInput!]!): [PayrollEmployerSettings!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePayrollEmployerSettingsInput!]!` |  |

### createOneNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createOneNlPayrollEmployerSettings(profileId: ID!, input: CreateNlPayrollEmployerSettingsInput!): NlPayrollEmployerSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateNlPayrollEmployerSettingsInput!` |  |

### createManyNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createManyNlPayrollEmployerSettings(profileId: ID!, input: [CreateNlPayrollEmployerSettingsInput!]!): [NlPayrollEmployerSettings!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateNlPayrollEmployerSettingsInput!]!` |  |

### createOneVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
createOneVehiclePayrollAttrs(profileId: ID!, input: CreateVehiclePayrollAttrsInput!): VehiclePayrollAttrs!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateVehiclePayrollAttrsInput!` |  |

### createManyVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
createManyVehiclePayrollAttrs(profileId: ID!, input: [CreateVehiclePayrollAttrsInput!]!): [VehiclePayrollAttrs!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateVehiclePayrollAttrsInput!]!` |  |

### updateOnePayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
updateOnePayrollEmployerSettings(input: UpdateOnePayrollEmployerSettingsInput!): PayrollEmployerSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePayrollEmployerSettingsInput!` |  |

### updateManyPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
updateManyPayrollEmployerSettings(input: UpdateManyPayrollEmployerSettingsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPayrollEmployerSettingsInput!` |  |

### deleteOnePayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
deleteOnePayrollEmployerSettings(input: DeleteOnePayrollEmployerSettingsInput!): PayrollEmployerSettingsDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePayrollEmployerSettingsInput!` |  |

### deleteManyPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
deleteManyPayrollEmployerSettings(input: DeleteManyPayrollEmployerSettingsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPayrollEmployerSettingsInput!` |  |

### updateOneNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
updateOneNlPayrollEmployerSettings(input: UpdateOneNlPayrollEmployerSettingsInput!): NlPayrollEmployerSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneNlPayrollEmployerSettingsInput!` |  |

### updateManyNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
updateManyNlPayrollEmployerSettings(input: UpdateManyNlPayrollEmployerSettingsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyNlPayrollEmployerSettingsInput!` |  |

### deleteOneNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
deleteOneNlPayrollEmployerSettings(input: DeleteOneNlPayrollEmployerSettingsInput!): NlPayrollEmployerSettingsDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneNlPayrollEmployerSettingsInput!` |  |

### deleteManyNlPayrollEmployerSettings

Requires: scope `payroll:write` · feature `payroll`.

```graphql
deleteManyNlPayrollEmployerSettings(input: DeleteManyNlPayrollEmployerSettingsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyNlPayrollEmployerSettingsInput!` |  |

### updateOneVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
updateOneVehiclePayrollAttrs(input: UpdateOneVehiclePayrollAttrsInput!): VehiclePayrollAttrs!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneVehiclePayrollAttrsInput!` |  |

### updateManyVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
updateManyVehiclePayrollAttrs(input: UpdateManyVehiclePayrollAttrsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyVehiclePayrollAttrsInput!` |  |

### deleteOneVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
deleteOneVehiclePayrollAttrs(input: DeleteOneVehiclePayrollAttrsInput!): VehiclePayrollAttrsDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneVehiclePayrollAttrsInput!` |  |

### deleteManyVehiclePayrollAttrs

Requires: scope `payroll:write` · feature `vehicles`.

```graphql
deleteManyVehiclePayrollAttrs(input: DeleteManyVehiclePayrollAttrsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyVehiclePayrollAttrsInput!` |  |

### createOnePayrollYtdImport

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createOnePayrollYtdImport(profileId: ID!, input: CreatePayrollYtdImportInput!): PayrollYtdImport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePayrollYtdImportInput!` |  |

### createManyPayrollYtdImports

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createManyPayrollYtdImports(profileId: ID!, input: [CreatePayrollYtdImportInput!]!): [PayrollYtdImport!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePayrollYtdImportInput!]!` |  |

### submitPayrollUpaFiling

Requires: scope `payroll:write` · feature `payroll`.

```graphql
submitPayrollUpaFiling(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createPayrollUpaFilingCorrection

Requires: scope `payroll:write` · feature `payroll`.

```graphql
createPayrollUpaFilingCorrection(correctsFilingId: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `correctsFilingId` | `ID!` |  |


---

<!-- /reference/graphql/payroll-filings -->
# Payroll filings

GraphQL operations: payroll filings.

## Queries

### payrollFilingOverview

Requires: scope `payroll_filings:read` · feature `payroll`.

```graphql
payrollFilingOverview(profileId: ID!, year: Int!): PayrollFilingOverview!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `year` | `Int!` |  |

## Mutations

### createPayrollFilingFromPayRun

Requires: scope `payroll_filings:write` · feature `payroll`.

```graphql
createPayrollFilingFromPayRun(payRunId: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `payRunId` | `ID!` |  |

### submitPayrollFiling

Requires: scope `payroll_filings:write` · feature `payroll`.

```graphql
submitPayrollFiling(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createPayrollFilingCorrection

Requires: scope `payroll_filings:write` · feature `payroll`.

```graphql
createPayrollFilingCorrection(correctsFilingId: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `correctsFilingId` | `ID!` |  |


---

<!-- /reference/graphql/process-documents -->
# Process documents

GraphQL operations: process documents.

## Queries

### processDocumentInboxEmail

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentInboxEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentSalesEmail

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentSalesEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentRequestsEmail

Address for purchase requests by email: requests+{company}@… (a message or forwarded quote becomes a draft purchase request).

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentRequestsEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentPackingEmail

Address for packing slips / delivery notes: {company}+packing@…

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentPackingEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentCatchAllEmail

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentCatchAllEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentLettersEmail

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentLettersEmail(profileId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### processDocumentInbox

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentInbox(profileId: ID!, status: ProcessDocumentInboxStatus!, search: String, category: ProcessDocumentCategory, allCategories: Boolean, relationId: ID, after: String): ProcessDocumentInboxPage!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `status` | `ProcessDocumentInboxStatus!` |  |
| `search` | `String` |  |
| `category` | `ProcessDocumentCategory` |  |
| `allCategories` | `Boolean` |  |
| `relationId` | `ID` |  |
| `after` | `String` |  |

### processDocument

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocument(id: ID!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### processDocuments

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocuments(paging: CursorPaging!, filter: ProcessDocumentFilter!, sorting: [ProcessDocumentSort!]!): ProcessDocumentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ProcessDocumentFilter!` | Specify to filter the records returned. |
| `sorting` | `[ProcessDocumentSort!]!` | Specify to sort results. |

### processDocumentsPlatformEmailDomain

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentsPlatformEmailDomain: String!
```

### processDocumentInboxMessagingAddress

Requires: scope `process_documents:read` · feature `process_documents`.

```graphql
processDocumentInboxMessagingAddress(profileId: ID!): String
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

## Mutations

### uploadProcessDocuments

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
uploadProcessDocuments(profileId: ID!, files: [ProcessDocumentUploadInput!]!, comment: String): [ProcessDocument!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `files` | `[ProcessDocumentUploadInput!]!` |  |
| `comment` | `String` |  |

### uploadProcessDocumentForPayment

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
uploadProcessDocumentForPayment(monetaryAccountPaymentId: ID!, file: ProcessDocumentUploadInput!, contextText: String): UploadProcessDocumentForPaymentResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `monetaryAccountPaymentId` | `ID!` |  |
| `file` | `ProcessDocumentUploadInput!` |  |
| `contextText` | `String` |  |

### rejectProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
rejectProcessDocument(id: ID!, reason: String): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `reason` | `String` |  |

### removeProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
removeProcessDocument(id: ID!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### restoreProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
restoreProcessDocument(id: ID!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### retryProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
retryProcessDocument(id: ID!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createOneProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
createOneProcessDocument(profileId: ID!, input: CreateProcessDocumentInput!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateProcessDocumentInput!` |  |

### createManyProcessDocuments

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
createManyProcessDocuments(profileId: ID!, input: [CreateProcessDocumentInput!]!): [ProcessDocument!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateProcessDocumentInput!]!` |  |

### updateOneProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
updateOneProcessDocument(input: UpdateOneProcessDocumentInput!): ProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneProcessDocumentInput!` |  |

### updateManyProcessDocuments

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
updateManyProcessDocuments(input: UpdateManyProcessDocumentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyProcessDocumentsInput!` |  |

### deleteOneProcessDocument

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
deleteOneProcessDocument(input: DeleteOneProcessDocumentInput!): ProcessDocumentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProcessDocumentInput!` |  |

### deleteManyProcessDocuments

Requires: scope `process_documents:write` · feature `process_documents`.

```graphql
deleteManyProcessDocuments(input: DeleteManyProcessDocumentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyProcessDocumentsInput!` |  |


---

<!-- /reference/graphql/products -->
# Products

GraphQL operations: products.

## Queries

### productStock

Requires: scope `products:read` · feature `products`.

```graphql
productStock(productId: ID!, warehouseId: ID): ProductStockBalance
```

| Argument | Type |  |
| --- | --- | --- |
| `productId` | `ID!` |  |
| `warehouseId` | `ID` |  |

### lowStockProducts

Requires: scope `products:read` · feature `inventory`.

```graphql
lowStockProducts(profileId: ID!): [Product!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### product

Requires: scope `products:read` · feature `products`.

```graphql
product(id: ID!): Product!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### products

Requires: scope `products:read` · feature `products`.

```graphql
products(paging: CursorPaging!, filter: ProductFilter!, sorting: [ProductSort!]!): ProductConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ProductFilter!` | Specify to filter the records returned. |
| `sorting` | `[ProductSort!]!` | Specify to sort results. |

### productCategory

Requires: scope `products:read` · feature `products`.

```graphql
productCategory(id: ID!): ProductCategory!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### productCategories

Requires: scope `products:read` · feature `products`.

```graphql
productCategories(paging: CursorPaging!, filter: ProductCategoryFilter!, sorting: [ProductCategorySort!]!): ProductCategoryConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ProductCategoryFilter!` | Specify to filter the records returned. |
| `sorting` | `[ProductCategorySort!]!` | Specify to sort results. |

## Mutations

### createOneProduct

Requires: scope `products:write` · feature `products`.

```graphql
createOneProduct(profileId: ID!, input: CreateProductInput!): Product!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateProductInput!` |  |

### createManyProducts

Requires: scope `products:write` · feature `products`.

```graphql
createManyProducts(profileId: ID!, input: [CreateProductInput!]!): [Product!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateProductInput!]!` |  |

### createOneProductCategory

Requires: scope `products:write` · feature `products`.

```graphql
createOneProductCategory(profileId: ID!, input: CreateProductCategoryInput!): ProductCategory!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateProductCategoryInput!` |  |

### createManyProductCategories

Requires: scope `products:write` · feature `products`.

```graphql
createManyProductCategories(profileId: ID!, input: [CreateProductCategoryInput!]!): [ProductCategory!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateProductCategoryInput!]!` |  |

### updateOneProduct

Requires: scope `products:write` · feature `products`.

```graphql
updateOneProduct(input: UpdateOneProductInput!): Product!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneProductInput!` |  |

### updateManyProducts

Requires: scope `products:write` · feature `products`.

```graphql
updateManyProducts(input: UpdateManyProductsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyProductsInput!` |  |

### deleteOneProduct

Requires: scope `products:write` · feature `products`.

```graphql
deleteOneProduct(input: DeleteOneProductInput!): ProductDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProductInput!` |  |

### deleteManyProducts

Requires: scope `products:write` · feature `products`.

```graphql
deleteManyProducts(input: DeleteManyProductsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyProductsInput!` |  |

### updateOneProductCategory

Requires: scope `products:write` · feature `products`.

```graphql
updateOneProductCategory(input: UpdateOneProductCategoryInput!): ProductCategory!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneProductCategoryInput!` |  |

### updateManyProductCategories

Requires: scope `products:write` · feature `products`.

```graphql
updateManyProductCategories(input: UpdateManyProductCategoriesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyProductCategoriesInput!` |  |

### deleteOneProductCategory

Requires: scope `products:write` · feature `products`.

```graphql
deleteOneProductCategory(input: DeleteOneProductCategoryInput!): ProductCategoryDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProductCategoryInput!` |  |

### deleteManyProductCategories

Requires: scope `products:write` · feature `products`.

```graphql
deleteManyProductCategories(input: DeleteManyProductCategoriesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyProductCategoriesInput!` |  |


---

<!-- /reference/graphql/projects -->
# Projects

GraphQL operations: projects.

## Queries

### projectAttachment

Requires: scope `projects:read` · feature `projects`.

```graphql
projectAttachment(id: ID!): ProjectAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### projectFinancials

Requires: scope `projects:read` · feature `projects`.

```graphql
projectFinancials(projectId: ID!, start: DateTime, end: DateTime): ProjectFinancials!
```

| Argument | Type |  |
| --- | --- | --- |
| `projectId` | `ID!` |  |
| `start` | `DateTime` |  |
| `end` | `DateTime` |  |

### projectTime

Requires: scope `projects:read` · feature `projects`.

```graphql
projectTime(id: ID!): ProjectTime!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### projectTimes

Requires: scope `projects:read` · feature `projects`.

```graphql
projectTimes(paging: CursorPaging!, filter: ProjectTimeFilter!, sorting: [ProjectTimeSort!]!): ProjectTimeConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ProjectTimeFilter!` | Specify to filter the records returned. |
| `sorting` | `[ProjectTimeSort!]!` | Specify to sort results. |

### project

Requires: scope `projects:read` · feature `projects`.

```graphql
project(id: ID!): Project!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### projects

Requires: scope `projects:read` · feature `projects`.

```graphql
projects(paging: CursorPaging!, filter: ProjectFilter!, sorting: [ProjectSort!]!): ProjectConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ProjectFilter!` | Specify to filter the records returned. |
| `sorting` | `[ProjectSort!]!` | Specify to sort results. |

## Mutations

### createOneProjectAttachment

Requires: scope `projects:write` · feature `projects`.

```graphql
createOneProjectAttachment(projectId: ID!, input: CreateProjectAttachmentInput!): ProjectAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `projectId` | `ID!` |  |
| `input` | `CreateProjectAttachmentInput!` |  |

### deleteOneProjectAttachment

Requires: scope `projects:write` · feature `projects`.

```graphql
deleteOneProjectAttachment(input: DeleteOneProjectAttachmentInput!): ProjectAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProjectAttachmentInput!` |  |

### createOneProjectTime

Requires: scope `projects:write` · feature `projects`.

```graphql
createOneProjectTime(projectId: ID!, input: CreateProjectTimeInput!): ProjectTime!
```

| Argument | Type |  |
| --- | --- | --- |
| `projectId` | `ID!` |  |
| `input` | `CreateProjectTimeInput!` |  |

### createManyProjectTimes

Requires: scope `projects:write` · feature `projects`.

```graphql
createManyProjectTimes(projectId: ID!, input: [CreateProjectTimeInput!]!): [ProjectTime!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `projectId` | `ID!` |  |
| `input` | `[CreateProjectTimeInput!]!` |  |

### createOneProject

Requires: scope `projects:write` · feature `projects`.

```graphql
createOneProject(profileId: ID!, input: CreateProjectInput!): Project!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateProjectInput!` |  |

### createManyProjects

Requires: scope `projects:write` · feature `projects`.

```graphql
createManyProjects(profileId: ID!, input: [CreateProjectInput!]!): [Project!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateProjectInput!]!` |  |

### updateOneProjectTime

Requires: scope `projects:write` · feature `projects`.

```graphql
updateOneProjectTime(input: UpdateOneProjectTimeInput!): ProjectTime!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneProjectTimeInput!` |  |

### updateManyProjectTimes

Requires: scope `projects:write` · feature `projects`.

```graphql
updateManyProjectTimes(input: UpdateManyProjectTimesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyProjectTimesInput!` |  |

### deleteOneProjectTime

Requires: scope `projects:write` · feature `projects`.

```graphql
deleteOneProjectTime(input: DeleteOneProjectTimeInput!): ProjectTimeDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProjectTimeInput!` |  |

### deleteManyProjectTimes

Requires: scope `projects:write` · feature `projects`.

```graphql
deleteManyProjectTimes(input: DeleteManyProjectTimesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyProjectTimesInput!` |  |

### updateOneProject

Requires: scope `projects:write` · feature `projects`.

```graphql
updateOneProject(input: UpdateOneProjectInput!): Project!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneProjectInput!` |  |

### updateManyProjects

Requires: scope `projects:write` · feature `projects`.

```graphql
updateManyProjects(input: UpdateManyProjectsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyProjectsInput!` |  |

### deleteOneProject

Requires: scope `projects:write` · feature `projects`.

```graphql
deleteOneProject(input: DeleteOneProjectInput!): ProjectDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneProjectInput!` |  |

### deleteManyProjects

Requires: scope `projects:write` · feature `projects`.

```graphql
deleteManyProjects(input: DeleteManyProjectsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyProjectsInput!` |  |


---

<!-- /reference/graphql/psp-payments -->
# Psp payments

GraphQL operations: psp payments.

## Queries

### pSPPayment

Requires: scope `psp_payments:read` · feature `online_payments`.

```graphql
pSPPayment(id: ID!): PSPPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### pSPPayments

Requires: scope `psp_payments:read` · feature `online_payments`.

```graphql
pSPPayments(paging: CursorPaging!, filter: PSPPaymentFilter!, sorting: [PSPPaymentSort!]!): PSPPaymentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PSPPaymentFilter!` | Specify to filter the records returned. |
| `sorting` | `[PSPPaymentSort!]!` | Specify to sort results. |

## Mutations

### refundPSPPayment

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
refundPSPPayment(id: String!): PSPPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `String!` |  |

### createOnePSPPayment

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
createOnePSPPayment(profileId: ID!, input: CreatePSPPaymentInput!): PSPPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePSPPaymentInput!` |  |

### createManyPSPPayments

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
createManyPSPPayments(profileId: ID!, input: [CreatePSPPaymentInput!]!): [PSPPayment!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePSPPaymentInput!]!` |  |

### updateOnePSPPayment

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
updateOnePSPPayment(input: UpdateOnePSPPaymentInput!): PSPPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePSPPaymentInput!` |  |

### updateManyPSPPayments

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
updateManyPSPPayments(input: UpdateManyPSPPaymentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPSPPaymentsInput!` |  |

### deleteOnePSPPayment

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
deleteOnePSPPayment(input: DeleteOnePSPPaymentInput!): PSPPaymentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePSPPaymentInput!` |  |

### deleteManyPSPPayments

Requires: scope `psp_payments:write` · feature `online_payments`.

```graphql
deleteManyPSPPayments(input: DeleteManyPSPPaymentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPSPPaymentsInput!` |  |


---

<!-- /reference/graphql/purchase-invoices -->
# Purchase invoices

GraphQL operations: purchase invoices.

## Queries

### purchaseInvoiceAttachment

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceAttachment(id: ID!): PurchaseInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### purchaseInvoiceEvent

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceEvent(id: ID!): PurchaseInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceEvents

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceEvents(paging: CursorPaging!, filter: PurchaseInvoiceEventFilter!, sorting: [PurchaseInvoiceEventSort!]!): PurchaseInvoiceEventConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceEventFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceEventSort!]!` | Specify to sort results. |

### purchaseInvoiceNote

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceNote(id: ID!): PurchaseInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceNotes

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceNotes(paging: CursorPaging!, filter: PurchaseInvoiceNoteFilter!, sorting: [PurchaseInvoiceNoteSort!]!): PurchaseInvoiceNoteConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceNoteFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceNoteSort!]!` | Specify to sort results. |

### purchaseInvoiceLine

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceLine(id: ID!): PurchaseInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceLines

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoiceLines(paging: CursorPaging!, filter: PurchaseInvoiceLineFilter!, sorting: [PurchaseInvoiceLineSort!]!): PurchaseInvoiceLineConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceLineFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceLineSort!]!` | Specify to sort results. |

### purchaseInvoice

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoice(id: ID!): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoices

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoices(paging: CursorPaging!, filter: PurchaseInvoiceFilter!, sorting: [PurchaseInvoiceSort!]!): PurchaseInvoiceConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalScheme

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalScheme(id: ID!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalSchemes

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemes(paging: CursorPaging!, filter: PurchaseInvoiceApprovalSchemeFilter!, sorting: [PurchaseInvoiceApprovalSchemeSort!]!): PurchaseInvoiceApprovalSchemeConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalSchemeFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalSchemeSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalSchemeStep

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeStep(id: ID!): PurchaseInvoiceApprovalSchemeStep!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalSchemeSteps

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeSteps(paging: CursorPaging!, filter: PurchaseInvoiceApprovalSchemeStepFilter!, sorting: [PurchaseInvoiceApprovalSchemeStepSort!]!): PurchaseInvoiceApprovalSchemeStepConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalSchemeStepFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalSchemeStepSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalSchemeStepRole

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeStepRole(id: ID!): PurchaseInvoiceApprovalSchemeStepRole!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalSchemeStepRoles

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeStepRoles(paging: CursorPaging!, filter: PurchaseInvoiceApprovalSchemeStepRoleFilter!, sorting: [PurchaseInvoiceApprovalSchemeStepRoleSort!]!): PurchaseInvoiceApprovalSchemeStepRoleConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalSchemeStepRoleFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalSchemeStepRoleSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalSchemeStepAccount

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeStepAccount(id: ID!): PurchaseInvoiceApprovalSchemeStepAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalSchemeStepAccounts

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeStepAccounts(paging: CursorPaging!, filter: PurchaseInvoiceApprovalSchemeStepAccountFilter!, sorting: [PurchaseInvoiceApprovalSchemeStepAccountSort!]!): PurchaseInvoiceApprovalSchemeStepAccountConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalSchemeStepAccountFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalSchemeStepAccountSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalSchemeRelationRule

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeRelationRule(id: ID!): PurchaseInvoiceApprovalSchemeRelationRule!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalSchemeRelationRules

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalSchemeRelationRules(paging: CursorPaging!, filter: PurchaseInvoiceApprovalSchemeRelationRuleFilter!, sorting: [PurchaseInvoiceApprovalSchemeRelationRuleSort!]!): PurchaseInvoiceApprovalSchemeRelationRuleConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalSchemeRelationRuleFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalSchemeRelationRuleSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalRun

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRun(id: ID!): PurchaseInvoiceApprovalRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalRuns

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRuns(paging: CursorPaging!, filter: PurchaseInvoiceApprovalRunFilter!, sorting: [PurchaseInvoiceApprovalRunSort!]!): PurchaseInvoiceApprovalRunConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalRunFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalRunSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalRunStep

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRunStep(id: ID!): PurchaseInvoiceApprovalRunStep!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalRunSteps

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRunSteps(paging: CursorPaging!, filter: PurchaseInvoiceApprovalRunStepFilter!, sorting: [PurchaseInvoiceApprovalRunStepSort!]!): PurchaseInvoiceApprovalRunStepConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalRunStepFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalRunStepSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalRunAssignee

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRunAssignee(id: ID!): PurchaseInvoiceApprovalRunAssignee!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalRunAssignees

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalRunAssignees(paging: CursorPaging!, filter: PurchaseInvoiceApprovalRunAssigneeFilter!, sorting: [PurchaseInvoiceApprovalRunAssigneeSort!]!): PurchaseInvoiceApprovalRunAssigneeConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalRunAssigneeFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalRunAssigneeSort!]!` | Specify to sort results. |

### purchaseInvoiceApprovalDecision

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalDecision(id: ID!): PurchaseInvoiceApprovalDecision!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### purchaseInvoiceApprovalDecisions

Requires: scope `purchase_invoices:read` · feature `purchase_invoice_approvals`.

```graphql
purchaseInvoiceApprovalDecisions(paging: CursorPaging!, filter: PurchaseInvoiceApprovalDecisionFilter!, sorting: [PurchaseInvoiceApprovalDecisionSort!]!): PurchaseInvoiceApprovalDecisionConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `PurchaseInvoiceApprovalDecisionFilter!` | Specify to filter the records returned. |
| `sorting` | `[PurchaseInvoiceApprovalDecisionSort!]!` | Specify to sort results. |

### purchaseInvoicesSpreadsheetImportTemplate

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
purchaseInvoicesSpreadsheetImportTemplate(format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `format` | `SpreadsheetFormat!` |  |

### exportPurchaseInvoicesSpreadsheet

Requires: scope `purchase_invoices:read` · feature `purchase_invoices`.

```graphql
exportPurchaseInvoicesSpreadsheet(profileId: ID!, format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |

## Mutations

### createOnePurchaseInvoiceAttachment

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createOnePurchaseInvoiceAttachment(purchaseInvoiceId: ID!, input: CreatePurchaseInvoiceAttachmentInput!): PurchaseInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceAttachmentInput!` |  |

### deleteOnePurchaseInvoiceAttachment

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteOnePurchaseInvoiceAttachment(input: DeleteOnePurchaseInvoiceAttachmentInput!): PurchaseInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceAttachmentInput!` |  |

### confirmPurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
confirmPurchaseInvoice(id: ID!, date: DateTime): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `date` | `DateTime` |  |

### approvePurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
approvePurchaseInvoice(id: ID!, comment: String): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `comment` | `String` |  |

### rejectPurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
rejectPurchaseInvoice(id: ID!, comment: String): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `comment` | `String` |  |

### reopenPurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
reopenPurchaseInvoice(id: ID!): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### upsertPurchaseInvoiceApprovalScheme

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
upsertPurchaseInvoiceApprovalScheme(input: UpsertPurchaseInvoiceApprovalSchemeInput!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpsertPurchaseInvoiceApprovalSchemeInput!` |  |

### replacePurchaseInvoiceApprovalSchemeSteps

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
replacePurchaseInvoiceApprovalSchemeSteps(input: ReplacePurchaseInvoiceApprovalSchemeStepsInput!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ReplacePurchaseInvoiceApprovalSchemeStepsInput!` |  |

### replacePurchaseInvoiceApprovalSchemeRelationRules

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
replacePurchaseInvoiceApprovalSchemeRelationRules(input: ReplacePurchaseInvoiceApprovalSchemeRelationRulesInput!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ReplacePurchaseInvoiceApprovalSchemeRelationRulesInput!` |  |

### processPurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
processPurchaseInvoice(id: ID!): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### assignCostCenterToPurchaseInvoices

Requires: scope `purchase_invoices:write` · feature `cost_centers`.

```graphql
assignCostCenterToPurchaseInvoices(input: AssignCostCenterToPurchaseInvoicesInput!): AssignCostCenterToPurchaseInvoicesResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `AssignCostCenterToPurchaseInvoicesInput!` |  |

### assignProjectToPurchaseInvoices

Requires: scope `purchase_invoices:write` · feature `projects`.

```graphql
assignProjectToPurchaseInvoices(input: AssignProjectToPurchaseInvoicesInput!): AssignProjectToPurchaseInvoicesResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `AssignProjectToPurchaseInvoicesInput!` |  |

### createOnePurchaseInvoiceEvent

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createOnePurchaseInvoiceEvent(purchaseInvoiceId: ID!, input: CreatePurchaseInvoiceEventInput!): PurchaseInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceEventInput!` |  |

### createManyPurchaseInvoiceEvents

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createManyPurchaseInvoiceEvents(purchaseInvoiceId: ID!, input: [CreatePurchaseInvoiceEventInput!]!): [PurchaseInvoiceEvent!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceEventInput!]!` |  |

### createOnePurchaseInvoiceNote

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createOnePurchaseInvoiceNote(purchaseInvoiceId: ID!, input: CreatePurchaseInvoiceNoteInput!): PurchaseInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceNoteInput!` |  |

### createManyPurchaseInvoiceNotes

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createManyPurchaseInvoiceNotes(purchaseInvoiceId: ID!, input: [CreatePurchaseInvoiceNoteInput!]!): [PurchaseInvoiceNote!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceNoteInput!]!` |  |

### createOnePurchaseInvoiceLine

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createOnePurchaseInvoiceLine(purchaseInvoiceId: ID!, input: CreatePurchaseInvoiceLineInput!): PurchaseInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceLineInput!` |  |

### createManyPurchaseInvoiceLines

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createManyPurchaseInvoiceLines(purchaseInvoiceId: ID!, input: [CreatePurchaseInvoiceLineInput!]!): [PurchaseInvoiceLine!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceLineInput!]!` |  |

### createOnePurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createOnePurchaseInvoice(profileId: ID!, input: CreatePurchaseInvoiceInput!): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceInput!` |  |

### createManyPurchaseInvoices

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
createManyPurchaseInvoices(profileId: ID!, input: [CreatePurchaseInvoiceInput!]!): [PurchaseInvoice!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceInput!]!` |  |

### createOnePurchaseInvoiceApprovalScheme

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalScheme(profileId: ID!, input: CreatePurchaseInvoiceApprovalSchemeInput!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalSchemeInput!` |  |

### createManyPurchaseInvoiceApprovalSchemes

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalSchemes(profileId: ID!, input: [CreatePurchaseInvoiceApprovalSchemeInput!]!): [PurchaseInvoiceApprovalScheme!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalSchemeInput!]!` |  |

### createOnePurchaseInvoiceApprovalSchemeStep

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalSchemeStep(schemeId: ID!, input: CreatePurchaseInvoiceApprovalSchemeStepInput!): PurchaseInvoiceApprovalSchemeStep!
```

| Argument | Type |  |
| --- | --- | --- |
| `schemeId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalSchemeStepInput!` |  |

### createManyPurchaseInvoiceApprovalSchemeSteps

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalSchemeSteps(schemeId: ID!, input: [CreatePurchaseInvoiceApprovalSchemeStepInput!]!): [PurchaseInvoiceApprovalSchemeStep!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `schemeId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalSchemeStepInput!]!` |  |

### createOnePurchaseInvoiceApprovalSchemeStepRole

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalSchemeStepRole(stepId: ID!, input: CreatePurchaseInvoiceApprovalSchemeStepRoleInput!): PurchaseInvoiceApprovalSchemeStepRole!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalSchemeStepRoleInput!` |  |

### createManyPurchaseInvoiceApprovalSchemeStepRoles

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalSchemeStepRoles(stepId: ID!, input: [CreatePurchaseInvoiceApprovalSchemeStepRoleInput!]!): [PurchaseInvoiceApprovalSchemeStepRole!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalSchemeStepRoleInput!]!` |  |

### createOnePurchaseInvoiceApprovalSchemeStepAccount

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalSchemeStepAccount(stepId: ID!, input: CreatePurchaseInvoiceApprovalSchemeStepAccountInput!): PurchaseInvoiceApprovalSchemeStepAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalSchemeStepAccountInput!` |  |

### createManyPurchaseInvoiceApprovalSchemeStepAccounts

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalSchemeStepAccounts(stepId: ID!, input: [CreatePurchaseInvoiceApprovalSchemeStepAccountInput!]!): [PurchaseInvoiceApprovalSchemeStepAccount!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalSchemeStepAccountInput!]!` |  |

### createOnePurchaseInvoiceApprovalSchemeRelationRule

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalSchemeRelationRule(schemeId: ID!, input: CreatePurchaseInvoiceApprovalSchemeRelationRuleInput!): PurchaseInvoiceApprovalSchemeRelationRule!
```

| Argument | Type |  |
| --- | --- | --- |
| `schemeId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalSchemeRelationRuleInput!` |  |

### createManyPurchaseInvoiceApprovalSchemeRelationRules

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalSchemeRelationRules(schemeId: ID!, input: [CreatePurchaseInvoiceApprovalSchemeRelationRuleInput!]!): [PurchaseInvoiceApprovalSchemeRelationRule!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `schemeId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalSchemeRelationRuleInput!]!` |  |

### createOnePurchaseInvoiceApprovalRun

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalRun(purchaseInvoiceId: ID!, input: CreatePurchaseInvoiceApprovalRunInput!): PurchaseInvoiceApprovalRun!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalRunInput!` |  |

### createManyPurchaseInvoiceApprovalRuns

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalRuns(purchaseInvoiceId: ID!, input: [CreatePurchaseInvoiceApprovalRunInput!]!): [PurchaseInvoiceApprovalRun!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `purchaseInvoiceId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalRunInput!]!` |  |

### createOnePurchaseInvoiceApprovalRunStep

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalRunStep(runId: ID!, input: CreatePurchaseInvoiceApprovalRunStepInput!): PurchaseInvoiceApprovalRunStep!
```

| Argument | Type |  |
| --- | --- | --- |
| `runId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalRunStepInput!` |  |

### createManyPurchaseInvoiceApprovalRunSteps

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalRunSteps(runId: ID!, input: [CreatePurchaseInvoiceApprovalRunStepInput!]!): [PurchaseInvoiceApprovalRunStep!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `runId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalRunStepInput!]!` |  |

### createOnePurchaseInvoiceApprovalRunAssignee

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalRunAssignee(stepId: ID!, input: CreatePurchaseInvoiceApprovalRunAssigneeInput!): PurchaseInvoiceApprovalRunAssignee!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalRunAssigneeInput!` |  |

### createManyPurchaseInvoiceApprovalRunAssignees

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalRunAssignees(stepId: ID!, input: [CreatePurchaseInvoiceApprovalRunAssigneeInput!]!): [PurchaseInvoiceApprovalRunAssignee!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `stepId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalRunAssigneeInput!]!` |  |

### createOnePurchaseInvoiceApprovalDecision

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createOnePurchaseInvoiceApprovalDecision(runId: ID!, input: CreatePurchaseInvoiceApprovalDecisionInput!): PurchaseInvoiceApprovalDecision!
```

| Argument | Type |  |
| --- | --- | --- |
| `runId` | `ID!` |  |
| `input` | `CreatePurchaseInvoiceApprovalDecisionInput!` |  |

### createManyPurchaseInvoiceApprovalDecisions

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
createManyPurchaseInvoiceApprovalDecisions(runId: ID!, input: [CreatePurchaseInvoiceApprovalDecisionInput!]!): [PurchaseInvoiceApprovalDecision!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `runId` | `ID!` |  |
| `input` | `[CreatePurchaseInvoiceApprovalDecisionInput!]!` |  |

### updateOnePurchaseInvoiceEvent

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateOnePurchaseInvoiceEvent(input: UpdateOnePurchaseInvoiceEventInput!): PurchaseInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePurchaseInvoiceEventInput!` |  |

### updateManyPurchaseInvoiceEvents

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateManyPurchaseInvoiceEvents(input: UpdateManyPurchaseInvoiceEventsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPurchaseInvoiceEventsInput!` |  |

### deleteOnePurchaseInvoiceEvent

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteOnePurchaseInvoiceEvent(input: DeleteOnePurchaseInvoiceEventInput!): PurchaseInvoiceEventDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceEventInput!` |  |

### deleteManyPurchaseInvoiceEvents

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteManyPurchaseInvoiceEvents(input: DeleteManyPurchaseInvoiceEventsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPurchaseInvoiceEventsInput!` |  |

### updateOnePurchaseInvoiceNote

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateOnePurchaseInvoiceNote(input: UpdateOnePurchaseInvoiceNoteInput!): PurchaseInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePurchaseInvoiceNoteInput!` |  |

### updateManyPurchaseInvoiceNotes

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateManyPurchaseInvoiceNotes(input: UpdateManyPurchaseInvoiceNotesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPurchaseInvoiceNotesInput!` |  |

### deleteOnePurchaseInvoiceNote

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteOnePurchaseInvoiceNote(input: DeleteOnePurchaseInvoiceNoteInput!): PurchaseInvoiceNoteDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceNoteInput!` |  |

### deleteManyPurchaseInvoiceNotes

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteManyPurchaseInvoiceNotes(input: DeleteManyPurchaseInvoiceNotesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPurchaseInvoiceNotesInput!` |  |

### updateOnePurchaseInvoiceLine

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateOnePurchaseInvoiceLine(input: UpdateOnePurchaseInvoiceLineInput!): PurchaseInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePurchaseInvoiceLineInput!` |  |

### updateManyPurchaseInvoiceLines

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateManyPurchaseInvoiceLines(input: UpdateManyPurchaseInvoiceLinesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPurchaseInvoiceLinesInput!` |  |

### deleteOnePurchaseInvoiceLine

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteOnePurchaseInvoiceLine(input: DeleteOnePurchaseInvoiceLineInput!): PurchaseInvoiceLineDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceLineInput!` |  |

### deleteManyPurchaseInvoiceLines

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteManyPurchaseInvoiceLines(input: DeleteManyPurchaseInvoiceLinesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPurchaseInvoiceLinesInput!` |  |

### updateOnePurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateOnePurchaseInvoice(input: UpdateOnePurchaseInvoiceInput!): PurchaseInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePurchaseInvoiceInput!` |  |

### updateManyPurchaseInvoices

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
updateManyPurchaseInvoices(input: UpdateManyPurchaseInvoicesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPurchaseInvoicesInput!` |  |

### deleteOnePurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteOnePurchaseInvoice(input: DeleteOnePurchaseInvoiceInput!): PurchaseInvoiceDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceInput!` |  |

### deleteManyPurchaseInvoices

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
deleteManyPurchaseInvoices(input: DeleteManyPurchaseInvoicesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPurchaseInvoicesInput!` |  |

### updateOnePurchaseInvoiceApprovalScheme

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
updateOnePurchaseInvoiceApprovalScheme(input: UpdateOnePurchaseInvoiceApprovalSchemeInput!): PurchaseInvoiceApprovalScheme!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOnePurchaseInvoiceApprovalSchemeInput!` |  |

### updateManyPurchaseInvoiceApprovalSchemes

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
updateManyPurchaseInvoiceApprovalSchemes(input: UpdateManyPurchaseInvoiceApprovalSchemesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyPurchaseInvoiceApprovalSchemesInput!` |  |

### deleteOnePurchaseInvoiceApprovalScheme

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
deleteOnePurchaseInvoiceApprovalScheme(input: DeleteOnePurchaseInvoiceApprovalSchemeInput!): PurchaseInvoiceApprovalSchemeDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOnePurchaseInvoiceApprovalSchemeInput!` |  |

### deleteManyPurchaseInvoiceApprovalSchemes

Requires: scope `purchase_invoices:write` · feature `purchase_invoice_approvals`.

```graphql
deleteManyPurchaseInvoiceApprovalSchemes(input: DeleteManyPurchaseInvoiceApprovalSchemesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyPurchaseInvoiceApprovalSchemesInput!` |  |

### uploadProcessDocumentForPurchaseInvoice

Requires: scope `purchase_invoices:write` · feature `process_documents`.

```graphql
uploadProcessDocumentForPurchaseInvoice(profileId: ID!, file: ProcessDocumentUploadInput!, currency: Currency, relationId: ID): UploadProcessDocumentForPurchaseInvoiceResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `file` | `ProcessDocumentUploadInput!` |  |
| `currency` | `Currency` |  |
| `relationId` | `ID` |  |

### writeOffPurchaseInvoicePaymentDifference

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
writeOffPurchaseInvoicePaymentDifference(profileId: ID!, purchaseInvoiceId: ID!, ledgerId: String): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `purchaseInvoiceId` | `ID!` |  |
| `ledgerId` | `String` |  |

### addPurchaseInvoiceToPaymentBatch

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
addPurchaseInvoiceToPaymentBatch(paymentBatchId: ID!, purchaseInvoiceId: ID!): PaymentBatch!
```

| Argument | Type |  |
| --- | --- | --- |
| `paymentBatchId` | `ID!` |  |
| `purchaseInvoiceId` | `ID!` |  |

### importPurchaseInvoicesSpreadsheet

Requires: scope `purchase_invoices:write` · feature `purchase_invoices`.

```graphql
importPurchaseInvoicesSpreadsheet(profileId: ID!, format: SpreadsheetFormat!, file: String!): SpreadsheetImportResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |
| `file` | `String!` |  |


---

<!-- /reference/graphql/quotes -->
# Quotes

GraphQL operations: quotes.

## Queries

### quoteAttachment

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAttachment(id: ID!): QuoteAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### quoteEvent

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteEvent(id: ID!): QuoteEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteEvents

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteEvents(paging: CursorPaging!, filter: QuoteEventFilter!, sorting: [QuoteEventSort!]!): QuoteEventConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteEventFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteEventSort!]!` | Specify to sort results. |

### quoteNote

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteNote(id: ID!): QuoteNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteNotes

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteNotes(paging: CursorPaging!, filter: QuoteNoteFilter!, sorting: [QuoteNoteSort!]!): QuoteNoteConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteNoteFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteNoteSort!]!` | Specify to sort results. |

### quoteLine

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteLine(id: ID!): QuoteLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteLines

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteLines(paging: CursorPaging!, filter: QuoteLineFilter!, sorting: [QuoteLineSort!]!): QuoteLineConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteLineFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteLineSort!]!` | Specify to sort results. |

### quoteAcceptanceDocument

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceDocument(id: ID!): QuoteAcceptanceDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteAcceptanceDocuments

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceDocuments(paging: CursorPaging!, filter: QuoteAcceptanceDocumentFilter!, sorting: [QuoteAcceptanceDocumentSort!]!): QuoteAcceptanceDocumentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteAcceptanceDocumentFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteAcceptanceDocumentSort!]!` | Specify to sort results. |

### quoteAcceptanceProcessDocument

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceProcessDocument(id: ID!): QuoteAcceptanceProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteAcceptanceProcessDocuments

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceProcessDocuments(paging: CursorPaging!, filter: QuoteAcceptanceProcessDocumentFilter!, sorting: [QuoteAcceptanceProcessDocumentSort!]!): QuoteAcceptanceProcessDocumentConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteAcceptanceProcessDocumentFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteAcceptanceProcessDocumentSort!]!` | Specify to sort results. |

### quoteAcceptanceProcess

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceProcess(id: ID!): QuoteAcceptanceProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quoteAcceptanceProcesses

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteAcceptanceProcesses(paging: CursorPaging!, filter: QuoteAcceptanceProcessFilter!, sorting: [QuoteAcceptanceProcessSort!]!): QuoteAcceptanceProcessConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteAcceptanceProcessFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteAcceptanceProcessSort!]!` | Specify to sort results. |

### quote

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quote(id: ID!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### quotes

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quotes(paging: CursorPaging!, filter: QuoteFilter!, sorting: [QuoteSort!]!): QuoteConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `QuoteFilter!` | Specify to filter the records returned. |
| `sorting` | `[QuoteSort!]!` | Specify to sort results. |

### quoteSalesTax

Requires: scope `quotes:read` · feature `quotes`.

```graphql
quoteSalesTax(profileId: ID!, input: QuoteSalesTaxInput!): QuoteSalesTaxResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `QuoteSalesTaxInput!` |  |

### publicQuote

Requires: scope `quotes:read`.

```graphql
publicQuote(profileUri: String!, quoteId: ID!, token: String): PublicQuote!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `quoteId` | `ID!` |  |
| `token` | `String` |  |

## Mutations

### createOneQuoteAttachment

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteAttachment(quoteId: ID!, input: CreateQuoteAttachmentInput!): QuoteAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `CreateQuoteAttachmentInput!` |  |

### updateOneQuoteAttachment

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteAttachment(input: UpdateOneQuoteAttachmentInput!): QuoteAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteAttachmentInput!` |  |

### deleteOneQuoteAttachment

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteAttachment(input: DeleteOneQuoteAttachmentInput!): QuoteAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteAttachmentInput!` |  |

### closeQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
closeQuote(id: ID!, send: Boolean): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `send` | `Boolean` |  |

### reopenQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
reopenQuote(id: ID!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### applyQuoteAcceptanceProcess

Requires: scope `quotes:write` · feature `quotes`.

```graphql
applyQuoteAcceptanceProcess(quoteId: ID!, processId: ID!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `processId` | `ID!` |  |

### acceptQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
acceptQuote(id: ID!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### copyProfileEmailAttachmentToQuoteAcceptanceProcess

Requires: scope `quotes:write` · feature `quotes`.

```graphql
copyProfileEmailAttachmentToQuoteAcceptanceProcess(processId: ID!, attachmentId: ID!): QuoteAcceptanceProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `processId` | `ID!` |  |
| `attachmentId` | `ID!` |  |

### createOneQuoteEvent

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteEvent(quoteId: ID!, input: CreateQuoteEventInput!): QuoteEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `CreateQuoteEventInput!` |  |

### createManyQuoteEvents

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteEvents(quoteId: ID!, input: [CreateQuoteEventInput!]!): [QuoteEvent!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `[CreateQuoteEventInput!]!` |  |

### createOneQuoteNote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteNote(quoteId: ID!, input: CreateQuoteNoteInput!): QuoteNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `CreateQuoteNoteInput!` |  |

### createManyQuoteNotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteNotes(quoteId: ID!, input: [CreateQuoteNoteInput!]!): [QuoteNote!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `[CreateQuoteNoteInput!]!` |  |

### createOneQuoteLine

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteLine(quoteId: ID!, input: CreateQuoteLineInput!): QuoteLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `CreateQuoteLineInput!` |  |

### createManyQuoteLines

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteLines(quoteId: ID!, input: [CreateQuoteLineInput!]!): [QuoteLine!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `[CreateQuoteLineInput!]!` |  |

### createOneQuoteAcceptanceDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteAcceptanceDocument(quoteId: ID!, input: CreateQuoteAcceptanceDocumentInput!): QuoteAcceptanceDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `CreateQuoteAcceptanceDocumentInput!` |  |

### createManyQuoteAcceptanceDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteAcceptanceDocuments(quoteId: ID!, input: [CreateQuoteAcceptanceDocumentInput!]!): [QuoteAcceptanceDocument!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `quoteId` | `ID!` |  |
| `input` | `[CreateQuoteAcceptanceDocumentInput!]!` |  |

### createOneQuoteAcceptanceProcessDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteAcceptanceProcessDocument(processId: ID!, input: CreateQuoteAcceptanceProcessDocumentInput!): QuoteAcceptanceProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `processId` | `ID!` |  |
| `input` | `CreateQuoteAcceptanceProcessDocumentInput!` |  |

### createManyQuoteAcceptanceProcessDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteAcceptanceProcessDocuments(processId: ID!, input: [CreateQuoteAcceptanceProcessDocumentInput!]!): [QuoteAcceptanceProcessDocument!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `processId` | `ID!` |  |
| `input` | `[CreateQuoteAcceptanceProcessDocumentInput!]!` |  |

### createOneQuoteAcceptanceProcess

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuoteAcceptanceProcess(profileId: ID!, input: CreateQuoteAcceptanceProcessInput!): QuoteAcceptanceProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateQuoteAcceptanceProcessInput!` |  |

### createManyQuoteAcceptanceProcesses

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuoteAcceptanceProcesses(profileId: ID!, input: [CreateQuoteAcceptanceProcessInput!]!): [QuoteAcceptanceProcess!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateQuoteAcceptanceProcessInput!]!` |  |

### createOneQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createOneQuote(profileId: ID!, input: CreateQuoteInput!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateQuoteInput!` |  |

### createManyQuotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createManyQuotes(profileId: ID!, input: [CreateQuoteInput!]!): [Quote!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateQuoteInput!]!` |  |

### updateOneQuoteEvent

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteEvent(input: UpdateOneQuoteEventInput!): QuoteEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteEventInput!` |  |

### updateManyQuoteEvents

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteEvents(input: UpdateManyQuoteEventsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteEventsInput!` |  |

### deleteOneQuoteEvent

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteEvent(input: DeleteOneQuoteEventInput!): QuoteEventDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteEventInput!` |  |

### deleteManyQuoteEvents

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteEvents(input: DeleteManyQuoteEventsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteEventsInput!` |  |

### updateOneQuoteNote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteNote(input: UpdateOneQuoteNoteInput!): QuoteNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteNoteInput!` |  |

### updateManyQuoteNotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteNotes(input: UpdateManyQuoteNotesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteNotesInput!` |  |

### deleteOneQuoteNote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteNote(input: DeleteOneQuoteNoteInput!): QuoteNoteDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteNoteInput!` |  |

### deleteManyQuoteNotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteNotes(input: DeleteManyQuoteNotesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteNotesInput!` |  |

### updateOneQuoteLine

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteLine(input: UpdateOneQuoteLineInput!): QuoteLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteLineInput!` |  |

### updateManyQuoteLines

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteLines(input: UpdateManyQuoteLinesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteLinesInput!` |  |

### deleteOneQuoteLine

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteLine(input: DeleteOneQuoteLineInput!): QuoteLineDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteLineInput!` |  |

### deleteManyQuoteLines

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteLines(input: DeleteManyQuoteLinesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteLinesInput!` |  |

### updateOneQuoteAcceptanceDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteAcceptanceDocument(input: UpdateOneQuoteAcceptanceDocumentInput!): QuoteAcceptanceDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteAcceptanceDocumentInput!` |  |

### updateManyQuoteAcceptanceDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteAcceptanceDocuments(input: UpdateManyQuoteAcceptanceDocumentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteAcceptanceDocumentsInput!` |  |

### deleteOneQuoteAcceptanceDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteAcceptanceDocument(input: DeleteOneQuoteAcceptanceDocumentInput!): QuoteAcceptanceDocumentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteAcceptanceDocumentInput!` |  |

### deleteManyQuoteAcceptanceDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteAcceptanceDocuments(input: DeleteManyQuoteAcceptanceDocumentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteAcceptanceDocumentsInput!` |  |

### updateOneQuoteAcceptanceProcessDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteAcceptanceProcessDocument(input: UpdateOneQuoteAcceptanceProcessDocumentInput!): QuoteAcceptanceProcessDocument!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteAcceptanceProcessDocumentInput!` |  |

### updateManyQuoteAcceptanceProcessDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteAcceptanceProcessDocuments(input: UpdateManyQuoteAcceptanceProcessDocumentsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteAcceptanceProcessDocumentsInput!` |  |

### deleteOneQuoteAcceptanceProcessDocument

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteAcceptanceProcessDocument(input: DeleteOneQuoteAcceptanceProcessDocumentInput!): QuoteAcceptanceProcessDocumentDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteAcceptanceProcessDocumentInput!` |  |

### deleteManyQuoteAcceptanceProcessDocuments

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteAcceptanceProcessDocuments(input: DeleteManyQuoteAcceptanceProcessDocumentsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteAcceptanceProcessDocumentsInput!` |  |

### updateOneQuoteAcceptanceProcess

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuoteAcceptanceProcess(input: UpdateOneQuoteAcceptanceProcessInput!): QuoteAcceptanceProcess!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteAcceptanceProcessInput!` |  |

### updateManyQuoteAcceptanceProcesses

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuoteAcceptanceProcesses(input: UpdateManyQuoteAcceptanceProcessesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuoteAcceptanceProcessesInput!` |  |

### deleteOneQuoteAcceptanceProcess

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuoteAcceptanceProcess(input: DeleteOneQuoteAcceptanceProcessInput!): QuoteAcceptanceProcessDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteAcceptanceProcessInput!` |  |

### deleteManyQuoteAcceptanceProcesses

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuoteAcceptanceProcesses(input: DeleteManyQuoteAcceptanceProcessesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuoteAcceptanceProcessesInput!` |  |

### updateOneQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateOneQuote(input: UpdateOneQuoteInput!): Quote!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneQuoteInput!` |  |

### updateManyQuotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
updateManyQuotes(input: UpdateManyQuotesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyQuotesInput!` |  |

### deleteOneQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteOneQuote(input: DeleteOneQuoteInput!): QuoteDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneQuoteInput!` |  |

### deleteManyQuotes

Requires: scope `quotes:write` · feature `quotes`.

```graphql
deleteManyQuotes(input: DeleteManyQuotesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyQuotesInput!` |  |

### createPublicQuotePaymentIntent

Requires: scope `quotes:write` · feature `quotes`.

```graphql
createPublicQuotePaymentIntent(profileUri: String!, quoteId: ID!, token: String): PublicQuotePaymentIntent!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `quoteId` | `ID!` |  |
| `token` | `String` |  |

### acceptPublicQuote

Requires: scope `quotes:write` · feature `quotes`.

```graphql
acceptPublicQuote(profileUri: String!, quoteId: ID!, token: String): PublicQuote!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `quoteId` | `ID!` |  |
| `token` | `String` |  |


---

<!-- /reference/graphql/relations -->
# Relations

GraphQL operations: relations.

## Queries

### relationAttachment

Requires: scope `relations:read` · feature `relations`.

```graphql
relationAttachment(id: ID!): RelationAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### relationPaymentTiming

How quickly this contact actually pays versus the company median, from settled sales invoices. Use before changing payment terms. Not plan-gated. Newest paid invoices first, capped at 50.

Requires: scope `relations:read` · feature `relations`.

```graphql
relationPaymentTiming(profileId: ID!, relationId: ID!): RelationPaymentTiming!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `relationId` | `ID!` |  |

### relationList

Requires: scope `relations:read` · feature `relations`.

```graphql
relationList(profileId: ID!, search: String, activity: RelationActivityFilter, kind: RelationKindFilter, first: Int, after: String): RelationListConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `search` | `String` |  |
| `activity` | `RelationActivityFilter` |  |
| `kind` | `RelationKindFilter` |  |
| `first` | `Int` |  |
| `after` | `String` |  |

### relation

Requires: scope `relations:read` · feature `relations`.

```graphql
relation(id: ID!): Relation!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### relations

Requires: scope `relations:read` · feature `relations`.

```graphql
relations(paging: CursorPaging!, filter: RelationFilter!, sorting: [RelationSort!]!): RelationConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `RelationFilter!` | Specify to filter the records returned. |
| `sorting` | `[RelationSort!]!` | Specify to sort results. |

### relationBankAccount

Requires: scope `relations:read` · feature `relations`.

```graphql
relationBankAccount(id: ID!): RelationBankAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### relationBankAccounts

Requires: scope `relations:read` · feature `relations`.

```graphql
relationBankAccounts(paging: CursorPaging!, filter: RelationBankAccountFilter!, sorting: [RelationBankAccountSort!]!): RelationBankAccountConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `RelationBankAccountFilter!` | Specify to filter the records returned. |
| `sorting` | `[RelationBankAccountSort!]!` | Specify to sort results. |

### openPurchaseOrdersForRelation

Purchase orders a supplier can still deliver or invoice against (issued, partially received, received, partially invoiced), oldest first, with their lines and open amount.

Requires: scope `relations:read` · feature `purchase_orders`.

```graphql
openPurchaseOrdersForRelation(relationId: ID!): [PurchaseOrder!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |

### relationsSpreadsheetImportTemplate

Requires: scope `relations:read` · feature `relations`.

```graphql
relationsSpreadsheetImportTemplate(format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `format` | `SpreadsheetFormat!` |  |

### exportRelationsSpreadsheet

Requires: scope `relations:read` · feature `relations`.

```graphql
exportRelationsSpreadsheet(profileId: ID!, format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |

### publicRelationInvoices

Requires: scope `relations:read`.

```graphql
publicRelationInvoices(profileUri: String!, relationId: ID!, token: String): [PublicRelationInvoice!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `relationId` | `ID!` |  |
| `token` | `String` |  |

### publicRelation

Requires: scope `relations:read`.

```graphql
publicRelation(profileUri: String!, relationId: ID!, token: String): PublicRelation!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `relationId` | `ID!` |  |
| `token` | `String` |  |

### publicRelationRecurrings

Requires: scope `relations:read`.

```graphql
publicRelationRecurrings(profileUri: String!, relationId: ID!, token: String): [PublicRelationRecurring!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `relationId` | `ID!` |  |
| `token` | `String` |  |

### relationRiskFindings

Open Risk Guard findings on a relation (supplier) and its bank accounts, newest first: which check, severity and what it saw. IBANs are masked. Read-only.

Requires: scope `relations:read` · feature `relations`.

```graphql
relationRiskFindings(relationId: ID!): [RelationRiskFinding!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |

## Mutations

### createOneRelationAttachment

Requires: scope `relations:write` · feature `relations`.

```graphql
createOneRelationAttachment(relationId: ID!, input: CreateRelationAttachmentInput!): RelationAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |
| `input` | `CreateRelationAttachmentInput!` |  |

### deleteOneRelationAttachment

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteOneRelationAttachment(input: DeleteOneRelationAttachmentInput!): RelationAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneRelationAttachmentInput!` |  |

### ensureEmployeeRelation

Requires: scope `relations:write` · feature `payroll`.

```graphql
ensureEmployeeRelation(employeeId: String!): Employee!
```

| Argument | Type |  |
| --- | --- | --- |
| `employeeId` | `String!` |  |

### dedupeRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
dedupeRelation(input: DedupeRelationInput!): Relation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DedupeRelationInput!` |  |

### deleteRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteRelation(id: ID!): ID!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createOneRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
createOneRelation(profileId: ID!, input: CreateRelationInput!): Relation!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateRelationInput!` |  |

### createManyRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
createManyRelations(profileId: ID!, input: [CreateRelationInput!]!): [Relation!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateRelationInput!]!` |  |

### createOneRelationBankAccount

Requires: scope `relations:write` · feature `relations`.

```graphql
createOneRelationBankAccount(relationId: ID!, input: CreateRelationBankAccountInput!): RelationBankAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |
| `input` | `CreateRelationBankAccountInput!` |  |

### createManyRelationBankAccounts

Requires: scope `relations:write` · feature `relations`.

```graphql
createManyRelationBankAccounts(relationId: ID!, input: [CreateRelationBankAccountInput!]!): [RelationBankAccount!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |
| `input` | `[CreateRelationBankAccountInput!]!` |  |

### updateOneRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
updateOneRelation(input: UpdateOneRelationInput!): Relation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneRelationInput!` |  |

### updateManyRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
updateManyRelations(input: UpdateManyRelationsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyRelationsInput!` |  |

### deleteOneRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteOneRelation(input: DeleteOneRelationInput!): RelationDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneRelationInput!` |  |

### deleteManyRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteManyRelations(input: DeleteManyRelationsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyRelationsInput!` |  |

### updateOneRelationBankAccount

Requires: scope `relations:write` · feature `relations`.

```graphql
updateOneRelationBankAccount(input: UpdateOneRelationBankAccountInput!): RelationBankAccount!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneRelationBankAccountInput!` |  |

### updateManyRelationBankAccounts

Requires: scope `relations:write` · feature `relations`.

```graphql
updateManyRelationBankAccounts(input: UpdateManyRelationBankAccountsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyRelationBankAccountsInput!` |  |

### deleteOneRelationBankAccount

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteOneRelationBankAccount(input: DeleteOneRelationBankAccountInput!): RelationBankAccountDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneRelationBankAccountInput!` |  |

### deleteManyRelationBankAccounts

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteManyRelationBankAccounts(input: DeleteManyRelationBankAccountsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyRelationBankAccountsInput!` |  |

### importRelationsSpreadsheet

Requires: scope `relations:write` · feature `relations`.

```graphql
importRelationsSpreadsheet(profileId: ID!, format: SpreadsheetFormat!, file: String!): SpreadsheetImportResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |
| `file` | `String!` |  |

### createOneEnterpriseProfileRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
createOneEnterpriseProfileRelation(input: CreateOneEnterpriseProfileRelationInput!): EnterpriseProfileRelation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateOneEnterpriseProfileRelationInput!` |  |

### createManyEnterpriseProfileRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
createManyEnterpriseProfileRelations(input: CreateManyEnterpriseProfileRelationsInput!): [EnterpriseProfileRelation!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateManyEnterpriseProfileRelationsInput!` |  |

### updateOneEnterpriseProfileRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
updateOneEnterpriseProfileRelation(input: UpdateOneEnterpriseProfileRelationInput!): EnterpriseProfileRelation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneEnterpriseProfileRelationInput!` |  |

### updateManyEnterpriseProfileRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
updateManyEnterpriseProfileRelations(input: UpdateManyEnterpriseProfileRelationsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyEnterpriseProfileRelationsInput!` |  |

### deleteOneEnterpriseProfileRelation

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteOneEnterpriseProfileRelation(input: DeleteOneEnterpriseProfileRelationInput!): EnterpriseProfileRelationDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneEnterpriseProfileRelationInput!` |  |

### deleteManyEnterpriseProfileRelations

Requires: scope `relations:write` · feature `relations`.

```graphql
deleteManyEnterpriseProfileRelations(input: DeleteManyEnterpriseProfileRelationsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyEnterpriseProfileRelationsInput!` |  |

### saveClientOnboardingContact

Requires: scope `relations:write`.

```graphql
saveClientOnboardingContact(token: String!, input: ClientOnboardingContactInput!): PublicClientOnboardingInvite!
```

| Argument | Type |  |
| --- | --- | --- |
| `token` | `String!` |  |
| `input` | `ClientOnboardingContactInput!` |  |


---

<!-- /reference/graphql/reminders -->
# Reminders

GraphQL operations: reminders.

## Queries

### reminderEvent

Requires: scope `reminders:read` · feature `reminders`.

```graphql
reminderEvent(id: ID!): ReminderEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### reminderEvents

Requires: scope `reminders:read` · feature `reminders`.

```graphql
reminderEvents(paging: CursorPaging!, filter: ReminderEventFilter!, sorting: [ReminderEventSort!]!): ReminderEventConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ReminderEventFilter!` | Specify to filter the records returned. |
| `sorting` | `[ReminderEventSort!]!` | Specify to sort results. |

### reminder

Requires: scope `reminders:read` · feature `reminders`.

```graphql
reminder(id: ID!): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### reminders

Requires: scope `reminders:read` · feature `reminders`.

```graphql
reminders(paging: CursorPaging!, filter: ReminderFilter!, sorting: [ReminderSort!]!): ReminderConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `ReminderFilter!` | Specify to filter the records returned. |
| `sorting` | `[ReminderSort!]!` | Specify to sort results. |

### publicReminder

Requires: scope `reminders:read`.

```graphql
publicReminder(profileUri: String!, reminderId: ID!, token: String): PublicReminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `reminderId` | `ID!` |  |
| `token` | `String` |  |

## Mutations

### createAndSendInvoiceReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createAndSendInvoiceReminder(salesInvoiceId: ID!, send: Boolean): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `send` | `Boolean` |  |

### createAndSendRelationReminder

Requires: scope `reminders:write` · feature `relations`.

```graphql
createAndSendRelationReminder(relationId: ID!, send: Boolean): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `relationId` | `ID!` |  |
| `send` | `Boolean` |  |

### createAndSendInvoicesReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createAndSendInvoicesReminder(salesInvoiceIds: [ID!]!, send: Boolean): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceIds` | `[ID!]!` |  |
| `send` | `Boolean` |  |

### sendReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
sendReminder(id: ID!): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### closeReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
closeReminder(id: ID!): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### createOneReminderEvent

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createOneReminderEvent(reminderId: ID!, input: CreateReminderEventInput!): ReminderEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `reminderId` | `ID!` |  |
| `input` | `CreateReminderEventInput!` |  |

### createManyReminderEvents

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createManyReminderEvents(reminderId: ID!, input: [CreateReminderEventInput!]!): [ReminderEvent!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `reminderId` | `ID!` |  |
| `input` | `[CreateReminderEventInput!]!` |  |

### createOneReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createOneReminder(profileId: ID!, input: CreateReminderInput!): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateReminderInput!` |  |

### createManyReminders

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createManyReminders(profileId: ID!, input: [CreateReminderInput!]!): [Reminder!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateReminderInput!]!` |  |

### updateOneReminderEvent

Requires: scope `reminders:write` · feature `reminders`.

```graphql
updateOneReminderEvent(input: UpdateOneReminderEventInput!): ReminderEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneReminderEventInput!` |  |

### updateManyReminderEvents

Requires: scope `reminders:write` · feature `reminders`.

```graphql
updateManyReminderEvents(input: UpdateManyReminderEventsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyReminderEventsInput!` |  |

### deleteOneReminderEvent

Requires: scope `reminders:write` · feature `reminders`.

```graphql
deleteOneReminderEvent(input: DeleteOneReminderEventInput!): ReminderEventDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneReminderEventInput!` |  |

### deleteManyReminderEvents

Requires: scope `reminders:write` · feature `reminders`.

```graphql
deleteManyReminderEvents(input: DeleteManyReminderEventsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyReminderEventsInput!` |  |

### updateOneReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
updateOneReminder(input: UpdateOneReminderInput!): Reminder!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneReminderInput!` |  |

### updateManyReminders

Requires: scope `reminders:write` · feature `reminders`.

```graphql
updateManyReminders(input: UpdateManyRemindersInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyRemindersInput!` |  |

### deleteOneReminder

Requires: scope `reminders:write` · feature `reminders`.

```graphql
deleteOneReminder(input: DeleteOneReminderInput!): ReminderDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneReminderInput!` |  |

### deleteManyReminders

Requires: scope `reminders:write` · feature `reminders`.

```graphql
deleteManyReminders(input: DeleteManyRemindersInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyRemindersInput!` |  |

### createPublicReminderPaymentIntent

Requires: scope `reminders:write` · feature `reminders`.

```graphql
createPublicReminderPaymentIntent(profileUri: String!, reminderId: ID!, token: String): PublicReminderPaymentIntent!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `reminderId` | `ID!` |  |
| `token` | `String` |  |


---

<!-- /reference/graphql/reports -->
# Reports

GraphQL operations: reports.

## Queries

### cashflowReport

Historical cashflow for a company: opening/closing liquid balance, inflow/outflow by month and category. Amounts are minor units. Not a forecast — use forecastReport for expected/estimated future cash and profit.

Requires: scope `reports:read` · feature `advanced_reports`.

```graphql
cashflowReport(profileId: ID!, start: DateTime, end: DateTime): CashflowReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `start` | `DateTime` |  |
| `end` | `DateTime` |  |

### forecastReport

Forward cash and profit forecast for `months` ahead (includes the current month). Expected lines come from open invoices, recurring, and loan installments; estimated lines are a history run-rate with mid/low/high bands. enoughHistory is false when estimates are zero. Plan-gated. Not historical cashflow (cashflowReport) and not the booked P&L (financialStatement).

Requires: scope `reports:read` · feature `forecasts`.

```graphql
forecastReport(profileId: ID!, months: Int!): ForecastReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `months` | `Int!` |  |

### debtorReport

Accounts receivable aging: who owes the company, invoices, and days overdue as of `end`. Amounts are minor units.

Requires: scope `reports:read` · feature `advanced_reports`.

```graphql
debtorReport(profileId: ID!, end: DateTime): DebtorCreditorReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `end` | `DateTime` |  |

### creditorReport

Accounts payable aging: who the company owes, bills, and days overdue as of `end`. Amounts are minor units.

Requires: scope `reports:read` · feature `advanced_reports`.

```graphql
creditorReport(profileId: ID!, end: DateTime): DebtorCreditorReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `end` | `DateTime` |  |

### profileUsageReport

Counts of processed documents and booked/draft invoices in a period. Usage metrics, not money.

Requires: scope `reports:read`.

```graphql
profileUsageReport(profileId: ID!, start: DateTime, end: DateTime): ProfileUsageReport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `start` | `DateTime` |  |
| `end` | `DateTime` |  |

### reportTemplates

Requires: scope `reports:read`.

```graphql
reportTemplates(bookkeeperId: ID, profileId: ID): [ReportTemplate!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID` |  |
| `profileId` | `ID` |  |

### reportTemplatePreview

HTML preview of a template layer on a dossier’s live data.

Requires: scope `reports:read`.

```graphql
reportTemplatePreview(dossierId: ID!, layer: JSONObject!, package: String!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `dossierId` | `ID!` |  |
| `layer` | `JSONObject!` |  |
| `package` | `String!` |  |

## Mutations

### saveReportTemplate

Requires: scope `reports:write`.

```graphql
saveReportTemplate(input: SaveReportTemplateInput!): ReportTemplate!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `SaveReportTemplateInput!` |  |

### deleteReportTemplate

Requires: scope `reports:write`.

```graphql
deleteReportTemplate(id: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |


---

<!-- /reference/graphql/sales-invoices -->
# Sales invoices

GraphQL operations: sales invoices.

## Queries

### overpaidSalesInvoiceIds

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
overpaidSalesInvoiceIds(profileId: ID!): [ID!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### salesInvoiceAttachment

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceAttachment(id: ID!): SalesInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### salesInvoiceEvent

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceEvent(id: ID!): SalesInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### salesInvoiceEvents

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceEvents(paging: CursorPaging!, filter: SalesInvoiceEventFilter!, sorting: [SalesInvoiceEventSort!]!): SalesInvoiceEventConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `SalesInvoiceEventFilter!` | Specify to filter the records returned. |
| `sorting` | `[SalesInvoiceEventSort!]!` | Specify to sort results. |

### salesInvoiceNote

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceNote(id: ID!): SalesInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### salesInvoiceNotes

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceNotes(paging: CursorPaging!, filter: SalesInvoiceNoteFilter!, sorting: [SalesInvoiceNoteSort!]!): SalesInvoiceNoteConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `SalesInvoiceNoteFilter!` | Specify to filter the records returned. |
| `sorting` | `[SalesInvoiceNoteSort!]!` | Specify to sort results. |

### salesInvoiceLine

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceLine(id: ID!): SalesInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### salesInvoiceLines

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceLines(paging: CursorPaging!, filter: SalesInvoiceLineFilter!, sorting: [SalesInvoiceLineSort!]!): SalesInvoiceLineConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `SalesInvoiceLineFilter!` | Specify to filter the records returned. |
| `sorting` | `[SalesInvoiceLineSort!]!` | Specify to sort results. |

### salesInvoice

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoice(id: ID!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### salesInvoices

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoices(paging: CursorPaging!, filter: SalesInvoiceFilter!, sorting: [SalesInvoiceSort!]!): SalesInvoiceConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `SalesInvoiceFilter!` | Specify to filter the records returned. |
| `sorting` | `[SalesInvoiceSort!]!` | Specify to sort results. |

### salesInvoiceLayoutPreviewHtml

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoiceLayoutPreviewHtml(profileId: ID!, layoutJson: String, logo: String): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `layoutJson` | `String` |  |
| `logo` | `String` |  |

### practiceSalesInvoicePreview

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
practiceSalesInvoicePreview(profileId: ID!): PracticeSalesInvoicePreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### salesInvoicesSpreadsheetImportTemplate

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
salesInvoicesSpreadsheetImportTemplate(format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `format` | `SpreadsheetFormat!` |  |

### exportSalesInvoicesSpreadsheet

Requires: scope `sales_invoices:read` · feature `sales_invoices`.

```graphql
exportSalesInvoicesSpreadsheet(profileId: ID!, format: SpreadsheetFormat!): SpreadsheetTemplateExport!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |

### publicSalesInvoice

Requires: scope `sales_invoices:read`.

```graphql
publicSalesInvoice(profileUri: String!, invoiceId: ID!, token: String): PublicSalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileUri` | `String!` |  |
| `invoiceId` | `ID!` |  |
| `token` | `String` |  |

## Mutations

### closeSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
closeSalesInvoice(id: ID!, send: Boolean): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `send` | `Boolean` |  |

### setSalesInvoiceExternalId

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
setSalesInvoiceExternalId(id: ID!, externalId: String!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `externalId` | `String!` |  |

### reopenSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
reopenSalesInvoice(id: ID!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### creditSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
creditSalesInvoice(id: ID!, close: Boolean): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `close` | `Boolean` |  |

### duplicateSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
duplicateSalesInvoice(id: ID!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### applySalesInvoiceDocumentDiscount

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
applySalesInvoiceDocumentDiscount(input: ApplySalesInvoiceDocumentDiscountInput!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `ApplySalesInvoiceDocumentDiscountInput!` |  |

### removeSalesInvoiceDocumentDiscount

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
removeSalesInvoiceDocumentDiscount(input: RemoveSalesInvoiceDocumentDiscountInput!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `RemoveSalesInvoiceDocumentDiscountInput!` |  |

### assignProjectToSalesInvoices

Requires: scope `sales_invoices:write` · feature `projects`.

```graphql
assignProjectToSalesInvoices(input: AssignProjectToSalesInvoicesInput!): AssignProjectToSalesInvoicesResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `AssignProjectToSalesInvoicesInput!` |  |

### createOneSalesInvoiceAttachment

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createOneSalesInvoiceAttachment(salesInvoiceId: ID!, input: CreateSalesInvoiceAttachmentInput!): SalesInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `CreateSalesInvoiceAttachmentInput!` |  |

### updateOneSalesInvoiceAttachment

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateOneSalesInvoiceAttachment(input: UpdateOneSalesInvoiceAttachmentInput!): SalesInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSalesInvoiceAttachmentInput!` |  |

### deleteOneSalesInvoiceAttachment

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteOneSalesInvoiceAttachment(input: DeleteOneSalesInvoiceAttachmentInput!): SalesInvoiceAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSalesInvoiceAttachmentInput!` |  |

### createOneSalesInvoiceEvent

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createOneSalesInvoiceEvent(salesInvoiceId: ID!, input: CreateSalesInvoiceEventInput!): SalesInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `CreateSalesInvoiceEventInput!` |  |

### createManySalesInvoiceEvents

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createManySalesInvoiceEvents(salesInvoiceId: ID!, input: [CreateSalesInvoiceEventInput!]!): [SalesInvoiceEvent!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `[CreateSalesInvoiceEventInput!]!` |  |

### createOneSalesInvoiceNote

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createOneSalesInvoiceNote(salesInvoiceId: ID!, input: CreateSalesInvoiceNoteInput!): SalesInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `CreateSalesInvoiceNoteInput!` |  |

### createManySalesInvoiceNotes

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createManySalesInvoiceNotes(salesInvoiceId: ID!, input: [CreateSalesInvoiceNoteInput!]!): [SalesInvoiceNote!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `[CreateSalesInvoiceNoteInput!]!` |  |

### createOneSalesInvoiceLine

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createOneSalesInvoiceLine(salesInvoiceId: ID!, input: CreateSalesInvoiceLineInput!): SalesInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `CreateSalesInvoiceLineInput!` |  |

### createManySalesInvoiceLines

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createManySalesInvoiceLines(salesInvoiceId: ID!, input: [CreateSalesInvoiceLineInput!]!): [SalesInvoiceLine!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `salesInvoiceId` | `ID!` |  |
| `input` | `[CreateSalesInvoiceLineInput!]!` |  |

### createOneSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createOneSalesInvoice(profileId: ID!, input: CreateSalesInvoiceInput!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateSalesInvoiceInput!` |  |

### createManySalesInvoices

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
createManySalesInvoices(profileId: ID!, input: [CreateSalesInvoiceInput!]!): [SalesInvoice!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateSalesInvoiceInput!]!` |  |

### updateOneSalesInvoiceEvent

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateOneSalesInvoiceEvent(input: UpdateOneSalesInvoiceEventInput!): SalesInvoiceEvent!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSalesInvoiceEventInput!` |  |

### updateManySalesInvoiceEvents

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateManySalesInvoiceEvents(input: UpdateManySalesInvoiceEventsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManySalesInvoiceEventsInput!` |  |

### deleteOneSalesInvoiceEvent

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteOneSalesInvoiceEvent(input: DeleteOneSalesInvoiceEventInput!): SalesInvoiceEventDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSalesInvoiceEventInput!` |  |

### deleteManySalesInvoiceEvents

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteManySalesInvoiceEvents(input: DeleteManySalesInvoiceEventsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManySalesInvoiceEventsInput!` |  |

### updateOneSalesInvoiceNote

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateOneSalesInvoiceNote(input: UpdateOneSalesInvoiceNoteInput!): SalesInvoiceNote!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSalesInvoiceNoteInput!` |  |

### updateManySalesInvoiceNotes

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateManySalesInvoiceNotes(input: UpdateManySalesInvoiceNotesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManySalesInvoiceNotesInput!` |  |

### deleteOneSalesInvoiceNote

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteOneSalesInvoiceNote(input: DeleteOneSalesInvoiceNoteInput!): SalesInvoiceNoteDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSalesInvoiceNoteInput!` |  |

### deleteManySalesInvoiceNotes

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteManySalesInvoiceNotes(input: DeleteManySalesInvoiceNotesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManySalesInvoiceNotesInput!` |  |

### updateOneSalesInvoiceLine

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateOneSalesInvoiceLine(input: UpdateOneSalesInvoiceLineInput!): SalesInvoiceLine!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSalesInvoiceLineInput!` |  |

### updateManySalesInvoiceLines

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateManySalesInvoiceLines(input: UpdateManySalesInvoiceLinesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManySalesInvoiceLinesInput!` |  |

### deleteOneSalesInvoiceLine

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteOneSalesInvoiceLine(input: DeleteOneSalesInvoiceLineInput!): SalesInvoiceLineDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSalesInvoiceLineInput!` |  |

### deleteManySalesInvoiceLines

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteManySalesInvoiceLines(input: DeleteManySalesInvoiceLinesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManySalesInvoiceLinesInput!` |  |

### updateOneSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateOneSalesInvoice(input: UpdateOneSalesInvoiceInput!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSalesInvoiceInput!` |  |

### updateManySalesInvoices

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
updateManySalesInvoices(input: UpdateManySalesInvoicesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManySalesInvoicesInput!` |  |

### deleteOneSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteOneSalesInvoice(input: DeleteOneSalesInvoiceInput!): SalesInvoiceDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSalesInvoiceInput!` |  |

### deleteManySalesInvoices

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
deleteManySalesInvoices(input: DeleteManySalesInvoicesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManySalesInvoicesInput!` |  |

### convertQuoteToSalesInvoice

Requires: scope `sales_invoices:write` · feature `quotes`.

```graphql
convertQuoteToSalesInvoice(id: ID!): SalesInvoice!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### writeOffSalesInvoicePaymentDifference

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
writeOffSalesInvoicePaymentDifference(profileId: ID!, salesInvoiceId: ID!, ledgerId: String): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `salesInvoiceId` | `ID!` |  |
| `ledgerId` | `String` |  |

### sendPracticeSalesInvoice

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
sendPracticeSalesInvoice(profileId: ID!): PracticeSalesInvoiceResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### importSalesInvoicesSpreadsheet

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
importSalesInvoicesSpreadsheet(profileId: ID!, format: SpreadsheetFormat!, file: String!): SpreadsheetImportResult!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `format` | `SpreadsheetFormat!` |  |
| `file` | `String!` |  |

### markSalesInvoiceUncollectible

Mark a closed sales invoice as uncollectible (bad debt) or undo it. Feeds VAT bad-debt relief checks; does not book anything.

Requires: scope `sales_invoices:write` · feature `sales_invoices`.

```graphql
markSalesInvoiceUncollectible(id: ID!, uncollectible: Boolean!, note: String, vatReliefClaimed: Boolean): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `uncollectible` | `Boolean!` |  |
| `note` | `String` |  |
| `vatReliefClaimed` | `Boolean` |  |


---

<!-- /reference/graphql/settings -->
# Settings

GraphQL operations: settings.

## Queries

### inventorySettings

Requires: scope `settings:read` · feature `inventory`.

```graphql
inventorySettings(profileId: ID!): InventorySettings
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### platformDocumentRenderSettings

Requires: scope `settings:read`.

```graphql
platformDocumentRenderSettings(platformId: ID): [PlatformDocumentRenderSetting!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `platformId` | `ID` |  |

### profileAiSettings

Requires: scope `settings:read`.

```graphql
profileAiSettings(profileId: ID!): ProfileAiSettingsView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

## Mutations

### updateInventorySettings

Requires: scope `settings:write` · feature `inventory`.

```graphql
updateInventorySettings(input: UpdateInventorySettingsDto!): InventorySettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateInventorySettingsDto!` |  |

### updateAnnualAccountsSettings

Requires: scope `settings:write`.

```graphql
updateAnnualAccountsSettings(id: ID!, input: UpdateAnnualAccountsSettingsInput!): AnnualAccountsDossier!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `input` | `UpdateAnnualAccountsSettingsInput!` |  |

### setPlatformDocumentRenderSetting

Requires: scope `settings:write`.

```graphql
setPlatformDocumentRenderSetting(documentType: DocumentType!, mode: DocumentRenderMode!, timeoutSeconds: Int): PlatformDocumentRenderSetting!
```

| Argument | Type |  |
| --- | --- | --- |
| `documentType` | `DocumentType!` |  |
| `mode` | `DocumentRenderMode!` |  |
| `timeoutSeconds` | `Int` |  |

### updateProfileAiSettings

Requires: scope `settings:write`.

```graphql
updateProfileAiSettings(profileId: ID!, input: UpdateProfileAiSettingsInput!): ProfileAiSettingsView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `UpdateProfileAiSettingsInput!` |  |


---

<!-- /reference/graphql/settlements -->
# Settlements

GraphQL operations: settlements.

## Queries

### settlementAttachment

Requires: scope `settlements:read` · feature `settlements`.

```graphql
settlementAttachment(id: ID!): SettlementAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### settlement

Requires: scope `settlements:read` · feature `settlements`.

```graphql
settlement(id: ID!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### settlements

Requires: scope `settlements:read` · feature `settlements`.

```graphql
settlements(paging: CursorPaging!, filter: SettlementFilter!, sorting: [SettlementSort!]!): SettlementConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `SettlementFilter!` | Specify to filter the records returned. |
| `sorting` | `[SettlementSort!]!` | Specify to sort results. |

## Mutations

### createOneSettlementAttachment

Requires: scope `settlements:write` · feature `settlements`.

```graphql
createOneSettlementAttachment(settlementId: ID!, input: CreateSettlementAttachmentInput!): SettlementAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `settlementId` | `ID!` |  |
| `input` | `CreateSettlementAttachmentInput!` |  |

### deleteOneSettlementAttachment

Requires: scope `settlements:write` · feature `settlements`.

```graphql
deleteOneSettlementAttachment(input: DeleteOneSettlementAttachmentInput!): SettlementAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSettlementAttachmentInput!` |  |

### createSettlement

Requires: scope `settlements:write` · feature `settlements`.

```graphql
createSettlement(input: CreateSettlementBatchInput!, profileId: String!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateSettlementBatchInput!` |  |
| `profileId` | `String!` |  |

### createSettlementFromPayment

Requires: scope `settlements:write` · feature `settlements`.

```graphql
createSettlementFromPayment(input: CreateSettlementFromPaymentInput!, profileId: String!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateSettlementFromPaymentInput!` |  |
| `profileId` | `String!` |  |

### updateSettlement

Requires: scope `settlements:write` · feature `settlements`.

```graphql
updateSettlement(input: UpdateSettlementBatchInput!, profileId: String!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateSettlementBatchInput!` |  |
| `profileId` | `String!` |  |

### deleteOneSettlement

Requires: scope `settlements:write` · feature `settlements`.

```graphql
deleteOneSettlement(input: DeleteOneSettlementInput!): SettlementDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneSettlementInput!` |  |

### createOneSettlement

Requires: scope `settlements:write` · feature `settlements`.

```graphql
createOneSettlement(profileId: ID!, input: CreateSettlementInput!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateSettlementInput!` |  |

### createManySettlements

Requires: scope `settlements:write` · feature `settlements`.

```graphql
createManySettlements(profileId: ID!, input: [CreateSettlementInput!]!): [Settlement!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateSettlementInput!]!` |  |

### updateOneSettlement

Requires: scope `settlements:write` · feature `settlements`.

```graphql
updateOneSettlement(input: UpdateOneSettlementInput!): Settlement!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneSettlementInput!` |  |

### updateManySettlements

Requires: scope `settlements:write` · feature `settlements`.

```graphql
updateManySettlements(input: UpdateManySettlementsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManySettlementsInput!` |  |


---

<!-- /reference/graphql/subscriptions -->
# Subscriptions

GraphQL operations: subscriptions.

## Queries

### profileSubscription

Requires: scope `subscriptions:read`.

```graphql
profileSubscription(profileId: ID!): ProfileSubscription
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### profileSubscriptionInvoices

Requires: scope `subscriptions:read`.

```graphql
profileSubscriptionInvoices(profileId: ID!): [ProfileSubscriptionInvoice!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### profileSubscriptionInvoicePdf

Requires: scope `subscriptions:read`.

```graphql
profileSubscriptionInvoicePdf(profileId: ID!, invoiceId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `invoiceId` | `ID!` |  |

### clientBillingSubscription

Requires: scope `subscriptions:read`.

```graphql
clientBillingSubscription(profileId: ID!): ClientBillingSubscription
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

## Mutations

### createProfileSubscriptionSetupIntent

Requires: scope `subscriptions:write`.

```graphql
createProfileSubscriptionSetupIntent(profileId: ID!): ProfileSubscriptionSetup!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### cancelProfileSubscription

Requires: scope `subscriptions:write`.

```graphql
cancelProfileSubscription(profileId: ID!): ProfileSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### createBookkeeperSubscriptionSetupIntent

Requires: scope `subscriptions:write`.

```graphql
createBookkeeperSubscriptionSetupIntent(bookkeeperId: ID!): BookkeeperSubscriptionSetup!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |

### cancelBookkeeperSubscription

Requires: scope `subscriptions:write`.

```graphql
cancelBookkeeperSubscription(bookkeeperId: ID!): BookkeeperSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |

### assignClientSubscription

Requires: scope `subscriptions:write`.

```graphql
assignClientSubscription(bookkeeperId: ID!, profileId: ID!, planId: ID!, input: AssignClientSubscriptionInput): ClientBillingSubscriptionSetup!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |
| `planId` | `ID!` |  |
| `input` | `AssignClientSubscriptionInput` |  |

### cancelClientBillingSubscription

Requires: scope `subscriptions:write`.

```graphql
cancelClientBillingSubscription(profileId: ID!): ClientBillingSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### cancelBookkeeperClientSubscription

Requires: scope `subscriptions:write`.

```graphql
cancelBookkeeperClientSubscription(bookkeeperId: ID!, profileId: ID!): ClientBillingSubscription!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |


---

<!-- /reference/graphql/tax -->
# Tax

GraphQL operations: tax.

## Queries

### hmrcVatReturn

Requires: scope `tax:read` · feature `hmrc_mtd`.

```graphql
hmrcVatReturn(profileId: ID!, periodKey: String!, fraudPrevention: HmrcFraudPreventionInput): HmrcVatReturnView!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `periodKey` | `String!` |  |
| `fraudPrevention` | `HmrcFraudPreventionInput` |  |

### profileTaxObligationMeters

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
profileTaxObligationMeters(profileId: ID!): TaxObligationMetersPayload!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |

### taxFilingAttachment

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingAttachment(id: ID!): TaxFilingAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### taxObligation

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxObligation(id: ID!): TaxObligation!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### taxObligations

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxObligations(paging: CursorPaging!, filter: TaxObligationFilter!, sorting: [TaxObligationSort!]!): TaxObligationConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `TaxObligationFilter!` | Specify to filter the records returned. |
| `sorting` | `[TaxObligationSort!]!` | Specify to sort results. |

### nlWageTaxObligationSettings

Requires: scope `tax:read` · feature `payroll`.

```graphql
nlWageTaxObligationSettings(paging: CursorPaging!, filter: NlWageTaxObligationSettingsFilter!, sorting: [NlWageTaxObligationSettingsSort!]!): NlWageTaxObligationSettingsConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `NlWageTaxObligationSettingsFilter!` | Specify to filter the records returned. |
| `sorting` | `[NlWageTaxObligationSettingsSort!]!` | Specify to sort results. |

### taxFilingOverview

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingOverview(profileId: ID!, year: Int!): TaxFilingOverview!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `year` | `Int!` |  |

### taxFilingMultiYearOverview

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingMultiYearOverview(profileId: ID!, fromYear: Int!, toYear: Int!): TaxFilingMultiYearOverview!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `fromYear` | `Int!` |  |
| `toYear` | `Int!` |  |

### periodTaxFilingsDue

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
periodTaxFilingsDue(periodId: ID!): [PeriodTaxFilingDue!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `periodId` | `ID!` |  |

### taxFilingPaymentSummary

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingPaymentSummary(filingId: ID!): TaxFilingPaymentSummary!
```

| Argument | Type |  |
| --- | --- | --- |
| `filingId` | `ID!` |  |

### computedTaxFilingVatData

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
computedTaxFilingVatData(filingId: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `filingId` | `ID!` |  |

### taxFilingPdfData

The filing rendered as a PDF, base64. The same document as the REST download, for callers (embedded components) that only speak GraphQL.

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingPdfData(id: ID!): String!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### taxFilingSubmitPreview

What would happen if this filing were submitted now, for the current actor.

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingSubmitPreview(id: ID!): TaxFilingSubmitPreview!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### tAXFiling

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
tAXFiling(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### tAXFilings

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
tAXFilings(paging: CursorPaging!, filter: TAXFilingFilter!, sorting: [TAXFilingSort!]!): TAXFilingConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `TAXFilingFilter!` | Specify to filter the records returned. |
| `sorting` | `[TAXFilingSort!]!` | Specify to sort results. |

### taxFilingPaymentRequests

Requires: scope `tax:read` · feature `tax_filings`.

```graphql
taxFilingPaymentRequests(profileId: ID!, taxFilingId: ID!): [PaymentRequest!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `taxFilingId` | `ID!` |  |

## Mutations

### endTaxObligation

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
endTaxObligation(id: ID!, endsAt: DateTime!): TaxObligation!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `endsAt` | `DateTime!` |  |

### createOneTaxFilingAttachment

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createOneTaxFilingAttachment(taxFilingId: ID!, input: CreateTaxFilingAttachmentInput!): TaxFilingAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `taxFilingId` | `ID!` |  |
| `input` | `CreateTaxFilingAttachmentInput!` |  |

### deleteOneTaxFilingAttachment

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteOneTaxFilingAttachment(input: DeleteOneTaxFilingAttachmentInput!): TaxFilingAttachment!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneTaxFilingAttachmentInput!` |  |

### createOneTaxObligation

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createOneTaxObligation(profileId: ID!, input: CreateTaxObligationInput!): TaxObligation!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateTaxObligationInput!` |  |

### createManyTaxObligations

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createManyTaxObligations(profileId: ID!, input: [CreateTaxObligationInput!]!): [TaxObligation!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateTaxObligationInput!]!` |  |

### updateOneTaxObligation

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateOneTaxObligation(input: UpdateOneTaxObligationInput!): TaxObligation!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneTaxObligationInput!` |  |

### updateManyTaxObligations

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateManyTaxObligations(input: UpdateManyTaxObligationsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyTaxObligationsInput!` |  |

### deleteOneTaxObligation

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteOneTaxObligation(input: DeleteOneTaxObligationInput!): TaxObligationDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneTaxObligationInput!` |  |

### deleteManyTaxObligations

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteManyTaxObligations(input: DeleteManyTaxObligationsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyTaxObligationsInput!` |  |

### createOneNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
createOneNlWageTaxObligationSettings(profileId: ID!, input: CreateNlWageTaxObligationSettingsInput!): NlWageTaxObligationSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateNlWageTaxObligationSettingsInput!` |  |

### createManyNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
createManyNlWageTaxObligationSettings(profileId: ID!, input: [CreateNlWageTaxObligationSettingsInput!]!): [NlWageTaxObligationSettings!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateNlWageTaxObligationSettingsInput!]!` |  |

### updateOneNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
updateOneNlWageTaxObligationSettings(input: UpdateOneNlWageTaxObligationSettingsInput!): NlWageTaxObligationSettings!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneNlWageTaxObligationSettingsInput!` |  |

### updateManyNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
updateManyNlWageTaxObligationSettings(input: UpdateManyNlWageTaxObligationSettingsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyNlWageTaxObligationSettingsInput!` |  |

### deleteOneNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
deleteOneNlWageTaxObligationSettings(input: DeleteOneNlWageTaxObligationSettingsInput!): NlWageTaxObligationSettingsDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneNlWageTaxObligationSettingsInput!` |  |

### deleteManyNlWageTaxObligationSettings

Requires: scope `tax:write` · feature `payroll`.

```graphql
deleteManyNlWageTaxObligationSettings(input: DeleteManyNlWageTaxObligationSettingsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyNlWageTaxObligationSettingsInput!` |  |

### createTaxFilingDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingDraft(obligationId: ID!, from: DateTime!, to: DateTime!, manual: Boolean, asReturn: Boolean): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `from` | `DateTime!` |  |
| `to` | `DateTime!` |  |
| `manual` | `Boolean` |  |
| `asReturn` | `Boolean` |  |

### updateTaxFilingCitData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingCitData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingUsCitData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingUsCitData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### refreshTaxFilingUsCitFromLedger

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
refreshTaxFilingUsCitFromLedger(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### refreshTaxFilingCitFromLedger

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
refreshTaxFilingCitFromLedger(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### updateTaxFilingKvkData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingKvkData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### refreshTaxFilingKvkFromLedger

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
refreshTaxFilingKvkFromLedger(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### updateTaxFilingVatData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingVatData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingIcpData

Save hand-typed ICP supplies on a manual ICP draft (filings-only clients).

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingIcpData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingOssData

Save hand-typed OSS lines on a manual OSS draft (filings-only clients).

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingOssData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingLateInvoices

Re-check late invoices from filed periods on a draft VAT return and include the given ones (all within the correction threshold when omitted).

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingLateInvoices(id: ID!, invoiceIds: [String!]): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `invoiceIds` | `[String!]` |  |

### updateTaxFilingWageTaxData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingWageTaxData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### recordTaxFilingManually

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
recordTaxFilingManually(id: ID!, data: String, bookedAt: DateTime): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String` |  |
| `bookedAt` | `DateTime` |  |

### updateTaxFilingBookedAt

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingBookedAt(id: ID!, bookedAt: DateTime!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `bookedAt` | `DateTime!` |  |

### createTaxFilingSuppletieDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingSuppletieDraft(correctsFilingId: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `correctsFilingId` | `ID!` |  |

### createTaxFilingSuppletieForPeriod

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingSuppletieForPeriod(obligationId: ID!, from: DateTime!, to: DateTime!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `from` | `DateTime!` |  |
| `to` | `DateTime!` |  |

### createTaxFilingUitstelDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingUitstelDraft(obligationId: ID!, from: DateTime!, to: DateTime!, data: String): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `from` | `DateTime!` |  |
| `to` | `DateTime!` |  |
| `data` | `String` |  |

### createTaxFilingBezwaarDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingBezwaarDraft(obligationId: ID!, data: String): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `data` | `String` |  |

### createTaxFilingEuVatRefundDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingEuVatRefundDraft(obligationId: ID!, data: String): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `data` | `String` |  |

### createTaxFilingVoorlopigeAanslagDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingVoorlopigeAanslagDraft(obligationId: ID!, from: DateTime!, to: DateTime!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `obligationId` | `ID!` |  |
| `from` | `DateTime!` |  |
| `to` | `DateTime!` |  |
| `data` | `String!` |  |

### updateTaxFilingVoorlopigeAanslagData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingVoorlopigeAanslagData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingUitstelData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingUitstelData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingBezwaarData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingBezwaarData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### updateTaxFilingEuVatRefundData

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateTaxFilingEuVatRefundData(id: ID!, data: String!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `data` | `String!` |  |

### markTaxFilingReady

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
markTaxFilingReady(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### approveTaxFiling

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
approveTaxFiling(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### markTaxFilingDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
markTaxFilingDraft(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### reopenRejectedTaxFiling

Move a rejected or failed filing back to draft so it can be corrected and submitted again. The previous delivery is kept.

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
reopenRejectedTaxFiling(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### submitTaxFiling

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
submitTaxFiling(id: ID!, finalised: Boolean, fraudPrevention: HmrcFraudPreventionInput): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `finalised` | `Boolean` |  |
| `fraudPrevention` | `HmrcFraudPreventionInput` |  |

### deleteTaxFilingDraft

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteTaxFilingDraft(id: ID!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### initiateTaxFilingPayment

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
initiateTaxFilingPayment(id: ID!, returnPath: String, returnTarget: TaxPaymentReturnTarget): TaxFilingPaymentInitiation!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |
| `returnPath` | `String` |  |
| `returnTarget` | `TaxPaymentReturnTarget` | `embed`: the payment page returns to the embedded components (popup callback on the embed origin); returnPath is ignored. |

### refreshTaxFilingPayment

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
refreshTaxFilingPayment(id: ID!): TaxAuthorityPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` |  |

### refreshTaxFilingPaymentByKenmerk

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
refreshTaxFilingPaymentByKenmerk(kenmerk: String): TaxAuthorityPayment!
```

| Argument | Type |  |
| --- | --- | --- |
| `kenmerk` | `String` |  |

### createOneTAXFiling

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createOneTAXFiling(profileId: ID!, input: CreateTAXFilingInput!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateTAXFilingInput!` |  |

### createManyTAXFilings

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createManyTAXFilings(profileId: ID!, input: [CreateTAXFilingInput!]!): [TAXFiling!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateTAXFilingInput!]!` |  |

### updateOneTAXFiling

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateOneTAXFiling(input: UpdateOneTAXFilingInput!): TAXFiling!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneTAXFilingInput!` |  |

### updateManyTAXFilings

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
updateManyTAXFilings(input: UpdateManyTAXFilingsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyTAXFilingsInput!` |  |

### deleteOneTAXFiling

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteOneTAXFiling(input: DeleteOneTAXFilingInput!): TAXFilingDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneTAXFilingInput!` |  |

### deleteManyTAXFilings

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
deleteManyTAXFilings(input: DeleteManyTAXFilingsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyTAXFilingsInput!` |  |

### createTaxFilingPaymentRequest

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
createTaxFilingPaymentRequest(profileId: ID!, taxFilingId: ID!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `taxFilingId` | `ID!` |  |

### reportTaxFilingPaymentRequestStatus

Requires: scope `tax:write` · feature `tax_filings`.

```graphql
reportTaxFilingPaymentRequestStatus(profileId: ID!, input: ReportPaymentRequestStatusInput!): PaymentRequest!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `ReportPaymentRequestStatusInput!` |  |


---

<!-- /reference/graphql/vehicles -->
# Vehicles

GraphQL operations: vehicles.

## Queries

### vehicle

Requires: scope `vehicles:read` · feature `vehicles`.

```graphql
vehicle(id: ID!): Vehicle!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### vehicles

Requires: scope `vehicles:read` · feature `vehicles`.

```graphql
vehicles(paging: CursorPaging!, filter: VehicleFilter!, sorting: [VehicleSort!]!): VehicleConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `VehicleFilter!` | Specify to filter the records returned. |
| `sorting` | `[VehicleSort!]!` | Specify to sort results. |

### vehicleTrip

Requires: scope `vehicles:read` · feature `vehicles`.

```graphql
vehicleTrip(id: ID!): VehicleTrip!
```

| Argument | Type |  |
| --- | --- | --- |
| `id` | `ID!` | The id of the record to find. |

### vehicleTrips

Requires: scope `vehicles:read` · feature `vehicles`.

```graphql
vehicleTrips(paging: CursorPaging!, filter: VehicleTripFilter!, sorting: [VehicleTripSort!]!): VehicleTripConnection!
```

| Argument | Type |  |
| --- | --- | --- |
| `paging` | `CursorPaging!` | Limit or page results. |
| `filter` | `VehicleTripFilter!` | Specify to filter the records returned. |
| `sorting` | `[VehicleTripSort!]!` | Specify to sort results. |

## Mutations

### createOneVehicle

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
createOneVehicle(profileId: ID!, input: CreateVehicleInput!): Vehicle!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `CreateVehicleInput!` |  |

### createManyVehicles

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
createManyVehicles(profileId: ID!, input: [CreateVehicleInput!]!): [Vehicle!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `profileId` | `ID!` |  |
| `input` | `[CreateVehicleInput!]!` |  |

### createOneVehicleTrip

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
createOneVehicleTrip(vehicleId: ID!, input: CreateVehicleTripInput!): VehicleTrip!
```

| Argument | Type |  |
| --- | --- | --- |
| `vehicleId` | `ID!` |  |
| `input` | `CreateVehicleTripInput!` |  |

### createManyVehicleTrips

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
createManyVehicleTrips(vehicleId: ID!, input: [CreateVehicleTripInput!]!): [VehicleTrip!]!
```

| Argument | Type |  |
| --- | --- | --- |
| `vehicleId` | `ID!` |  |
| `input` | `[CreateVehicleTripInput!]!` |  |

### updateOneVehicle

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
updateOneVehicle(input: UpdateOneVehicleInput!): Vehicle!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneVehicleInput!` |  |

### updateManyVehicles

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
updateManyVehicles(input: UpdateManyVehiclesInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyVehiclesInput!` |  |

### deleteOneVehicle

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
deleteOneVehicle(input: DeleteOneVehicleInput!): VehicleDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneVehicleInput!` |  |

### deleteManyVehicles

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
deleteManyVehicles(input: DeleteManyVehiclesInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyVehiclesInput!` |  |

### updateOneVehicleTrip

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
updateOneVehicleTrip(input: UpdateOneVehicleTripInput!): VehicleTrip!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateOneVehicleTripInput!` |  |

### updateManyVehicleTrips

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
updateManyVehicleTrips(input: UpdateManyVehicleTripsInput!): UpdateManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `UpdateManyVehicleTripsInput!` |  |

### deleteOneVehicleTrip

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
deleteOneVehicleTrip(input: DeleteOneVehicleTripInput!): VehicleTripDeleteResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteOneVehicleTripInput!` |  |

### deleteManyVehicleTrips

Requires: scope `vehicles:write` · feature `vehicles`.

```graphql
deleteManyVehicleTrips(input: DeleteManyVehicleTripsInput!): DeleteManyResponse!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `DeleteManyVehicleTripsInput!` |  |


---

<!-- /reference/graphql/work-sessions -->
# Work sessions

GraphQL operations: work sessions.

## Mutations

### endProfileWorkSession

Requires: scope `work_sessions:write`.

```graphql
endProfileWorkSession(bookkeeperId: ID!, profileId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `profileId` | `ID!` |  |

### createManualProfileWorkSession

Requires: scope `work_sessions:write`.

```graphql
createManualProfileWorkSession(input: CreateManualProfileWorkSessionInput!): ProfileWorkSession!
```

| Argument | Type |  |
| --- | --- | --- |
| `input` | `CreateManualProfileWorkSessionInput!` |  |

### updateManualProfileWorkSession

Requires: scope `work_sessions:write`.

```graphql
updateManualProfileWorkSession(bookkeeperId: ID!, sessionId: ID!, input: UpdateManualProfileWorkSessionInput!): ProfileWorkSession!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `sessionId` | `ID!` |  |
| `input` | `UpdateManualProfileWorkSessionInput!` |  |

### deleteManualProfileWorkSession

Requires: scope `work_sessions:write`.

```graphql
deleteManualProfileWorkSession(bookkeeperId: ID!, sessionId: ID!): Boolean!
```

| Argument | Type |  |
| --- | --- | --- |
| `bookkeeperId` | `ID!` |  |
| `sessionId` | `ID!` |  |


---

<!-- /security -->
# Security and compliance

How FinBaze for Platforms is built to be safe to embed: architecture, EU residency, sub-processors, DPA, testing and certification status.

This page is for the security and vendor-risk review of a bank or platform that wants to embed FinBaze. It states what is in place, and says plainly what is not yet. Nothing here is a claim of a certification FinBaze does not hold.

## At a glance

|  |  |
| --- | --- |
| **Where the data lives** | In France, within the European Union (see [EU residency](#eu-residency)). |
| **Certification** | None yet. ISO 27001 and SOC 2 readiness is in progress (see [Certification status](#certification-status)). |
| **Penetration test** | An independent test of the embed and token surfaces is planned in this release; there is no report to publish yet (see [Testing](#testing)). |
| **Sub-processors** | [Listed here](/security/sub-processors), generated from the published privacy policy. |
| **DPA** | FinBaze acts as processor for the platform's company data under a [data processing agreement](https://finbaze.com/privacy/dpa). |
| **Status page** | Linked here once it is public. |

## Architecture

- **Tokens never reach your page.** Components run in iframes on FinBaze's origin; the embed token stays in a hidden controller iframe and moves over private message ports. See the [embed security model](/concepts/embed-security-model).
- **Single-use client secrets.** A secret works once, for 15 minutes.
- **Origin allowlist.** Components render only on the origins you register; sandbox and live origins are separate.
- **Allowlisted operations.** An embed token can run only the GraphQL operations FinBaze ships for the components in its session, for the one company it was created for. Arbitrary queries and introspection are refused.
- **Least privilege keys.** Server keys can be restricted to scopes. Key management is portal-only, so a leaked key cannot mint keys. Keys are shown once and stored hashed.
- **Tenant isolation.** Every operation reachable with a platform token is classified, and operations that take an id check that the caller can reach the company that owns it. Another platform's object is a 404, never a 403. A tenant-isolation test suite is being added to CI as a required check in this release.
- **Consent before filing.** FinBaze files for a platform company only with the authorisation of the company's own admin, recorded with the statement version and hash ([Filing consent](/concepts/filing-consent)).
- **Step-up for high-risk actions.** Your own strong customer authentication confirms them ([Delegated actions](/concepts/delegated-actions#step-up)).
- **Audit.** Every change through an embed is recorded as "*user* via *platform*"; platforms read their companies' audit log ([Lifecycle](/guides/lifecycle-and-migration#audit)). FinBaze support sees a company only with its admin's consent. The one exception is break-glass access for a legal order or a security incident: a second FinBaze admin must approve, it is read only, lasts two hours at most, and you receive `support.break_glass` when it starts ([Support and view-as](/concepts/support-and-view-as#break-glass)).
- **Webhooks.** Signed with HMAC-SHA256 and a timestamp, secrets rotate without a gap, endpoints are checked against unsafe URLs ([Webhook events](/reference/webhook-events)).
- **No analytics in the components.** The embed app, the component library and the browser SDK load no analytics, session replay or advertising scripts. This is checked in CI.

## EU residency

Production data is hosted in France, within the European Union, on machines owned by OVH. The hosting service is provided by Auric (see the [sub-processor list](/security/sub-processors)). Data is encrypted in transit and at rest, access is role-based and logged, and personnel access is restricted. The encryption and access statements come from FinBaze's published [privacy policy](https://finbaze.com/privacy) and DPA; this page repeats them. The statement about who owns the machines and who provides the hosting service is added here.

Some functions use providers outside the EU (for example AI features and sign-in). The list shows each one and its purpose, and the DPA describes the transfer mechanisms. Platform companies never reach FinBaze's push provider: FinBaze sends push only to its own app for direct customers ([Messages](/concepts/messages#push-notifications-and-the-expo-sub-processor)).

## Backups and recovery

The privacy policy states that backups are kept for up to three years, access-restricted and used for continuity and recovery. Scheduled backups with a tested restore, and a disaster-recovery plan with recovery point and time objectives, are part of the security work of this release; the objectives are published here when they are approved.

## Sub-processors and the DPA

The [sub-processor list](/security/sub-processors) is generated from the privacy policy the DPA incorporates, so it cannot differ from it. FinBaze gives reasonable advance notice of a material new sub-processor and customers may object within 15 days on data-protection grounds (DPA, section 6).

## Testing

| Test | Status |
| --- | --- |
| Automated: access audit of every platform operation, operation manifest check, secrets scan in CI | In place |
| Tenant-isolation suite as a required CI check | Being added in this release |
| Independent penetration test of the embed and token surfaces, with a retest letter | Planned; a summary is published here when the report and the retest letter exist |
| Dependency and container scanning in CI | Being added in this release |

## Certification status

FinBaze does **not** currently hold an ISO 27001 certificate or a SOC 2 report. Readiness work for both has started: a gap assessment, a statement of applicability and a dated plan. When a certificate or a report exists it appears here, with its scope and date. Until then, a vendor-risk team can ask for the security questionnaire answers and the evidence the readiness work produces: write to [info@finbaze.com](mailto:info@finbaze.com).

## Reporting a vulnerability

Send suspected incidents or vulnerabilities to [info@finbaze.com](mailto:info@finbaze.com). Include the `X-Request-Id` of a request when you have one.


---

<!-- /security/sub-processors -->
# Sub-processors

The providers and recipients FinBaze uses, generated from the published privacy policy.

Generated from FinBaze's published [privacy policy](https://finbaze.com/privacy), version 2026-10-10 (last updated 10 October 2026), which the [data processing agreement](https://finbaze.com/privacy/dpa) incorporates. This page cannot differ from it.

| Provider or recipient | Purpose and location |
| --- | --- |
| Aurtic and related infrastructure | Hosting, databases, email delivery, infrastructure and access logging in France / the European Union |
| Anthropic | AI-assisted features |
| OpenAI | AI-assisted features |
| Google | AI-assisted features |
| Amazon | AI-assisted features |
| TypeSafe | AI-assisted features |
| Lunch Flow | Open banking and bank-transaction synchronisation |
| Bird / MessageBird | WhatsApp delivery; Bird is configured by FinBaze not to retain message content |
| Stripe | Subscription payments, connected payment functionality and billing |
| Gotenberg (self-hosted) | PDF generation |
| Digipoort and Belastingdienst | Dutch tax submissions and related responses |
| Kamer van Koophandel (KvK) | Dutch company-information lookups |
| Google Analytics (Google Ireland Limited / Google LLC) | Usage measurement for the FinBaze marketing website and bookkeeping platform (web) |
| Microsoft Clarity (Microsoft Ireland Operations Limited / Microsoft Corporation) | Usage measurement, heatmaps and session recordings for the FinBaze marketing website, bookkeeping platform (web) and mobile applications |
| Google | Sign-in, maps and calendar functionality |
| Google (Workspace APIs, including Gmail) | Read-only access to a mailbox the customer connects. FinBaze monitors only for invoice-related keywords and discards any other email without storing its content. Google Workspace API user data is strictly excluded from being used to train or improve FinBaze's in-house generalized AI/ML models. Use of this data adheres to the [Google User Data Policy](https://developers.google.com/terms/api-services-user-data-policy), including the Limited Use requirements |
| Apple | Sign-in functionality |
| Customer-enabled payment providers and shops | Integrations enabled and instructed by the customer |
| Customer-selected email providers | Delivery through email infrastructure configured by the customer |
| Professional advisers, authorities and courts | Advice, legal claims and compliance with lawful requirements |

Some recipients, such as government bodies or customer-selected integration providers, may act as independent controllers. A material new sub-processor is announced in advance and customers may object within 15 days on data-protection grounds (DPA, section 6).

Which of these apply to a platform company: the embedded components (embed app, component library, browser SDK) load no analytics, session replay or advertising script. Platform companies never reach FinBaze's push provider ([Messages](/concepts/messages#push-notifications-and-the-expo-sub-processor)).


---

<!-- /changelog -->
# Changelog

Changes to the platform API, the SDKs and these docs.

Every change to the GraphQL schema gets an entry here. Add a file `content/changelog/YYYY-MM-DD-<slug>.md`; CI fails a pull request that changes `schema.gql` without one.

## 2026-11-02: filing consent (Wave 5.1)

- **FinBaze files only with consent.** For a platform company the company's own user authorises FinBaze to file each tax (`AuthorisedTax`: `nl_vat`, `nl_icp`, `nl_oss`, `nl_cit`, `nl_annual_accounts`, `nl_wage_tax`, `nl_pension`, `uk_vat`, `uk_income_tax`). A submit without it fails with `TAX_AUTHORISATION_REQUIRED`. See [Filing consent](/concepts/filing-consent).
- **New operations.** `taxAuthorisationStatement(companyId, taxes, locale)`, `taxAuthorisationStatus(companyId)`, `taxAuthorisations(companyId, includeRevoked)`, `grantTaxAuthorisation(input)` and `revokeTaxAuthorisation(input)`. **Granting is for embed and headless tokens only**: a server token or a user token minted by your backend gets `FORBIDDEN_TOKEN_TYPE`. The session needs the `onboarding` or `tax-authorisation` component and an admin of the company. Revoking also works with your server token and is effective on the next request.
- **Hash of the displayed text.** `grantTaxAuthorisation` takes the `statementVersion` and `statementHash` of the statement that was shown; a different text is `TAX_AUTHORISATION_STATEMENT_OUTDATED`. A tax the company has no obligation for is `TAX_NOT_REGISTERED`.
- **Requirements and events.** `onboardingRequirements` gains `tax_<tax>_authorisation` (`currently_due` while a tax is `missing` or `reconfirmation_due`). New events `tax_authorisation.granted`, `tax_authorisation.revoked` (`{ companyId, taxes, channel, stepUp, at }`, no IP or user agent) and `company.requirements.updated`, now available. Message type `tax_authorisation.revoked` for your message routing.
- **Step-up.** The `step_up` provider accepts the action `tax_authorisation.grant`.
- **Components.** `onboarding` has a "Filing authorisation" step (`features.filingConsent`); `tax-authorisation` shows the status per tax, the history, grant and revoke (`features.grant`, `features.revoke`) next to the HMRC connection; `vat-return`, `icp-return` and `oss-return` show a grant panel instead of an error (`features.inlineConsent`) or "Your accountant files this return". Events `tax_authorisation.granted` / `.revoked` carry the webhook payload. Headless: `useTaxAuthorisation()`.
- **SDK.** `platform.taxAuthorisations.list`, `.status`, `.revoke` (no `grant`) and the new events in `PlatformControlEvent`.
- **Portal.** The companies page shows each company's authorisation status and history, read only.

## 2026-11-06: accountants on platform companies (Wave 5.3)

- **Engagements.** A company connects one accounting firm by name: `lookupFirmForConnect` (exact KvK number or connect code, 10 lookups an hour per company), `firmEngagementStatement`, `requestFirmConnection`, `decideFirmConnection`, `updateFirmEngagementAuthority`, `endFirmEngagement`, `companyFirmEngagements`. A firm asks for access with `requestCompanyAccess` (always `true`: it never says whether a company matched); the company approves or declines. New enums `FirmEngagementStatus`, `FirmEngagementOrigin`, `FirmFilingAuthority`, `EngagementSide`; new scopes `platform_firms:read` and `platform_firms:write`.
- **The firm pays nothing** for a platform company: no seat, no filings-only fee, no per-document or AI usage. The firm works the company in the normal dashboard inside its effective features; firm-installed apps and firm API credentials do not reach it.
- **`firm_access` feature key.** Hiding it blocks new connections and gives active ones a notice (default 30 days) before they end (`firm.disconnect_scheduled`, then `firm.disconnected` with `endedBySide: platform`).
- **Events.** `firm.access_requested`, `firm.connection_requested`, `firm.connected`, `firm.connection_declined`, `firm.connection_expired`, `firm.disconnect_scheduled`, `firm.disconnected`, `firm.authority_changed`; messages `firm.access_requested`, `firm.engagement_company_notice` and `firm.engagement_firm_notice`.
- **Component.** `accountant-connect` (session key `accountantConnect`, features `invite`, `approve`, `end`, events `firm.connected` and `firm.disconnected`); `notification-banner` points at pending firm requests. See [Working with accountants](/concepts/working-with-accountants).
- **SDK.** `platform.firms.listEngagements(companyId)` and `platform.firms.end(engagementId, { reason })`.
- `Profile.platformName` and `Bookkeeper.connectCode` (firm admins; `bookkeeperConnectCode`, `rotateBookkeeperConnectCode`). `firmEngagementStatement` is the one `firm…` root field that platform tokens may call.

## 2026-11-03: sandbox tools (Wave 5.5)

Sandbox only; production answers `SANDBOX_ONLY`.

- **Test clocks.** `createTestClock`, `advanceTestClock`, `deleteTestClock`, `testClocks`; `createPlatformCompany` takes `testClockId`. Events `test_clock.ready` and `test_clock.failed` carry `testClockTime`.
- **Demo companies.** `seedTestCompany` with five templates; magic KvK and Companies House numbers `00000001`, `00000002`, `99999999`.
- **Reset.** `platformSandboxSettings`, `updatePlatformSandboxSettings` (`sandboxReset`: `none` or `nightly`, `sandboxSeedTemplates`), `resetPlatformSandbox`, event `sandbox.reset.completed`.

## 2026-10-31: documents, part 2 (Wave 4.3/4.4)

- **Presets travel with the `documents` policy.** The sandbox bundle carries your active layout presets; confirming the import in production makes them the active versions there (earlier versions are archived, companies follow the new one).
- **Quote, reminder, payslip and jaaropgaaf.** Templates and partner rendering now cover them (`setPlatformDocumentRenderSetting` accepts `quote`, `reminder`, `payslip`, `year_document` in `partner` mode). Their data models never contain the BSN; `documentDataModelSchema` publishes them. A partner payslip must show employer, employee, period, gross, wage tax withheld and the amount payable; a jaaropgaaf employer, employee, year, wage and withholding, or FinBaze falls back to its own layout (`document.render_rejected`).
- **Large PDFs.** `POST /v2/platform/documents/uploads` (`application/pdf`) answers an `uploadId`, valid an hour and usable once: `attachRenderedDocument(jobId, uploadId)`. `pdfBase64` stays for small files.
- **UBL link.** `document.render_requested` carries `attachments` with a signed link (15 minutes) to the invoice's UBL.
- **Company fonts.** `POST|GET|DELETE /v2/profiles/:profileId/fonts` for a company's own WOFF2 brand fonts.

## 2026-10-30: delegated actions (Wave 4.5)

- **Providers.** `upsertPlatformProvider` declares what you fulfil yourself: `payments`, `payment_links`, `tax_reservation`, `step_up` (and `camera`, embed only), each with its own `config` and `mode` (`webhook`, `embed` or `both`). Registration needs the matching `delegated.*` feature in your allowance, checked again at use. `platformProviders` lists them.
- **Payment requests.** FinBaze asks you to pay: `createTaxPaymentRequest(company, taxFilingId)` for an accepted NL VAT or wage tax filing, `createPaymentRequestFromBatch(company, paymentBatchId)` for supplier and wage batches (lines held or blocked by Risk Guard are left out; a pain.001 file is attached through `pain001Url`). Creditor IBANs are frozen when the request is created; you cannot change them. Put the request's `endToEndId` (or the line's) in the SEPA `EndToEndId`. Events: `payment_request.created`, `payment_request.updated`, `payment_request.paid`.
- **Status.** `reportPaymentRequestStatus` accepts `sent`, `accepted`, `scheduled`, `failed` and `cancelled`; it never accepts `paid`. A request becomes `paid` (or `partially_paid`) only when the bank transaction is matched, by end-to-end id or, for tax, by the 16-digit betalingskenmerk to the Belastingdienst IBAN with the exact amount. `cancelPaymentRequest`, `paymentRequest`, `paymentRequests`.
- **Payment links.** With a `payment_links` provider FinBaze emits `payment_link.requested` for an invoice and waits `waitSeconds`; `providePaymentLink(requestId, url, expiresAt)` stores an `https` link on one of your `allowedHosts`.
- **Tax reservation.** With a `tax_reservation` provider, `tax_reservation.advised` carries what to set aside for the open VAT period; `taxReservationAdvice(company)` lists it and `reportTaxReservation` tells FinBaze what you reserved.
- **Step-up.** When your `step_up` provider lists an action (`tax_filing.submit`, `pay_run.approve`, `bank_details.change`, `payment_request.approve`), a guarded mutation from a user, embed or headless token fails with `STEP_UP_REQUIRED` and a challenge (`stepUpChallenge`, event `step_up.required`). Sign a JWS (`ES256`, `EdDSA` or `RS256`; claims `iss` = your platform id, `aud` = `finbaze`, `sub` = the user's external id, `challenge_id`, `nonce`, `action`, `amr`, `iat`, `exp` within `maxAgeSeconds`) and retry with `FinBaze-Step-Up: <challengeId>.<jws>`. A challenge is single use and lives five minutes.
- **Automatic requests.** A tax payment request is created when an NL VAT or wage tax filing is accepted with an amount due, and a wage request when a pay run batch is created, for platforms with a `payments` provider. Wage tax advice (`nl_wage_tax`) comes from approved and paid pay runs.
- **For your users' components.** `taxFilingPaymentRequests`, `createTaxFilingPaymentRequest` and `reportTaxFilingPaymentRequestStatus` take a `profileId` and work for user and embed tokens (scopes `tax:read` and `tax:write`; embed: the `payment` feature of `vat-return`). `loadFinBaze` takes `onPaymentRequested`, `onStepUp` and `onCameraCapture`; the `vat-return` component shows a Pay button when you set the first.
- **Payment links and invoices.** `PublicSalesInvoice.partnerPaymentUrl` carries your link; the invoice email, the PDF and the public page show it, and `paymentsEnabled` is false for that invoice while `replaceFinbazePsp` is on.
- **Step-up** also covers `createOneRelationBankAccount`, `updateOneRelationBankAccount`, `deleteOneRelationBankAccount` and `createManyRelationBankAccounts` for `bank_details.change`.
- New scopes `platform_payments:read` and `platform_payments:write`; the feature keys `delegated.payment_requests`, `delegated.payment_links`, `delegated.tax_reservation` and `delegated.step_up`.

## 2026-10-30: policies and extensions (Wave 4.6, 4.7)

- **Policies.** One versioned store for how FinBaze behaves for your companies: `category_mapping` (MCC, partner category, counterparty IBAN, description regex → ledger and tax code, applied to bank feed transactions before any AI suggestion), `chart_template`, `booking_rules`, `filing_policy` (deadline reminders as `tax.deadline_upcoming` messages), `roles_mapping`, `company_defaults` (including optional modules), `quotas`, and the `messaging`, `documents` and `extensions` snapshots. `policySchemas` returns a JSON Schema per kind; `createPolicyDraft` validates (`POLICY_INVALID` lists every issue), `activatePolicyVersion` archives the previous version, `platformPolicies` lists versions, `effectivePolicy(kind, companyId)` shows what applies to a company. `setCompanyPolicyOverride` / `clearCompanyPolicyOverride` for the kinds that allow it. Event `policy.activated`.
- **Promotion.** In the sandbox `promotePlatformPolicies` returns a bundle id; in production `previewPolicyImport(bundleId)` verifies the signed bundle and shows what changes per kind, `confirmPolicyImport` activates everything together. Ids that only exist in one environment (a company in a booking rule) are left out and reported as warnings.
- **Quotas.** `quotas.ai.creditsPerCompanyPerMonth` / `documentsPerCompanyPerMonth` with `atLimit: block` (`QUOTA_EXCEEDED`) or `platform_pays`; the first time a company reaches one in a month you get `quota.reached`.
- **Partner roles.** `setPlatformUserAccess` takes `partnerRole` (a role from your `roles_mapping` policy) instead of `role`; `role` is now optional, one of the two is required. Only the role's permission set is applied for now.
- **Custom actions and deep links.** `upsertCustomAction` (placements such as `booking.detail.header`, conditions `hasExternalId` and `customRecordType`), `customActions(placement, contextType, contextId)` resolves what to show, `invokeCustomAction` emits `custom_action.invoked` for webhook delivery. `upsertLinkTemplate` (https, host in your allowed origins; `{externalId}`, `{id}`, `{companyExternalId}`, `{metadata.<key>}`) and `partnerLinks(objectType, objectId)`: a booking made by a flow template links back to its custom record ("Open shipment 48213 in TMS").
- **Custom fields.** `upsertCustomFieldDefinition` (text, number, boolean, date, select, url; at most 50 per entity type; `editableBy`), `setCustomFieldValues` / `customFieldValues` on sales invoices, transactions, relations and projects. Behind the feature `extensions.custom_fields`.
- **Field control.** `setFieldControl` hides, locks or presets a field for your users (`FIELD_LOCKED` on a write); legally required invoice fields cannot be controlled.
- **Slots.** Declarative in the embed iframe: your page sends `finbaze:slots.set` with descriptors for `headerActions`, `rowActions`, `emptyState`, `help` and `paymentButton`; a click arrives as `finbaze:action.invoked` and as `custom_action.invoked` (`invokeSlotItem`).
- **Policies in effect.** Category mapping and booking rules now decide a bank suggestion before learned rules and AI (a policy match carries `autoBook` and `reviewRequired` hints); quotas are checked before AI calls and document processing; `applyChartTemplate(companyId)` adds your chart template's accounts and hides the ones you listed; filing policy `submitRoles` and `dualApproval` are enforced on `submitTaxFiling` (`FILING_SUBMIT_ROLE`, `FILING_APPROVAL_REQUIRED`) with `approveTaxFiling` for the second person, and `autoCreateDrafts` creates drafts for ended periods.
- **Partner roles** now carry their grants and denies as a role of your platform (denies win; nothing beyond what an admin has).
- **Custom fields** show as `customFields` on sales invoices, transactions, relations and projects, and as `custom_fields` in the events of those objects (for fields with `includeInEvents`). Field control is enforced on the create and update mutations of those four objects for your users' tokens.
- Extension queries (`customActions`, `partnerLinks`, `customFieldDefinitions`, `customFieldValues`, `fieldControls`) and `invokeCustomAction` / `invokeSlotItem` also work for user, embed and headless tokens of your companies. All policy and extension operations take an optional `platformId` for the portal.
- New scopes `platform_policies:read|write` and `platform_extensions:read|write`; events `policy.activated`, `quota.reached`, `custom_action.invoked`.

## 2026-10-30: documents (Wave 4.3 and 4.4)

- **Layout presets.** `upsertPlatformDocumentLayout` / `activatePlatformDocumentLayout` / `archivePlatformDocumentLayout` give your companies presets for invoices, quotes and reminders (and chrome layouts for payslips, year documents, loonstaten, annual accounts and reports). `companyEditable` is `none`, `unlocked_blocks` or `full`; `chooseDocumentLayout` lets a company pick one, `availableDocumentLayouts` lists them, `validateDocumentLayout` shows the required-content warnings, `platformDocumentLayoutPreview` renders a sample. Activation fails with `DOCUMENT_LAYOUT_INVALID` when a rule that can block is violated.
- **Brand fonts.** `POST /v2/platform/fonts?family=&weight=&style=&attest=true` with a WOFF2 body (up to 1 MB, 8 per platform); `brandFonts`, `deleteBrandFont`. Fonts are embedded in the PDF, nothing is fetched at render time. Feature `documents.brand_fonts`.
- **Required content.** NL invoice, quote and reminder checks run when a document closes: warnings for direct companies, a refusal (`DOCUMENT_REQUIRED_CONTENT_MISSING`) for platform companies once a rule is signed off by the adviser. Invoices now print "Btw verlegd" for domestic reverse charge, a VAT exemption reference, and separate wording for intra-EU goods and services (these are visible changes on direct invoices too).
- **Official copies.** Closed invoices, sent quotes and reminders keep the PDF that was sent: a layout change no longer rewrites them. `documentArtifacts(entityType, entityId)` lists the copies with a signed link; event `document.official_copy_created`.
- **Custom templates.** `upsertDocumentTemplate`, `validateDocumentTemplate`, `activateDocumentTemplate`, `archiveDocumentTemplate`, `documentTemplatePreview`, `documentDataModelSchema` (JSON Schema of the data model). A logic-less subset (`{{ }}`, `if`, `unless`, `for`, `raw`; filters `t default upcase downcase truncate escape newline_to_br size`), rendered in an isolated renderer without JavaScript or network. Images must be PNG, JPEG or WebP (`asset:<key>`). A template activates only after rendering at least 12 fixtures with the required content. Feature `documents.custom_templates`.
- **Partner-rendered invoices.** `setPlatformDocumentRenderSetting(documentType: invoice, mode: partner)`. On close you get `document.render_requested` with the data model; answer with `POST /v2/platform/documents/render-jobs/:jobId/pdf` (`application/pdf`) or `attachRenderedDocument`. FinBaze checks the PDF (no scripts or attachments, the required content) and stores it as the official copy, or falls back to its own layout (`document.render_rejected`, `document.render_failed`). A late PDF answers 409 `RENDER_JOB_CLOSED`. Feature `documents.partner_rendered`.
- **Custom domains** for public invoice, quote and payment pages: `addPlatformCustomDomain`, `checkPlatformCustomDomain`, `removePlatformCustomDomain`, `platformCustomDomains` (CNAME to `domains.finbaze.com` plus a TXT record), event `custom_domain.status_changed`. Feature `public_pages.custom_domain`.
- New scopes `platform_documents:read|write`, `platform_domains:read|write`.

## 2026-10-30: all messages, sender domains and the notification centre (Wave 4.2)

- **Every mail goes through messages.** Customer and employee correspondence, firm and account mail, notifications, automation and assistant mail are now messages with a routing decision. Lifecycle, billing and internal mail never reach a platform company. New types in `messageCatalogue`: `sales.*` (invoice, payment received and failed, quote, reminder, recurring), `payroll.payslip_available`, `payroll.year_document_available`, `custom.notification`, `custom.automation_email`, `assistant.inbound_reply`, `documents.inbound_unsorted` and the firm types. Platform default is `finbaze_sends` for correspondence (from your own sender domain) and `partner_delivers` for notifications; you can change it unless the catalogue says `platformMayChange: false`.
- **Sender domains.** `createPlatformSenderDomain` returns the DKIM, SPF and DMARC records to publish; `verifyPlatformSenderDomain` checks DNS (FinBaze also re-checks every 10 minutes while pending); `platformSenderDomains`, `disablePlatformSenderDomain`. Mail about your companies is signed with your key and sent from `no-reply@<your domain>`, never "via FinBaze". Without a verified domain, correspondence is routed to you (`partner_delivers`, reason `no_sender_domain`) and replies to inbound mail are dropped. `updatePlatformMessageSettings` takes `brandName`, `brandLogoUrl`, `brandColor` and `supportEmail` for company mail that has no logo or colour of its own.
- **Copy overrides.** `setPlatformMessageCopy` / `clearPlatformMessageCopy` / `platformMessageCopy` replace the push, in-app, email subject, email intro and SMS text per type and locale with plain text and `{{data.field}}` placeholders (checked against the type's fields, HTML refused); `previewPlatformMessageCopy`. Your wording appears in `message.created` and in the notification centre.
- **Notification centre and preferences** (feature `notification_centre`): `myNotifications`, `markNotificationsRead`, `notificationPreferences`, `setNotificationPreference` (account security email cannot be switched off). With routing `finbaze_sends` and `channels: ["in_app"]` your users read FinBaze's inbox in the embedded action centre instead of you building one.
- **Push** for FinBaze's own app (feature `push_notifications`, FinBaze direct only): `registerPushToken` / `unregisterPushToken`. WhatsApp automation actions need the `whatsapp` feature.
- Messages that carry a token in a link (password reset, invites) have the link blanked once they are delivered.

## 2026-10-29: messages (Wave 4.1)

- **Messages.** FinBaze now routes the notifications it used to email to your users (tax deadlines, filings, documents, agents, thresholds) through a message log. For a platform company with `partner_delivers` you receive `message.created` with content variants for push, in-app, email and SMS; critical messages carry `ack_required` and `ack_deadline`. `acknowledgeMessage` / `acknowledgeMessages` confirm delivery, `markMessageRead` records that the user saw it. `platformMessages` lists the log with the routing decision and reason.
- **Unacknowledged.** After the deadline `message.unacknowledged` goes to your endpoints; with `criticalEmailFallback` on, FinBaze emails critical messages itself an hour later.
- **Routing.** `messageCatalogue` lists every message type with its default and what you may change. `setPlatformMessageRouting` / `clearPlatformMessageRouting` choose `finbaze_sends`, `partner_delivers`, `both` or `suppress` per type, category or for all, platform-wide or per company; lifecycle, billing and account-security messages cannot be changed (`ROUTING_NOT_CHANGEABLE`). `platformMessageSettings` / `updatePlatformMessageSettings` set quiet hours, digest hour, acknowledgement timeouts and the email fallback.
- **Resend.** `resendPlatformMessage` sends `message.created` again for a message that was routed to you (a lost webhook). From the developer portal every message operation takes the optional `platformId`, as the feature operations do.
- New scopes `platform_messages:read` and `platform_messages:write`; events `message.created` and `message.unacknowledged`. See [Messages](/concepts/messages) and the [message catalogue](/reference/message-catalogue).

## 2026-10-28: credit notes through the data API, operations status

- **Credit notes.** `upsertSalesInvoice` takes `creditOf: { externalId }` instead of `lines`. It credits that finalised invoice (a draft credit invoice with the lines negated; add `finalise: true` to number and book it). Send either `lines` or `creditOf`, not both. Crediting twice, or crediting a credit note, is refused.
- **Operations status.** `platformOpsStatus` (scope `platform_usage:read`) shows queue depths and oldest-item ages for ingest, events, webhooks, feeds, flows and exports.

## 2026-10-27: reports, documents and exports (Wave 3.5)

- **Reports.** `platformReport(company, input)` for `profit_loss`, `balance_sheet`, `trial_balance`, `vat_position` (with a `taxFilingId`), `cashflow`, `aged_receivables`, `aged_payables`, `kpis`, `general_ledger` and `forecast`; amounts in minor units, `data` is JSON per type. `platformReportDocument` renders `profit_loss`, `balance_sheet`, `cashflow`, `forecast` and the aged reports as XLSX, and the last three as PDF.
- **Documents.** `companyDocument(company, kind, object, params)` for `sales_invoice_pdf`, `sales_invoice_ubl`, `credit_note_pdf`, `quote_pdf`, `reminder_pdf`, `report_pdf`, `report_xlsx` and `xaf`. The result carries a signed `downloadUrl` valid for 15 minutes (`GET /v2/platform/files/{token}`); files are kept for 24 hours. The other kinds answer `UNSUPPORTED_OPERATION` for now.
- **Audit file.** `requestXafExport` writes an Auditfile Financieel 3.2 for a financial year or a period in the background; the run's `document` has the link when it is ready, with the event `export.ready`.
- **Scheduled exports** to your own bucket: `createPlatformExportDestination` (S3 and S3-compatible, or an Azure container SAS; verified by writing a marker; credentials are stored encrypted and never returned), `createPlatformExportSchedule` / `updatePlatformExportSchedule`, `runPlatformExportNow`, `platformExportRun`. Datasets: `journal_lines`, `trial_balance`, `bank_transactions`, `sales_invoices`, `sales_invoice_lines`, `purchase_invoices`, `purchase_invoice_lines`, `relations`, `custom_records`, `record_effects`, as Parquet, CSV or NDJSON. Incremental datasets send only what changed since the last run (`op` is `upsert` or `delete`). Every run ends with `_manifest.json` and then `_SUCCESS`.
- New scopes `reports:read`, `documents:read`, `exports:read`, `exports:write`; events `export.ready` and `export.failed`; the feature `data_export` is part of a platform's allowance.

## 2026-10-26: custom records and flow templates (Wave 3.3)

- **Record types.** `definePlatformRecordType` describes your own objects (a shipment, a job): a JSON Schema for `data`, the states and which moves between them are allowed. A change creates a new version; records keep the version they were last written with. `platformRecordTypes` lists them.
- **Records.** `upsertCustomRecord`, `deleteCustomRecord` (only without bookings), `customRecord`, `customRecords`. Each record keeps its revision, its history of states, the bookings it caused (`effects`) and its flow runs.
- **Flow templates** turn a state change into bookings: YAML or JSON with `{{ interpolation }}` and JSONata expressions (`=`), the steps `upsert_relation`, `upsert_project`, `create_sales_invoice`, `create_purchase_invoice`, `create_journal_entry`, `reverse` and `fail`, and the helpers `$lookup`, `$net`, `$vatRate`, `$date`, `$euCountry`. `saveFlowTemplate`, `testFlowTemplate` (plans what would be booked, writes nothing), `activateFlowTemplate`, `retireFlowTemplate`, `flowTemplates`.
- **Runs.** One transaction per run: any failing step undoes the others and the run is `failed` with the step, code and path; later runs of that record wait until you `retryFlowRun`. A trigger can `rebook` when the data changes in a state it watches. Reversals use what the run recorded, never the current template.
- Events `record.created`, `record.updated`, `record.transitioned`, `flow_run.succeeded`, `flow_run.failed`; scopes `custom_records:read` and `custom_records:write`; the feature `custom_records`.

## 2026-10-25: data sources and bank feeds (Wave 3.2)

- **Data sources.** `registerDataSource`, `updateDataSource`, `retireDataSource`, `attachDataSource` (with `backfillFrom`), `pauseDataSourceAttachment`, `detachDataSource`; queries `dataSources`, `dataSource`, `feedHealth`, `dataSourceFiles`. Sources with `autoAttach` attach to every new company.
- **Feeds.** `upsertFeedBankAccount` (bank, card or PSP accounts; an existing Lunch Flow account with the same IBAN is taken over, keeping its history and processing), `ingestBankTransactions` (max 500 per call; booked only, `PENDING_NOT_BOOKED` otherwise; a changed line is `IMMUTABLE_TRANSACTION` and a correction is a reversal), `reportBankBalances` (checked against the transactions; a mismatch changes nothing in the books and raises `feed.balance_mismatch`), `reportFeedWatermark` (also the heartbeat), `ingestWorkedHours`.
- **Statement files.** `POST /v2/platform/data-sources/{key}/files?format=camt053|camt052|mt940` accepts a file for many companies at once, routed by IBAN. The same booking arriving as camt.052, camt.053 or MT940 is stored once.
- **Feed health** (`healthy`, `delayed`, `gap`, `balance_mismatch`, `stopped`) with events `feed.delayed`, `feed.gap_detected`, `feed.balance_mismatch`, `feed.recovered`, `bank_account.created`, `data_source_file.processed`, `data_source_file.failed` and `data_source.backfill_completed`.
- Bank transactions and accounts a platform delivered are read-only for users (`PARTNER_SOURCED_READ_ONLY`); processing them is not.
- New scopes `data_sources:read` and `data_sources:write`.

## 2026-10-24: return flow (Wave 3.6)

- **`bankTransactionBookings(company, externalIds)`** (max 100) returns what happened to your bank transactions in the books: status (`unbooked`, `suggested`, `booked`, `needs_review`), counterpart, ledger legs, VAT code, receipt status and who booked it. Unknown ids and ids of other companies read as `booking: null`.
- New events `bank_transaction.booked`, `.unbooked`, `.needs_receipt` and `.needs_review`, sent once per real change.

## 2026-10-23: events and webhooks (Wave 3.4)

- **Events.** `platformEventCatalog` lists the event types; `platformEvents` pages through them by an ordered cursor, `platformEvent` reads one. Events carry a snapshot of the object, are tagged with API version `2026-11-01`, and are not published for a module that is hidden or off for the company.
- **Webhook endpoints.** `createPlatformWebhookEndpoint`, `updatePlatformWebhookEndpoint`, `rotatePlatformWebhookSecret` (old secret also signs for a grace period), `deletePlatformWebhookEndpoint`, `pingPlatformWebhookEndpoint`. The signing secret is shown once.
- **Deliveries.** `platformWebhookDeliveries`, `replayPlatformWebhookDelivery`, `replayPlatformWebhookDeliveries`, `resendPlatformEvent`. Failed deliveries retry with backoff (30 s to 24 h, 8 attempts); an endpoint answering 410 or failing persistently is disabled.
- New scopes: `events:read`, `webhooks:read`, `webhooks:write`.

## 2026-10-22: data in (Wave 3)

- **Your ids and metadata.** Relations, products, projects, cost centers, sales and purchase invoices, quotes, journal entries, employees and employments can carry your own `externalId` (unique per company and object type) and up to 50 string `metadata` values. They are never part of the normal create/update inputs.
- **Upserts.** `upsertRelation`, `upsertProduct`, `upsertProject`, `upsertCostCenter`, `upsertSalesInvoice`, `upsertPurchaseInvoice`, `upsertJournalEntry`, `upsertEmployee`, `upsertEmployment` answer `created`, `updated`, `unchanged` or `deleted`. Sending the same data again writes nothing. Invoices stay drafts until `finalise: true`; after that only metadata changes. Employments are created as drafts; the company finalises the terms in FinBaze. Worked hours (`object=worked_hours`) are bulk only for now: drafts can be corrected, approved hours are final. `setObjectMetadata` and `platformObjectByExternalId` complete the set.
- **Bulk jobs.** `POST /v2/platform/bulk-jobs?object=…` takes NDJSON (optionally gzip) with an `Idempotency-Key`, answers 202 and applies the lines in the background. `platformBulkJob`, `platformBulkJobs` and `cancelPlatformBulkJob` report and control it, line by line. New scopes `bulk:read` and `bulk:write`.
- **Payments.** `MonetaryAccountPayment` gains `valueDate`, `endToEndId`, `bankReference` and `details` (read-only in the app; feeds fill them from Wave 3.2).

## 2026-10-22

- **Components.** Nine more views render: `onboarding`, `action-centre`, `transactions`, `transaction-detail`, `purchase-inbox`, `tax-calendar` and the `vat-return`, `icp-return` and `oss-return` overviews. `tax-authorisation` connects UK companies to HMRC in a popup (Dutch companies need no authorisation); `tax-payments` is still a placeholder. `startHmrcOrganisationConnection` takes an optional `redirectTarget` (`web` or `embed`). The `purchase-inbox` upload runs under the component feature `upload`.
- **Embed sessions.** `createEmbedSession`, `exchangeEmbedSession`, `revokeEmbedSession`, `revokeEmbedSessionsForUser`, `embedContext`.
- **Allowed origins and embed settings** for platforms.
- **Booking summaries and onboarding requirements** for components and headless hooks: `bookingSummaries`, `onboardingRequirements`.
- **SDKs.** `@finbaze/embed-js`, `@finbaze/embed-react` (components and `/headless` hooks) and `@finbaze/platform-sdk` 1.0 (built; npm release pending).


---

<!-- /changelog/2026-11-06-company-lifecycle -->
# Company lifecycle, transfers and audit log (Wave 5.4)

Suspend, close, archive and transfer companies, deprovision users and read the audit log.

## 2026-11-06: company lifecycle, transfers and audit log (Wave 5.4)

- **Lifecycle.** `suspendPlatformCompany`, `reactivatePlatformCompany`, `closePlatformCompany`, `reopenPlatformCompany`, `archivePlatformCompany` and `companyClosingChecklist`. `PlatformCompany.lifecycle` reports the state; `platformCompanies` takes `lifecycleStates` and `includeArchived` and hides archived companies by default. Mutations on a non-active company fail with `COMPANY_SUSPENDED`, `COMPANY_CLOSED` or `COMPANY_ARCHIVED`.
- **Transfers.** `companyTransferStatement`, `createCompanyTransfer`, `companyTransfers`, `cancelCompanyTransfer`, `acceptCompanyTransfer` and, for a FinBaze account, `companyTransferClaimPreview` and `claimCompanyTransfer`. New embed element `company-transfer`.
- **Users.** `deprovisionPlatformUser(userId, anonymise)`; a deprovisioned user's tokens fail at once.
- **Audit.** `platformAuditLogs` (scope `audit:read`, admin role, keyset pagination), `requestAuditLogExport` and an `audit_log` export kind. Audit entries now record the token type, IP, user agent, request id, step-up assertion and support grant; new actor kinds `platform` and `support`.
- **Events.** `company.suspended`, `company.reactivated`, `company.closed`, `company.reopened`, `company.archived`, `company.transfer.created`, `company.transfer.cancelled`, `company.transferred_out`, `company.transferred_in` and `platform_user.deprovisioned`, each with a JSON Schema in the catalogue.
- **SDK.** `platform.companies.suspend/reactivate/close/reopen/archive/closingChecklist`, `platform.transfers`, `platform.users.deprovision` and `platform.audit`.


---

<!-- /changelog/2026-11-07-support-and-view-as -->
# Support routing and consented view-as (Wave 5.5)

contact-support, escalations to FinBaze, support access grants and break-glass.

## 2026-11-07: support routing and consented view-as (Wave 5.5)

- **Support settings.** `platformSupportSettings` and `updatePlatformSupportSettings` (`supportMode` `partner_first` or `finbaze_direct`, `supportUrl`, `supportEmail`, `supportEscalationEnabled`). Enum `SupportMode`.
- **Escalations to FinBaze.** `supportEscalations(status, first, after)`, `createSupportEscalation(input)` and `addSupportEscalationComment(escalationId, body)`; enums `SupportSeverity` and `SupportEscalationStatus`. A company user can create one from the embed only when the platform chose `finbaze_direct`.
- **Request ids.** Every response carries `X-Request-Id`; a caller's own id (8 to 64 characters of `A-Z a-z 0-9 . _ -`) is kept and written to the audit log. The header is now exposed to browsers (CORS), so embed errors carry `requestId`.
- **Consented view-as.** FinBaze staff open a platform company only under a support access grant. `supportAccessGrants(companyId, includeEnded)`, `decideSupportAccess(grantId, approve, attestation, stepUpAssertionId)` and `revokeSupportAccess(grantId)`; enums `SupportAccessScope` and `SupportAccessStatus`. Read-only grants refuse every change; filings, consent, firm connections and transfers are refused under any grant. Break-glass needs a second FinBaze admin, lasts two hours and is announced at once.
- **Embed.** New elements `contact-support` (session key `contactSupport`; events `support.requested` and `support.escalation.created`; the SDK opens `supportUrl` when the page has no `support.requested` handler) and `support-access` (session key `supportAccess`; features `decide` and `revoke`; events `support.access.approved`, `.declined`, `.revoked`). `notification-banner` approves or declines a pending support request in place (feature `supportApproval`; events `support.access.approved` and `.declined`). New operations `requestPlatformSupport(companyId, screen, requestIds, componentVersion)` for `partner_first`.
- **Events.** `support.requested`, `support.escalation.created`, `support.escalation.updated`, `support.access_requested`, `support.access_granted`, `support.access_revoked`, `support.access_expired` and `support.break_glass`, each with a JSON Schema in the catalogue.
- **Step-up.** The `step_up` provider accepts the action `support_access.approve`.
- **Scopes.** `support:read` and `support:write`.
- **Audit.** Rows written under a grant have actor kind `support`, the grant id and audience `both`, so they appear in `platformAuditLogs`.
- **SDK.** `platform.support` (settings, escalations, grants) and `platform.sandbox` (test clocks, `seedTestCompany`, `resetSandbox`).

See [Support and view-as](/concepts/support-and-view-as).


---

<!-- /changelog/2026-11-08-access-audit -->
# Access audit (Wave 5)

Every operation reachable by platform tokens is classified; billing hand-over operations are refused, child-id operations check the company.

## 2026-11-08: access audit (Wave 5)

- **No schema change in shape.** `schema.gql` was regenerated from the running API; it now lists the Wave 4 and Wave 5 operations that were missing from the tracked file.
- **Refused for platform tokens.** `subscribeBookkeeper`, `subscribeBookkeeperDeveloperPlan`, `createBookkeeperSubscriptionSetupIntent`, `cancelBookkeeperSubscription`, `createBookkeeperBillingProfile`, `completeBookkeeperClientConnectBilling` and `completeClientOnboardingBilling` answer `Not available for platform tokens`, like every other plan and billing operation. A platform company has no FinBaze plan.
- **Company check on id-only operations.** `projectFinancials`, `recurringFinancials`, `productStock`, `stockAvailability`, the stock document operations (`postStockCount`, `postStockAdjustment`, `postStockTransfer`, `completeAssemblyOrder`, `reopenStockCount`, `reopenStockAdjustment`, `updateStockAdjustment`) and the employee operations `ensureEmployeeRelation` and `setEmployeeNetPayIban` now check that the caller can reach the company that owns the id. An id of another platform's company is a 404, as everywhere else.


---

<!-- /changelog/2026-11-09-mobile-sdks -->
# Mobile SDKs (Wave 6.2)

Register your native apps, create mobile embed sessions, confirm users on the device, and hand a push over to a component.

## 2026-11-09: mobile SDKs (Wave 6.2)

- **Mobile apps.** `platformMobileApps`, `registerPlatformMobileApp(input)` and `removePlatformMobileApp(id)` (scope `platform_embed:read` / `platform_embed:write`, team role admin to change). An app is an iOS bundle id or an Android application id plus the URL scheme it owns; it gets an id `fb_app_…` (`mobileAppId`). Up to 10 per platform and environment; a sandbox app does not exist in production.
- **Mobile sessions.** `createEmbedSession` takes `mobileAppId` (embed sessions only, no `origin`). Such a session is exchanged only by the mobile shell (`https://embed.finbaze.com/v1/m/<component>?app=fb_app_…`), which sends `mobileAppId` to `exchangeEmbedSession`. A web session that names an app, and a mobile session without it, fail with `EMBED_APP_MISMATCH`. Without app attestation the app id is a binding, not proof: the protection is the same as on the web, a single-use client secret that your backend mints for a signed-in user.
- **Device confirmation.** The `step_up` provider takes `stepUpMode: assertion | device_biometric` (default `assertion`, your own signed assertion; `device_biometric` needs no keys). The `STEP_UP_REQUIRED` challenge carries `mode`. In `device_biometric` mode the mobile SDK asks for Face ID or the fingerprint and calls `completeStepUpChallengeWithDeviceAssertion(challengeId)`; the component retries with `FinBaze-Step-Up: <challengeId>.device`. The challenge records `method: device_local`, a weaker signal than your assertion. Banks should keep `assertion`.
- **Push hand-off.** `message.created` carries `action: { type: "open_route", route, component, params, intent, intent_expires_at }` for a message with a deep link. Forward `intent` (opaque, signed, 7 days) in your own push. `resolveEmbedIntent(intent)` (server token) returns the component, company and params before you mint the session; the mobile SDKs call `acknowledgeMessageIntent(id)` once the component is open.
- **New error code** `EMBED_APP_MISMATCH`; new step-up error `STEP_UP_DEVICE_NOT_ALLOWED`.
- **Not available to assistants and agents:** `registerPlatformMobileApp`, `removePlatformMobileApp`, `acknowledgeMessageIntent`, `completeStepUpChallengeWithDeviceAssertion`.


---

<!-- /changelog/2026-11-09-partner-portal -->
# Partner portal (Wave 6.4)

Request ids, the request log, feature explain, data-source health, test events, partner alerts and portal roles.

## 2026-11-09: partner portal (Wave 6.4)

- **Request id on every response.** Every response carries `FinBaze-Request-Id: req_…` (also `X-Request-Id`), every GraphQL error carries `extensions.requestId`, and every server log line of the request carries it. Send your own `FinBaze-Request-Id` (`req_` and 20 to 32 letters or digits) to tie a call to your logs; any other format is replaced.
- **`platformRequestLogs(filter, first, after)`.** The calls of your keys, users and embeds for 30 days: time, request id, token type, operation, company, status, error code, duration. No bodies and no variables. Needs `request_logs:read`; always your own platform. The portal's Logs > Requests page uses it.
- **Find by request id.** `PlatformEventFilter.requestId` and `PlatformDeliveryFilter.requestId` find the events and webhook deliveries a request caused; `PlatformEvent.requestId` and `PlatformWebhookDelivery.requestId` say which request did.
- **`sendPlatformTestEvent(endpointId, type)`.** Posts a signed example event of an available type (`data.test = true`) to an endpoint and returns the answer. Nothing is stored.
- **`platformFeatureExplain(profileId, key)`.** The steps behind a feature key for one of your companies: environment, requires, FinBaze override, platform, allowance, company limit, default limit. Firm overrides are shown as skipped.
- **`platformUsers`** also returns `lastTokenIssuedAt`, `lastAuthenticatedAt`, `tokensRevokedAt` and `deprovisionedAt`; **`revokePlatformUserTokens(userId)`** refuses every token issued to a user so far, keeping the user and their access.
- **`platformOverview`, `platformDataSourceHealth`, `platformAlerts`, `setPlatformDataSourceStatus`, `requestPlatformDataSourceResync`.** Read models for the portal's overview and data-source pages; a resync sends the new event `data_source.resync_requested` (`data.object`: `source`, `from`, `to`) that tells your backend which days to deliver again.
- **Partner alerts and `platform.alert`.** A job every five minutes opens an alert when an endpoint fails 10 deliveries in a row, a feed stalls for an hour, or a filing is rejected. It is sent as the new event `platform.alert` and by email to the owners, admins and developers of your portal. An endpoint without a success for three days is disabled (`disabledReason: failing_for_days`). **Behaviour change:** an endpoint is no longer disabled after 8 consecutive failures; it is disabled after 3 days.
- **Portal roles.** `AccountDeveloper.role` (`owner`, `admin`, `developer`, `support`, `billing`), `platformPortalMembers`, `platformPortalAccess`, `setPlatformPortalRole`. Enforced for portal members only, behind the flag `api.platforms.portal_roles_enforced` (sandbox first). Platform tokens are governed by key scopes, as before. Refused operations answer `PORTAL_ROLE_FORBIDDEN`.
- **New scope** `request_logs:read` (also needed for `platformAlerts`).


---

<!-- /changelog/2026-11-11-portal-records-flows-exports -->
# Portal: record types, flows and exports

Record types, flow templates, flow runs and export destinations and schedules are now available to portal members.

## 2026-11-11: record types, flows and exports in the partner portal

- **Optional `platformId` argument** on `platformRecordTypes`, `definePlatformRecordType`, `flowTemplates`, `saveFlowTemplate`, `activateFlowTemplate`, `retireFlowTemplate`, `testFlowTemplate`, `flowRuns`, `retryFlowRun`, `platformExportDestinations`, `platformExportSchedules`, `platformExportRun`, `createPlatformExportDestination`, `updatePlatformExportDestinationCredentials`, `deletePlatformExportDestination`, `createPlatformExportSchedule`, `updatePlatformExportSchedule` and `runPlatformExportNow`. Server tokens leave it out (the token names the platform; a different id is refused). Members signed in to the partner portal pass it: the portal's Record types, Flows and Exports pages use these operations.
- **Who may call them.** Server tokens with the scope, as before, and now portal members. Portal roles apply (area "data"): support reads, owners, admins and developers also change. User, embed and headless tokens still cannot call them.
- No change for existing integrations: the argument is optional.


---

<!-- /changelog/2026-11-09-sample-apps-and-docs-mcp -->
# Sample apps and docs MCP (Wave 6.5)

bootstrapSampleApp for one-click sample deploys, the docs MCP server, guides, completed references and the agent skill.

## 2026-11-09: sample apps, guides and the docs MCP (Wave 6.5)

- **New mutation `bootstrapSampleApp(sample, webhookUrl)`**, sandbox only (`SANDBOX_ONLY` everywhere else). It creates a restricted test key and a publishable key for a sample app, a webhook endpoint at `webhookUrl` (when given) and the sample's demo company, and returns `{ secretKey, publishableKey, webhookSecret, companyId }`. Keys and the secret are shown once. Portal sign-in only (a key cannot call it); at most 5 per day per developer (`RATE_LIMITED`). A new bootstrap of the same sample revokes that sample's earlier keys and endpoint. See [Sample apps](/guides/sample-apps). `webhookSecret` is `null` when no `webhookUrl` was given.
- **Guides.** Five by partner type ([Banks](/guides/banks), [Point of sale](/guides/pos), [Logistics](/guides/logistics), [E-commerce](/guides/ecommerce), [Scheduling and hours](/guides/scheduling)) and seven by part of FinBaze ([Data sources](/guides/data-sources), [Messages and routing](/guides/messages-and-routing), [Documents](/guides/documents), [Features and limits](/guides/features-and-limits), [Firms](/guides/firms), [Lifecycle and migration](/guides/lifecycle-and-migration), [Mobile](/guides/mobile), the last one marked as planned for Wave 6.2). Every GraphQL block in them is validated against the schema in CI.
- **Sample apps.** `neobank-demo`, `pos-demo`, `tms-demo`, `headless-demo`, `webhook-receivers` (Node, Python, PHP) and `finbaze-embed-examples`, each with an end-to-end script that runs against the sandbox every night.
- **References.** [Errors](/reference/errors) now lists all 158 codes the API can return, grouped by area (a test fails when the API throws a code that is not listed). [Webhook events](/reference/webhook-events) has the envelope, the signature and a sample delivery for every event. [Component props](/components/reference) is generated from the registry. [Versions](/reference/versions) and [Upgrading](/guides/upgrading) explain how versions work and what each release asks of you.
- **Security and compliance.** A [page](/security) for vendor-risk reviews, and the [sub-processor list](/security/sub-processors) generated from the privacy policy.
- **Docs MCP.** `https://mcp.finbaze.com/docs/mcp` is a public, read-only MCP server over these docs, with no sign-in and no session. See [Docs MCP and llms.txt](/sdks/docs-mcp). `llms.txt` now groups pages by section, and there is an [agent skill](/sdks/agent-skill) for integrating the components into a Next.js app.


---

<!-- /changelog/2026-11-10-security-hardening -->
# Security hardening (Wave 6.7)

Account.secret leaves the schema, account reads need a tenant in common, authenticator codes at sign-in.

## 2026-11-10: security hardening (Wave 6.7)

- **`Account.secret` is removed from the schema.** It was a random value written at sign-up that nothing used. The field is gone from `Account`, its filters and sort fields, and from the generated `CreateAccountDto` and `UpdateAccountDto` inputs. A query that selected `secret` on an account now fails validation. (`AccountDevice.secret` and `TotpEnrolment.secret` are unchanged.)
- **Reading an account by id needs a tenant in common.** `account(id)` and relations that end at an account (`createdBy`, `reviewedBy`, ...) return the caller's own account and accounts that share a company, bookkeeper firm or enterprise with the caller. Any other id answers like an unknown one. Platform users see the other users of the same platform company only.
- **Password grant takes `otp`.** `POST /v2/oauth2/token` with `grant_type=password` accepts an optional `otp` (authenticator or recovery code). A valid code puts `otp` in the token's `amr` claim; a wrong code is `invalid_grant`. Without it nothing changes.
- **Schema file.** `apps/api/schema.gql` is regenerated from the running API; two enums changed order, nothing else changed besides the removals above.


---

<!-- /changelog/2026-11-11-tax-payment-instruction -->
# Tax payment instructions

TAXFiling.paymentInstruction for paying a filing by bank transfer, and returnTarget on initiateTaxFilingPayment.

## 2026-11-11: tax payment instructions

- **`TAXFiling.paymentInstruction`** (new, nullable `TaxPaymentInstruction`): how to pay a filing by bank transfer: `creditorName`, `iban`, `bic`, `reference` (the 16-digit betalingskenmerk), `amountMinor` (the open amount after matched payments), `currency` and `dueDate` (last day of the month after the period). Filled for submitted or accepted Dutch VAT and wage tax filings with an amount due; null otherwise, including refunds. The account details come from FinBaze's configuration, never from input. UK VAT returns null for now (HMRC's bank details are not configured yet; pay those through `initiateTaxFilingPayment`). The `ukSortCode` and `ukAccountNumber` fields are reserved for them.
- **`initiateTaxFilingPayment(returnTarget: TaxPaymentReturnTarget = web)`** (new optional argument): `embed` makes the Belastingdienst Internetkassa page return to the embedded components' popup callback instead of the web app; `returnPath` is then ignored. Only for Dutch VAT and wage tax filings, and only where the embedded return URL is registered; otherwise the mutation fails with a clear message. Existing calls are unchanged.


---

<!-- /changelog/2026-11-11-data-out-part-2 -->
# Data out, part 2 (Wave 3.5, 3.6, 4.4)

Every company document kind, report PDFs on the document layout, XAF 4.0 with VAT per line, vat_returns, per-run company filters, and suggestions and review reasons on bookings.

## 2026-11-11: data out, part 2 (Wave 3.5, 3.6, 4.4)

- **All company document kinds.** `companyDocument` now renders `purchase_invoice_original`, `receipt_original` (by bank transaction, `params.documentId` picks one of `booking.receipt.documentIds`), `tax_filing_pdf`, `tax_filing_receipt` (JSON: reference and the authority's status messages, submitted filings only), `annual_accounts_pdf` (`params.financialYear` or a financial year id; the issued version, else a CONCEPT), `payslip_pdf` and `year_document_pdf`, with the same renderers as the FinBaze app. Each needs `data_export` and its module (`purchase_invoices`, `banking`, `tax_filings`, `annual_accounts`, `payroll`); `report_pdf` and `report_xlsx` now also check the report's module, like `platformReport`. A transaction without a receipt answers `NOT_ATTACHED`. `audit_log` answers `UNSUPPORTED_OPERATION` (use `requestAuditLogExport`).
- **Report PDFs on the document layout.** Profit and loss and balance sheet are now available as PDF (`platformReportDocument(format: PDF)`, `report_pdf`). Every report PDF (also cash flow, forecast, aged reports and budgets) is rendered on the company's `report` document layout, your preset or the company's own, like payslips and annual accounts.
- **XAF 4.0.** The audit file is Auditfile Financieel **4.0** by default, validated against the official XSD; `version: "3.2"` (`requestXafExport(version:)`, `params.version` of `companyDocument(kind: xaf)`) still writes 3.2. The Belastingdienst accepts only 4.0 from 1 January 2027. Invoice lines carry their VAT (`vat`) and relation (`custSupID`, the relation id without hyphens), with the codes in `vatCodes` and RGS codes on the ledger accounts. **Behaviour change:** a call without `version` returned 3.2 until now.
- **Exports.** New dataset `vat_returns` (NL and UK VAT returns with their boxes, incremental). `runPlatformExportNow(key, companies)` runs a schedule for some of its companies only; the manifest lists them in `companyFilter`.
- **Return flow.** `PaymentBooking.suggestion` (counterpart, ledger, confidence of FinBaze's pending proposal), `reviewReason` (`policy_review_required`, `awaiting_document`, `amount_difference`, `low_confidence`; the status is then `needs_review` and `bank_transaction.needs_review` is sent), `vatAmountMinor` (the VAT of the invoice the transaction is booked to) and `receipt.documentIds` are filled. `MonetaryAccountPayment.booking` returns the same object on the transaction.
- **Schema.** `MonetaryAccountPayment.booking`, `requestXafExport(version: String)`, `runPlatformExportNow(companies: [CompanyRef!])`, descriptions on `PaymentBooking` and `BookingReceipt`. Nothing removed.


---

<!-- /changelog/2026-11-11-data-in-feeds-quotes-records -->
# Payout, sales and SFTP feeds, quotes, shipped Z-report (Wave 3)

Payouts pair with their bank credit, sales and purchase feeds, SFTP statement pickup, upsertQuote, read-only partner invoices, a shipped z_report type and template, previous.data, records in bulk and in promotions.

## 2026-11-11: payout, sales and SFTP feeds, quotes, shipped Z-report (Wave 3)

- **Payout feeds.** `ingestPayoutTransactions(source, company, account, payouts)` takes up to 500 payouts of a `payout_feed` source onto the company's PSP account (`upsertFeedBankAccount` with `type: psp`). `PayoutFeedInput` carries `payoutDate`, `arrivalDate`, the net `amountMinor` (positive), `grossMinor`, `feesMinor`, the `reference` the bank statement shows, `destination { iban account }`, `status` (`paid`, `in_transit`: not accepted until paid, `PENDING_NOT_BOOKED`) and `reverses` for a payout that failed. Idempotent by `externalId`; a changed payout is `IMMUTABLE_TRANSACTION`. Scope `monetary_accounts:write`.
- **Transfer matcher.** A payout is paired with the credit on one of the company's bank accounts (same amount, around the arrival day, the reference in the statement text or the destination IBAN), whichever arrives first, also when the credit comes through Lunch Flow or a statement file (hourly). Both sides are booked on the suspense ledger, where they cancel out; `bank_transaction.booked` follows as for any booking. `payoutTransferMatches(source, company, payouts)` (`monetary_accounts:read`) lists the pairs with `confidence` and `rationale`.
- **Sales and purchase feeds.** `ingestSalesInvoices` (`sales_feed` source) and `ingestPurchaseInvoices` (`purchase_feed`) take up to 500 invoices with the same fields and rules as `upsertSalesInvoice` and `upsertPurchaseInvoice`; the invoices carry the source.
- **Read-only partner data.** Invoices from a sales or purchase feed and hours from an hours feed are read-only for the company's users, like delivered bank rows: changing the facts (customer, dates, amounts, lines, tax) or deleting answers `PARTNER_SOURCED_READ_ONLY` with the source's name. Processing stays open: ledgers, cost centres and projects on purchase lines, approval, payment and booking. Reopening a delivered sales invoice is refused too; corrections are credit notes from you.
- **SFTP statement pickup.** A source with `delivery: { sftp: true }` accepts camt.053, camt.052 and MT940 files in its folder on the FinBaze SFTP server (`<platform id>/<source key>/`). FinBaze picks them up within a minute, imports them like an upload (`receivedVia: sftp` on `dataSourceFiles`, same dedup and events) and moves them to `processed/<date>/`; a file it cannot take moves to `failed/` with a `.error.txt` beside it. SFTP accounts are set up per platform on request.
- **Quotes.** `upsertQuote(input)` and bulk `object=quotes` (`quotes:write`): draft quotes with your own id, lines as on sales invoices, `expectedTotalMinor` as a guard. Sending stays in FinBaze; a sent quote accepts metadata only and cannot be deleted.
- **Bank detail provenance.** A bank account change through your token (including bulk jobs and flow runs) records your platform; changes by your backend count as `platform_push`.
- **Custom records.** FinBaze ships a `z_report` record type and a `pos-z-report` template (`flowTemplates` lists it as `shipped`). Your own `z_report` type replaces the shipped one; `activateFlowTemplate(key: "pos-z-report", version: 1)` copies the shipped template into your platform and activates the copy, it never runs on its own. Expressions can read `previous.data` (the record's data before the change that started the run) next to `previous.status`; `testFlowTemplate` takes `previousData` per sample record. Records in bulk: `object=custom_records` with lines like `upsertCustomRecord` (`{ company?, externalId, type, status?, data, metadata?, occurredAt? }`, `custom_records:write`). A record pushed without `status` keeps its current state.
- **Promotion.** The sandbox bundle carries a new policy kind `records`: your active record types and flow templates. Confirming the import in production defines the types, saves and activates the templates and retires active templates that are not in the bundle. `PolicyKind` gains `records`.