Standard flow & events

A data-aggregation session emits postMessage events in a predictable order. Knowing the sequence helps you decide where to show progress, fire analytics, or react to completion. The full payload and shape of each event is documented in the Configuration reference; this page explains when each one fires.

The prebuilt UI supports three collection methods, and they don't all emit the same events:

• Login (connection) — the standard flow, and the one most integrations use. The full event sequence below.
• PDF upload — the same collection pipeline as login; only the authentication step differs.
• Manual selection — skips data collection entirely and ends with a single SELECTED_COVERAGE_PACKAGE event.

A collection group is everything kicked off together when the user confirms their selection. It contains one collection per selected company:

• Single collection — the user picked one company. COLLECTION_GROUP_CREATED reports { totalCollections: 1, multipleCollections: false }, and you'll see one COLLECTION_ID and one run of COLLECTION_STATUS events.
• Multiple collections — the user picked several companies. COLLECTION_GROUP_CREATED reports { totalCollections: <n>, multipleCollections: true }, and the per-company events (COLLECTION_ID, COLLECTION_STATUS) repeat once per company.

Some events fire once per group (COLLECTION_GROUP_CREATED, COLLECTION_GROUP_STARTED, RESULTS, COLLECTION_GROUP_ENDED) and others once per company (COLLECTION_ID, and a stream of COLLECTION_STATUS).

Login (connection) — the standard flow

1. APP_LOADED — once, as soon as the interface has loaded inside the iframe. A safe signal that the module is ready.
2. PAGE_VIEW — every time the user navigates to a new view (company selection, consent, authentication, results, …). Fires throughout the flow, not just at the start. The value is the name of the view. This is informational only — the view names can change, so don't build logic on them.
3. SELECTED_COMPANY — when the user picks a company. The value is the company code (e.g. se-demo). On a multi-select screen you may also receive DESELECTED_COMPANY when they remove one.
4. COLLECTION_GROUP_CREATED — once, the moment the user confirms their company selection, before authentication begins. The value carries totalCollections and multipleCollections, so this is your earliest signal of how many collections to expect.
5. SELECTED_AUTHENTICATION_METHOD — once per company, when the user picks how to authenticate (for example username & password). The value is the chosen method. It fires per company in both single- and multi-company collections.
6. COLLECTION_GROUP_STARTED — once per group, when the first collection actually begins. Same totalCollections / multipleCollections payload as COLLECTION_GROUP_CREATED. This marks the transition from setup to active collection.
7. COLLECTION_ID — once per company, right after that company's collection starts. Identifies the individual collection.
8. COLLECTION_STATUS — many times per company. Fires on every status change as a collection progresses (e.g. LOGIN → COLLECTING → COMPLETED). The value is the status; extraInformation includes the collectionId and company. See collection statuses for the full list. This is the event to drive a live progress indicator.
9. RESULTS — once, when all collections in the group have completed. The value is the array of collected data. (Available only if you have a data processing agreement — see Receive the collected data.)
10. COLLECTION_GROUP_ENDED — once per group, after every collection has finished. The value is 'success' or 'failure', and extraInformation summarises totalCollections, successfulCollections, failedCollections, and multipleCollections. This is the most reliable signal that the data-aggregation step is done.
11. RESULTS_SELECTED_ITEM — after collection, when a specific result item (e.g. an insurance policy) is selected in the results view. The value is { id } — the selected item's id. It fires when the user clicks an item. For insurance results, when there is only one item it is also emitted automatically without any click (the single item is auto-selected). This auto-select does not apply to wealth — for wealth the event always requires a user selection.
12. APP_CLOSE — when the user clicks the close icon on the results page. In a normal embed this sends the user back to the start; in a mobile/webview context you can use it to close the module.

The Swedish market adds extra authentication events on top of this flow — see Swedish BankID.

A single-company collection

For one company, the events arrive roughly like this:

