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.

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.

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

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

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

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#