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 has the full rules.

1. Show the connect component#

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

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

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. 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) 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:

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.