APP_LOADED
PAGE_VIEW ...                       (repeats as the user moves through the UI)
SELECTED_COMPANY                    "se-demo"
COLLECTION_GROUP_CREATED            { totalCollections: 1, multipleCollections: false }
SELECTED_AUTHENTICATION_METHOD
COLLECTION_GROUP_STARTED            { totalCollections: 1, multipleCollections: false }
COLLECTION_ID                       <id>
COLLECTION_STATUS                   LOGIN
COLLECTION_STATUS                   COLLECTING
COLLECTION_STATUS                   COMPLETED
RESULTS                             [ ...collected data ]   (with a DPA)
RESULTS_SELECTED_ITEM               {id: "01233..."}
COLLECTION_GROUP_ENDED              "success"
APP_CLOSE                           (when the user leaves)

Multiple companies in one group

When the user selects several companies (the multi-select flow), the per-company events SELECTED_COMPANY, SELECTED_AUTHENTICATION_METHOD, COLLECTION_ID, and COLLECTION_STATUS each repeat once per company, while COLLECTION_GROUP_CREATED, COLLECTION_GROUP_STARTED, RESULTS, and COLLECTION_GROUP_ENDED still fire only once for the whole group.

Swedish BankID is an exception: with multiple companies the user authenticates them all on one combined screen rather than per company — see Swedish BankID.

PDF upload

When the user uploads a policy document instead of logging in, the flow is identical to login — it runs the same collection pipeline and ends with RESULTS and COLLECTION_GROUP_ENDED. The only difference is the authentication step: SELECTED_AUTHENTICATION_METHOD reports PDF_UPLOAD. You can treat it exactly like the standard flow.

Manual selection

Manual selection (sometimes called manual compare) is fundamentally different: the user picks their company and their package, and Insurely returns the standard coverage for that package rather than collecting from their account. Because there is no collection, none of the COLLECTION_* events or RESULTS are emitted. Instead the flow ends with a single SELECTED_COVERAGE_PACKAGE event.

APP_LOADED
PAGE_VIEW ...
SELECTED_COMPANY                    "fr-credit-agricole"
SELECTED_AUTHENTICATION_METHOD      "MANUAL_SELECT"
SELECTED_COVERAGE_PACKAGE           { company, packageName, coverage, insuranceParameters, ... }

The SELECTED_COVERAGE_PACKAGE payload (the selected company, package, and its coverage) and a full handling example are documented on the Collection methods page.

Swedish BankID

The standard flow above is market-agnostic. The Swedish market authenticates with BankID, which adds a couple of events on top of the login flow. You only need to handle these if you serve the Swedish market.

• COLLECTION_INITIATED — fires when the user submits their personal number to start BankID authentication. The value is { personalNumber }. In a single collection it fires for that collection; on the combined multi-select screen (below) it fires once for the whole group.
• OPEN_SWEDISH_BANKID — fires only on mobile, when the BankID app needs to be opened. The value contains the url and autostartToken. You only need this if you handle Swedish BankID in a mobile/webview context, where you may need to open the app yourself.

Multiple companies. With several companies, Swedish BankID does not authenticate each company on its own screen. Instead the user authenticates all of them together on one combined screen, so:

• You receive a PAGE_VIEW with the value DATA_AGGREGATION_MULTI_SELECT_AUTHENTICATION.

Listening for the events

You listen for all of these the same way — a single message listener on the window:

window.addEventListener('message', ({ data }) => {
  switch (data.name) {
    case 'COLLECTION_GROUP_CREATED':
      // data.value.totalCollections tells you how many collections to expect
      break;
    case 'COLLECTION_STATUS':
      // data.value is the status; data.extraInformation.collectionId / .company identify it
      break;
    case 'COLLECTION_GROUP_ENDED':
      // data.value is 'success' or 'failure' — the data-aggregation step is done
      break;
  }
});

See the Configuration reference for every event, its value, and the full list of collection statuses.