Configuration options
The full shape of the window.insurely configuration object. Set it before the iframe is added to the page, since bootstrap.js reads it only once (see Before you go live):
window.insurely = {
config: {
customerId: string, // Your unique customer ID (required)
configName: string, // The name of your specific configuration (required)
language?: 'en' | 'sv' | 'da' | 'no' | 'fr' | 'et' | 'lv' | 'lt', // Interface language. An unknown value stops the interface loading
themeMode?: 'light' | 'dark' | 'system', // Color theme (see below)
authToken?: string, // 'Bearer <JWT>' (see below)
disableAutomaticScrolling?: boolean, // No auto-scroll (default false)
scrollToTopOffset?: number, // Sticky header px, web only (default 0)
dataAggregation?: {
referenceId?: string, // Unique reference for this collection (max 50 chars, [a-zA-Z0-9@_-])
advisorHandle?: string, // Links collection to a specific advisor in your dashboard
},
},
prefill?: {
customer?: {
email?: string, // Customer's email address
phoneNumber?: string, // Customer's phone number
},
user?: {
swedishPersonalNumber?: string, // Format: YYYYMMDDXXXX
estonianPersonalNumber?: string | PrefilledField,
estonianPhoneNumber?: string | PrefilledField,
norwegianPersonalNumber?: string,
norwegianPhoneNumber?: string,
username?: string | PrefilledField, // Login username or email
},
dataAggregation?: {
company?: string, // Pre-select a single company, e.g. "se-xxxx", "no-xxxx"
companies?: string[], // Pre-select multiple companies, e.g. ["se-xxxx", "no-xxxx"]
},
},
}Available company codes can be found in the module's status information. Pre-selecting a single company skips the company selection step entirely.
themeMode controls which color theme the interface is rendered in. system follows the user's OS-level preference. For the chosen mode to render correctly, your configuration needs to have a matching light and/or dark theme set up — if no dark theme is configured, the interface will always fall back to the light theme regardless of themeMode. Without themeMode, the interface uses system when your configuration has both a light and a dark theme, and otherwise the one theme it has.
Auth token
authToken is a token for products that act on the user's behalf, such as the wealth overview. It must be a JWT with the Bearer prefix, 'Bearer <header>.<payload>.<signature>', and is sent with every request the interface makes. A value in any other format stops the interface loading. The token must have an exp claim: a token without one counts as expired.
- Replace the token before it expires, with
updateAuthToken. The interface sendsAUTH_TOKEN_EXPIRING_SOONabout five minutes before, but time the refresh from the token'sexprather than relying on the event. - Once the token has expired, the interface sends
APP_CLOSEwith the value'Token expired', possibly more than once. Close the interface, or replace the token.
Prefilled fields you can lock
estonianPersonalNumber, estonianPhoneNumber and username also accept an object instead of a string:
type PrefilledField = {
value: string,
inputField: 'normal' | 'disabled', // 'disabled' locks the field
}'disabled' locks the field in the Estonian Mobile-ID and Smart-ID login forms. Other forms pre-fill username.value but leave it editable.
Replace the auth token while the interface is open
Once the interface has sent APP_LOADED, bootstrap.js adds window.insurely.updateAuthToken. Call it with a new token before the old one expires:
window.insurely.updateAuthToken('Bearer <header>.<payload>.<signature>');The interface answers with VALID_AUTH_TOKEN and uses the new token for every request from then on, or with INVALID_AUTH_TOKEN if the format is wrong, keeping the old token. Neither checks whether the token has expired. Call it with an empty string to remove the token.
Track what happens in the interface (optional)
The interface sends postMessage events during the data collection process. Listen for them to show progress indicators, track completions, or handle user actions like closing the interface.
Every event has a name and a value, and some also carry extraInformation.
Loading and navigation
| Event name | Value | Description |
|---|---|---|
| APP_LOADED | When the module and all its content is loaded | |
| PAGE_VIEW | Name of current page | Sent on each page navigation. This is subject to change and we do not recommend to rely on this for tracking/analytic purposes |
| APP_CLOSE | Empty, or 'Token expired' | The module is done and wants to be closed, which it cannot do itself. Sent when the user presses back on the first page, presses the call to action on the end page or closes the wealth overview, and when the authToken has expired. Handle it by removing or hiding the module, or by closing the web view in a mobile app |
| NON_RECOVERABLE_ERROR | { type } | The interface hit an error it cannot recover from and shows an error screen. type is APPLICATION_STATE_ERROR, for example for an invalid configuration, or UNEXPECTED_RUNTIME_ERROR |
Company selection and collection
| Event name | Value | Description |
|---|---|---|
| SELECTED_COMPANY | Company code, e.g. se-demo | The user picked a company |
| DESELECTED_COMPANY | Company code | The user removed a company on a multi-select screen |
| COLLECTION_GROUP_CREATED | Object containing totalCollections and multipleCollections | Sent when the user has confirmed the company selection, before authentication begins |
| SELECTED_AUTHENTICATION_METHOD | Authentication method | When the user has selected an authentication method |
| COLLECTION_INITIATED | { personalNumber } | The user submitted their personal number to start Swedish BankID |
| COLLECTION_GROUP_STARTED | Object containing totalCollections and multipleCollections | Sent once per session when the first collection in the group begins |
| COLLECTION_ID | The collectionId string | Sent right after the collection has started. extraInformation may contain externalUserUuid — our stable identifier for the end user across their collections. Nullable: not every collection carries one, so tolerate its absence. |
| COLLECTION_STATUS | The collection status | Sent whenever the collection's status information changes, so the same status can arrive more than once. extraInformation contains the collectionId and company |
| COLLECTION_SKIPPED | { company, collectionId } | The user skipped one company during a multi-company collection |
| CANCEL_COLLECTION_PRESSED | The user chose to skip all remaining companies during a multi-company collection | |
| INVALID_CREDENTIALS | { company } | A collection ended because the user's login details were wrong |
| ERROR | { collectionStatus, cause, message } | A collection failed for any other reason. cause says why |
| COLLECTION_GROUP_ENDED | Group outcome ('success' or 'failure') | Sent when all collections in the group have finished. extraInformation contains totalCollections, successfulCollections, failedCollections, and multipleCollections |
Results
| Event name | Value | Description |
|---|---|---|
| RESULTS | Array of collected data | The format of the data is dependent on the backendAPI version that is used. |
| RESULTS_SELECTED_ITEM | Object containing id, and autoSelected from the standard insurance results view | Sent when a result item is selected, for insurance and wealth. In the standard insurance results view, autoSelected is true when the only result was selected for the user and false when the user picked it |
| WEALTH_RESULT_SELECTED_ITEMS | Array of accounts | The user confirmed which accounts to move, in the account selection views |
| SELECTED_COVERAGE_PACKAGE | The selected company, package and coverage | Manual selection only. See Collection methods |
| CONTACT_DETAILS | { email, phoneNumber } | The user submitted the contact form |
Opening other apps
On a website, bootstrap.js handles these for you. In a mobile webview, your app must open the URL.
| Event name | Value | Description |
|---|---|---|
| OPEN_SWEDISH_BANKID | Object containing url and autostartToken | Request to open the swedish BankID app |
| OPEN_COMPANION_APP | The URL, as a string | The user is moving the login to their phone through the Anessa app |
| OPEN_FRENCH_TRUST_ME | { url } | Open the authentication app for the login, e.g. TrustMe or a bank's own app |
| OPEN_FRANCE_IDENTITE | { url } | Open France Identité |
Auth token
| Event name | Value | Description |
|---|---|---|
| AUTH_TOKEN_EXPIRING_SOON | The authToken expires in about five minutes | |
| VALID_AUTH_TOKEN | The token passed to updateAuthToken was accepted | |
| INVALID_AUTH_TOKEN | The token passed to updateAuthToken had the wrong format and was not used |
Listening for events:
window.addEventListener('message', (event) => {
// Only trust the Anessa interface: any other page or frame can post messages too.
if (event.origin !== 'https://blocks.anessa.co') return;
const { data } = event;
console.groupCollapsed(data.name);
console.log('Name: ', data.name);
console.log('Value: ', data.value);
console.groupEnd();
});Important note: The data format for the RESULTS and COLLECTION_STATUS events is dependent on the backendAPI version that is used. This means that upgrading to a newer version of the backendAPI can change the format of the data.
Understand collection statuses
COLLECTION_STATUS passes on the status from the Anessa API unchanged. These are the statuses of API version 2024-06-01 and later; older versions spell some of them differently.
In progress
| Status | Description |
|---|---|
| RUNNING | Collection process has started |
| LOGIN | The user is being authenticated towards the company |
| WAITING_FOR_USER_ACTION | User action is needed for authentication to continue, e.g. signing in the BankID app |
| TWO_FACTOR_PENDING | Waiting for the user to supply a two-factor code |
| CUSTOMER_ENROLLMENT_CHECK | Checking whether the user is a customer at the company before data can be collected |
| CONTACT_FORM_PENDING | The company has asked the user to fill out a contact form, and the collection is waiting for it |
| COLLECTING | Collection of data has started |
Finished
| Status | Description |
|---|---|
| COMPLETED | Data was collected successfully |
| COMPLETED_PARTIAL | Finished, but not all data was collected |
| COMPLETED_EMPTY | Finished, but no data was found |
Failed
| Status | Description |
|---|---|
| FAILED | Failed, for example because of a timeout, the company's site being down or another temporary issue |
| INCORRECT_CREDENTIALS | The user entered incorrect login details |
| INCORRECT_TWO_FACTOR_CODE | The company rejected the two-factor code. A new collection is needed to try again (2025-01-01 and later) |
| AUTHENTICATION_TIMEOUT | The user did not authenticate in time |
| AUTHENTICATION_CANCELLED | The user cancelled the authentication |
| AUTHENTICATION_CONFLICT | Cancelled because another authentication was already in progress |
| AUTHENTICATION_MISMATCH | The person who authenticated is not the person who started the collection |
| AUTHENTICATION_ERROR | Any other authentication failure (2026-04-01) |
| ACCOUNT_TEMPORARILY_LOCKED | The company has temporarily blocked the account |
| CUSTOMER_ENROLLMENT_REQUIRED | The user needs to sign up as a customer at the company first |
| KYC_FORM | The company is asking the user to fill out a KYC form, which blocks the collection |
| CONTACT_FORM | The user needs to fill out a contact form in the company's own channel, or did not fill it out in time |
| THIRD_PARTY_ERROR | A technical issue on the company's side |
| TWO_FACTOR_METHOD_SELECTION_TIMEOUT | The user did not choose a two-factor method in time |
| LOGIN_METHOD_NOT_APPLICABLE | The chosen login method is not available for this user at the company (2026-04-01) |
| FAILED_PDF_PARSE | The uploaded PDF could not be read |
| FAILED_PDF_USER_INPUT | The uploaded PDF is not supported |
A failed collection is also reported with INVALID_CREDENTIALS (for incorrect login details) or ERROR (for everything else).
Receive the collected data (optional)
If you have a data processing agreement (DPA) with us, you can receive the actual insurance data that was collected. This allows you to:
- Store the data in your own system
- Process it for your own analysis
- Use it in your applications
Note: This feature requires a special agreement with us and is only available to approved partners.
window.addEventListener('message', (event) => {
// Only trust the Anessa interface: any other page or frame can post messages too.
if (event.origin !== 'https://blocks.anessa.co') return;
const { data } = event;
if (data.name === 'RESULTS') {
console.log('Collection data:', data.value);
// Handle the collected data
}
});Last updated on