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 sends AUTH_TOKEN_EXPIRING_SOON about five minutes before, but time the refresh from the token's exp rather than relying on the event.
  • Once the token has expired, the interface sends APP_CLOSE with 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 nameValueDescription
APP_LOADEDWhen the module and all its content is loaded
PAGE_VIEWName of current pageSent on each page navigation. This is subject to change and we do not recommend to rely on this for tracking/analytic purposes
APP_CLOSEEmpty, 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 nameValueDescription
SELECTED_COMPANYCompany code, e.g. se-demoThe user picked a company
DESELECTED_COMPANYCompany codeThe user removed a company on a multi-select screen
COLLECTION_GROUP_CREATEDObject containing totalCollections and multipleCollectionsSent when the user has confirmed the company selection, before authentication begins
SELECTED_AUTHENTICATION_METHODAuthentication methodWhen the user has selected an authentication method
COLLECTION_INITIATED{ personalNumber }The user submitted their personal number to start Swedish BankID
COLLECTION_GROUP_STARTEDObject containing totalCollections and multipleCollectionsSent once per session when the first collection in the group begins
COLLECTION_IDThe collectionId stringSent 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_STATUSThe collection statusSent 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_PRESSEDThe 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_ENDEDGroup outcome ('success' or 'failure')Sent when all collections in the group have finished. extraInformation contains totalCollections, successfulCollections, failedCollections, and multipleCollections

Results

Event nameValueDescription
RESULTSArray of collected dataThe format of the data is dependent on the backendAPI version that is used.
RESULTS_SELECTED_ITEMObject containing id, and autoSelected from the standard insurance results viewSent 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_ITEMSArray of accountsThe user confirmed which accounts to move, in the account selection views
SELECTED_COVERAGE_PACKAGEThe selected company, package and coverageManual 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 nameValueDescription
OPEN_SWEDISH_BANKIDObject containing url and autostartTokenRequest to open the swedish BankID app
OPEN_COMPANION_APPThe URL, as a stringThe 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 nameValueDescription
AUTH_TOKEN_EXPIRING_SOONThe authToken expires in about five minutes
VALID_AUTH_TOKENThe token passed to updateAuthToken was accepted
INVALID_AUTH_TOKENThe 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

StatusDescription
RUNNINGCollection process has started
LOGINThe user is being authenticated towards the company
WAITING_FOR_USER_ACTIONUser action is needed for authentication to continue, e.g. signing in the BankID app
TWO_FACTOR_PENDINGWaiting for the user to supply a two-factor code
CUSTOMER_ENROLLMENT_CHECKChecking whether the user is a customer at the company before data can be collected
CONTACT_FORM_PENDINGThe company has asked the user to fill out a contact form, and the collection is waiting for it
COLLECTINGCollection of data has started

Finished

StatusDescription
COMPLETEDData was collected successfully
COMPLETED_PARTIALFinished, but not all data was collected
COMPLETED_EMPTYFinished, but no data was found

Failed

StatusDescription
FAILEDFailed, for example because of a timeout, the company's site being down or another temporary issue
INCORRECT_CREDENTIALSThe user entered incorrect login details
INCORRECT_TWO_FACTOR_CODEThe company rejected the two-factor code. A new collection is needed to try again (2025-01-01 and later)
AUTHENTICATION_TIMEOUTThe user did not authenticate in time
AUTHENTICATION_CANCELLEDThe user cancelled the authentication
AUTHENTICATION_CONFLICTCancelled because another authentication was already in progress
AUTHENTICATION_MISMATCHThe person who authenticated is not the person who started the collection
AUTHENTICATION_ERRORAny other authentication failure (2026-04-01)
ACCOUNT_TEMPORARILY_LOCKEDThe company has temporarily blocked the account
CUSTOMER_ENROLLMENT_REQUIREDThe user needs to sign up as a customer at the company first
KYC_FORMThe company is asking the user to fill out a KYC form, which blocks the collection
CONTACT_FORMThe user needs to fill out a contact form in the company's own channel, or did not fill it out in time
THIRD_PARTY_ERRORA technical issue on the company's side
TWO_FACTOR_METHOD_SELECTION_TIMEOUTThe user did not choose a two-factor method in time
LOGIN_METHOD_NOT_APPLICABLEThe chosen login method is not available for this user at the company (2026-04-01)
FAILED_PDF_PARSEThe uploaded PDF could not be read
FAILED_PDF_USER_INPUTThe 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