Widget Properties

The tables below list all properties used for embedding Business Health widgets and customizing their behavior — see Embedding Widgets for details on the overall flow.

General Widget Properties apply to every widget. Beyond that, which additional properties are available depends on the widget: the data-display widgets (Accounts, Credit Score, Cash Flow Forecast, and so on) accept the properties under Business Widget Properties, while App Connector, Credit Score Connector, and Insights each have their own — covered in their own sections below.

This page also covers the JavaScript events widgets emit.

General Widget Properties

PROPERTY	TYPE	DESCRIPTION	REQUIRED
`api`	string	Host of the deployed Business Health web application.	Yes
`auth`	object	Authorization parameters — any parameters needed for cross-server integration to identify the current user (session ID, email, etc.). Upon receiving these parameters, the widget sends all the necessary requests and performs authorization. The `auth` and `token` properties are mutually exclusive.	Yes (if authorization is performed by the widget)
`token`	string	JWT token for authorization. Upon receiving the JWT directly from the User Platform, the widget performs authorization without any additional requests. The `token` and `auth` properties are mutually exclusive.	Yes (if authorization is performed by an external app and a token is passed to the widget)
`isDarkTheme`	boolean	If true, dark theme is enabled and the app logos are adjusted accordingly. If false, dark theme is disabled and the regular app logos are used.	No
`locale`	string	Localization of the widget's user interface.	No

Business Widget Properties (Optional)

PROPERTY	TYPE	DESCRIPTION
`showHeaderIcon`	boolean	If true, the icon in the widget's header is shown. If false (default), the icon in the widget's header is hidden.
`name`	string	Text in the widget's header. If empty (default), the widget's default name is displayed.
`hideRefreshDate`	boolean	If true, the data refresh status in the widget's header is hidden. If false (default), the data refresh status in the widget's header is displayed.
`disableapps`	boolean	If true, all buttons leading to the App Connector are hidden. If false (default), all buttons leading to the App Connector are displayed.
`readonly`	boolean	If true, the widget is displayed in read-only mode. If false (default), read-only mode is disabled.
`demo`	boolean	If true, demo mode is enabled, populating the widget with mock data in read-only mode. If false (default), demo mode is disabled.
`introtext`	array of objects	Customizes the title and text on each intro screen — see example below.
`introctatext`	string	Customizes the call-to-action (CTA) label of the intro screens' button.

introtext example — shape: array of {"title": "string", "text": "string", "image": "string"}

[
  {"title": "Title 1", "text": "Text 1", "image": "Image 1"},
  {"title": "Title 2", "text": "Text 2", "image": "Image 2"}
]

App Connector and Credit Score Connector Properties (Optional)

PROPERTY	TYPE	DESCRIPTION
`titleText`	string	Brief text at the top of the App Connector. If empty (default), the title isn't displayed. In Credit Score Connector — sets the Search Screen title.
`subtitleText`	string	Additional text below the title. In Credit Score Connector — sets the Search Screen subtitle. If empty (default), the subtitle isn't displayed.
`hideInvite` (App Connector)	boolean	If true, the Invite button is hidden from the app tiles. If false (default), the Invite button is displayed on the app tiles, allowing users to share the app connection link.
`hideSearchBar` (App Connector)	boolean	If true, the search bar at the top of the App Connector is hidden. If false (default), the search bar is displayed, allowing filtering of apps by title.
`hideFilter` (App Connector)	boolean	If true, the filter bar at the top of the App Connector is hidden. If false (default), the filter bar is displayed, allowing filtering of apps by category.
`poolInstanceId` (App Connector)	uuid	ID of the pool of apps available in the App Connector. If empty (default), the default pool configured in the Admin Panel is used.
`filterParams`	object	IDs of specific app categories (`categoriesIds`) and/or apps (`servicesIds`) to display in the App Connector — see example below. Either array is optional and may be omitted; if both are specified, the App Connector only displays apps matching both criteria.
`hideSecurityBlock`	boolean	Hides the footer with security information. False by default.
`application` (App Connector)	object	Stores the company data — see example below.
`showBackButtonFromAppConnector` (Credit Score Connector)	boolean	If true, the Back button is displayed in the App Connector's footer. If false (default), the Back button is hidden.
`hideAppConnectionStep` (Credit Score Connector)	boolean	Hides the app connection step. True by default.
`isAppConnectionRequired` (Credit Score Connector)	boolean	Disables the "Get Score" button in the app connection step if no app is connected to the account (the same default-pool list shown in the Dashboard's Apps section, with status Loading or higher), except User Platform Data. True by default.
`excludedServicesIds`	string	Excludes specific services from a category in the integrations pool, so only currently-connectable services are shown. `serviceId` specifies which service to exclude; `categoryId` specifies the category to exclude it from.
`creditBureauId`	string	Defines which credit bureau to use for the search-and-connect process inside the Credit Score Connector. Default: CreditSafe.

filterParams example

{
  "categoriesIds": ["uuid"],
  "servicesIds": ["uuid"]
}

application example

{
  "companyName": "Test Company",
  "email": "[email protected]",
  "applicationNumber": "234234234324",
  "countryAlpha2Code": "US",
  "userExternalId": "1234567890123",
  "companyExternalId": "1234567890123123",
  "username": "testusername123"
}

Insights Widget Properties (Optional)

PROPERTY	TYPE	DESCRIPTION
`showHeaderIcon`	boolean	If true, the icon in the widget's header is shown. If false (default), the icon in the widget's header is hidden.
`name`	string	Text in the widget's header. If empty (default), the widget's default name is displayed.
`readonly`	boolean	If true, the widget is displayed in read-only mode. If false (default), read-only mode is disabled.
`demo`	boolean	If true, demo mode is enabled, populating the widget with mock data in read-only mode. If false (default), demo mode is disabled.
`componentIds`	array of uuid	An array of widget IDs for which insights should be shown in the list. Default: an empty array, meaning insights from all widgets are displayed — see widget IDs below.

Widget IDs

WIDGET	ID
Accounts	`22e2ec5f-ea14-4cbe-a5bc-1be7df4130a1`
Business Valuation	`3a648cb7-55ab-4448-aab1-2403f517538d`
Carbon Footprint	`587f0167-ffa2-44b1-b031-a70cda99ef8f`
Cash Flow Forecast	`489b61aa-ef28-11ed-86b4-0242ac1e0029`
Credit Score	`73f0158c-12c3-4927-b2ad-d79fe91b7473`
eCommerce & Sales	`8ad43e89-7c9f-11ee-a77f-0242ac120005`
Key Metrics	`4e36abee-33a7-4256-a500-fc6baa11e9a1`
Marketing	`10b6fd42-5198-4730-8c76-4531e8879875`
Payment Calendar	`43d765e4-397e-4117-ac35-587547b1c38c`

Widget Events

To sustain certain background operations, Business Health widgets emit JavaScript frontend events. These let you build custom user flows around how users interact with widgets. They also trigger background processes without affecting the user's ability to keep interacting with the product.

Events and the widgets that use them

Event Name	Event Data	Trigger	Widget
`invalidtoken`	Axios Error	After pressing Try Again on the error screen shown when the token expired.	All widgets
`handleBack`	—	After the Back button is pressed.	App Connector
`handleNext`	—	After the Next button is pressed.	App Connector
`startProcessing`	`{ bureauId: string; companyId: string }`	After calling the API method `/api/v1/wc/credit-score/start-processing`.	Credit Score Connector
`handleBack`	—	After the Back button is pressed.	Credit Score Connector