Migration Guide

Migrating to 2026-04-01

Summary

This version introduces a major shift from plain integer amounts to structured MonetaryAmount objects across all insurance types. Several fields have been removed or relocated. Collections have also moved from /insurance/collection to a shared, top-level /collections resource, and the collection request body has moved from an untyped input map to a typed parameters array.

Breaking Changes

1. Monetary fields changed from integer to MonetaryAmount

All fields that previously returned a bare integer now return a MonetaryAmount object with amount (number) and currency (string) properties.

Action: Update your parsing logic wherever you read these fields. Instead of accessing the value directly (e.g., discountAmount: 500), you now receive an object (e.g., discountAmount: { amount: 500, currency: "SEK" }).

Affected fields by insurance type:

2. MonetaryAmount field renamed: currencyCode to currency

The MonetaryAmount object's currencyCode field has been renamed to currency. The type has also changed from a string enum to an open string (still ISO 4217 values, but additional currencies may appear in the future).

This affects premium.amount: read premium.amount.currency instead of premium.amount.currencyCode.

Action: Replace all references to currencyCode with currency. If you validate against a fixed set of currency codes, update your validation to accept any ISO 4217 string.

3. Removed fields

Several fields have been removed from specific insurance types:

Action: Remove references to these fields from your code.

4. Insured amount fields changed from integer to MonetaryAmount on person insurance types

The following fields that were previously plain integers are now MonetaryAmount objects on their respective insurance types:

Action: Update your parsing logic to read field.amount and field.currency instead of using the integer value directly.

5. Collection request body uses typed parameters

POST /collections takes an InitiateCollectionRequest. The untyped input map and the separate consents field are replaced by a single typed parameters array. loginMethod must still be sent as a top-level field (a LOGIN_METHOD entry in parameters is ignored), and the Swedish values are unchanged.

// 2024-06-01
{
  "company": "se-lansforsakringar",
  "loginMethod": "SWEDISH_MOBILE_BANKID_OTHER_DEVICE",
  "input": { "SWEDISH_PERSONAL_NUMBER": "199001011234" }
}

// 2026-04-01
{
  "company": "se-lansforsakringar",
  "loginMethod": "SWEDISH_MOBILE_BANKID_OTHER_DEVICE",
  "parameters": [
    { "type": "SWEDISH_BANKID", "personalNumber": "199001011234" }
  ]
}

Action: Convert each input key, consent and session identifier into a typed entry in parameters. See the 2025-01-01 migration guide for the full per-login-method mapping.

6. Collections moved to a top-level /collections resource

Collection endpoints no longer live under the product namespace. A collection is created at POST /collections regardless of product, and the insurance data is read from a product sub-path.

Action: Replace /insurance/collection with /collections, and read data from /collections/{collectionId}/insurance/data instead of /insurance/collection/{collectionId}/data. Status, supplement-info and deletion keep the same suffixes under the new prefix.

7. New CollectionStatus value

A new CollectionStatusResponse status value, AUTHENTICATION_ERROR, is returned for a sign-in failure that doesn't match a more specific status, for example when the chosen login method can't be used at the company. In 2024-06-01 these were reported as FAILED.

Action: Handle AUTHENTICATION_ERROR.

8. New CompanyAvailability status value

On CompanyAvailability:

• New status value DEGRADED_PERFORMANCE: the company is experiencing intermittent issues; collections can still be attempted but may fail or return incomplete data

Action: Handle the DEGRADED_PERFORMANCE status.

Migration Checklist

• Update Insurely-Version header to 2026-04-01
• Update all monetary field parsing to handle MonetaryAmount objects ({ amount, currency }) instead of plain integers
• Replace currencyCode references with currency in MonetaryAmount
• Remove references to deleted fields: usedForWork (car), numberOfToilets (villa)
• Update insured amount fields on person insurance types (InsuranceAccident, InsuranceChild, InsuranceLife, InsurancePregnancy) from integer to MonetaryAmount
• Update all endpoint URLs from /insurance/collection/* to /collections/*, and read data from /collections/{collectionId}/insurance/data
• Move input, consents and session identifiers into the typed parameters array
• Handle the new AUTHENTICATION_ERROR status
• Handle the DEGRADED_PERFORMANCE company availability status

Field Mapping Table