Migration Guide

Migrating to 2026-04-01

Summary

This migration covers four version jumps (2021-01-01 -> 2023-03-15 -> 2024-06-01 -> 2025-01-01 -> 2026-04-01) and includes significant restructuring of the API. The collection endpoints have been reorganized under a shared, top-level /collections resource, the collection request body has moved from an untyped input map to a typed parameters array, policyholder fields have been consolidated into a dedicated Holder object, monetary integer fields have been replaced with MonetaryAmount objects, and the premium fields have been collected in the Premium object.

Breaking Changes

Endpoint paths restructured

All /insurance-collection/* and /insurance-company/* endpoints have been removed. Collections are now a shared, top-level /collections resource, with the insurance data read from a product sub-path.

Action: Update all endpoint URLs in your integration according to the mapping below.

Collection request body uses typed parameters

POST /collections takes an InitiateCollectionRequest. The insuranceCompany field is renamed to company, and 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.

// 2021-01-01
{
  "insuranceCompany": "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: Rename insuranceCompany to company and 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.

Policyholder fields moved to Holder object

The insuranceHolder* fields and otherInsuranceHolder have moved from individual insurance objects into a new Holder object, accessible via the holder field on each insurance type:

• insuranceHolderName → holder.name
• insuranceHolderEmail → holder.email
• insuranceHolderPhoneNumber → holder.phoneNumber
• insuranceHolderStreetAddress → holder.streetAddress
• insuranceHolderPostalCode → holder.postalCode
• insuranceHolderCity → holder.city
• otherInsuranceHolder → holder.otherInsuranceHolder

Action: Replace all reads of insuranceHolder* fields with the equivalent fields on the holder object. For example, change insurance.insuranceHolderName to insurance.holder.name and insurance.otherInsuranceHolder to insurance.holder.otherInsuranceHolder.

Removed fields from Insurance base object

The following fields have been removed from Insurance and all insurance type objects:

• externalId: the same value is now returned as id on each item in the data response, next to insurance (see FullInsuranceWrapper)
• premiumAmountYearRounded
• premiumFrequency

The premium fields premiumAmountYearRounded, premiumFrequency and paymentMethod have moved into the premium object (see Premium fields moved into premium below).

Action: Read id on the data response item instead of insurance.externalId, and use the premium object instead of premiumAmountYearRounded and premiumFrequency.

Integer monetary fields changed to MonetaryAmount

Multiple fields across insurance types that were previously plain integer values are now MonetaryAmount objects with amount and currency fields. This affects:

• discountAmount on all insurance types
• animalPurchasePrice, veterinaryCareAmount, veterinaryCareAmountRemaining on InsuranceAnimal
• insuredMovablesAmount on InsuranceCottage, InsuranceFarm, InsuranceHome, InsuranceVilla
• insuredAmount and insuredMonthlyAmount on InsuranceIncome
• insuredAmountBaseEconomicalDisability, insuredAmountBaseMedicalDisability, insuredAmountLife, insuredAmountMaxMedicalDisability on InsuranceAccident, InsuranceChild
• insuredAmountLife on InsuranceLife
• insuredAmountBaseMedicalDisability on InsurancePregnancy

Action: Update all reads of these fields from field (integer) to field.amount (number) and field.currency (string).

Premium fields moved into premium

premiumAmountYearRounded, premiumFrequency and paymentMethod have been removed from the insurance object. Use the premium object (Premium) instead:

A Swedish premium in 2026-04-01 looks like this:

"premium": {
  "@market": "se",
  "amount": { "amount": 2355, "currency": "SEK" },
  "period": "YEARLY_PREMIUM_PERIOD",
  "paymentFrequency": 12,
  "paymentMethod": "AUTOGIRO"
}

Action: Read the premium amount from premium.amount instead of premiumAmountYearRounded, and check premium.period to see what period it covers. Read the payment frequency from premium.paymentFrequency and the payment method from premium.paymentMethod.

Changes inside the existing premium object

Only relevant if you already read the premium object in 2021-01-01. Its fields are renamed, and the MonetaryAmount object in premium.amount is restructured:

Action: Update your reads of these fields to the new names.

Removed fields on specific insurance types

• usedForWork removed from InsuranceCar
• insuranceLevel removed from InsuranceCar
• veterinaryCareCovered removed from InsuranceAnimal
• numberOfToilets removed from InsuranceVilla

Action: Remove any references to these fields in your code.

CompanyAvailability field renames

On CompanyAvailability:

• insuranceCompany renamed to company
• insuranceCompanyDisplayName renamed to companyDisplayName
• New field companyGroup added
• New status value DEGRADED_PERFORMANCE: the company is experiencing intermittent issues; collections can still be attempted but may fail or return incomplete data

Action: Update field references from insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName. Handle the DEGRADED_PERFORMANCE status.

CollectionStatus information map changes

In the CollectionStatusInformationMap (extraInformation on the status response):

• AUTOSTART_TOKEN, the precompiled bankid:/// app link, has been removed. Build the link from SWEDISH_MOBILE_BANKID_AUTOSTART_TOKEN, which is unchanged.
• INSTRUCTIONS now holds the instructions object that 2021-01-01 returned as INSTRUCTIONS_V2, and INSTRUCTIONS_V2 has been removed. This only affects the SWEDISH_MOBILE_BANKID_SAME_DEVICE_CLIENT_SIDE_AUTHENTICATION login method.

Action: Stop reading AUTOSTART_TOKEN and INSTRUCTIONS_V2. If you use client-side BankID authentication, read the instructions from INSTRUCTIONS.

Supplement-info

POST /insurance-collection/supplement-info is replaced by POST /collections/{collectionId}/supplement-info. In 2026-04-01 you may need it in these cases:

Action: When you get CONTACT_FORM_PENDING, or if you use client-side BankID authentication, send the matching body to POST /collections/{collectionId}/supplement-info.

parameters moved into coverage

The parameters list on each item in the data response has moved into a new coverage object: read coverage.parameters instead of parameters. The parameter entries themselves are unchanged. coverage also holds the insurance's documents.

Action: Read coverage.parameters instead of parameters.

Collection status values renamed and split

In 2021-01-01, status values were space-separated (for example COMPLETED PARTIAL), and LOGIN, USER INPUT, WAITING FOR AUTHENTICATION and FAILED each covered several different situations. In 2026-04-01 every value uses underscores, and each of those situations has its own status. WAITING FOR AUTHENTICATION itself is renamed to AUTHENTICATION_TIMEOUT:

See Collection statuses for what each 2026-04-01 status means and how to act on it.

Action: Update every comparison against a status value to the 2026-04-01 name, and handle each of the values a single old status is now split into.

New Features

New collection endpoints

• DELETE /collections/{collectionId} — delete a collection and its associated data
• GET /collections/{collectionId}/insurance/policy/{policyId}/document/{documentId} — download policy documents

New field on InsuranceChild

insuredPersonDateOfBirth (the insured child's date of birth, YYYY-MM-DD) has been added to InsuranceChild. It is only available for some companies and is absent when it could not be determined.

Migration Checklist

• Update Insurely-Version header to 2026-04-01
• Update all endpoint URLs from /insurance-collection/* to /collections/*, and read data from /collections/{collectionId}/insurance/data
• Rename insuranceCompany to company in the collection request, and move input, consents and session identifiers into the typed parameters array
• Replace /insurance-company/status with /companies/availability, and remove calls to /insurance-collection/get-parameters and /insurance-collection/parameters/{country}
• Update insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName in company availability responses
• Migrate all insuranceHolder* field reads to the new holder object
• Read id on the data response item instead of insurance.externalId
• Read coverage.parameters instead of parameters
• Update all integer monetary fields to read from MonetaryAmount objects (.amount and .currency)
• Read the premium from the premium object: premium.amount together with premium.period (replaces premiumAmountYearRounded), premium.paymentFrequency (was premiumFrequency) and premium.paymentMethod (was paymentMethod)
• If you read the premium object before: use the renamed fields premium.amount.amount, premium.amount.currency and premium.period
• Build the BankID app link from SWEDISH_MOBILE_BANKID_AUTOSTART_TOKEN instead of AUTOSTART_TOKEN
• Answer CONTACT_FORM_PENDING, and send client-side BankID responses, through /collections/{collectionId}/supplement-info
• Update status handling to the 2026-04-01 status names, including the values that USER INPUT, WAITING FOR AUTHENTICATION, FAILED and LOGIN are split into
• Remove references to usedForWork and insuranceLevel (car), veterinaryCareCovered (animal) and numberOfToilets (villa)

Field Mapping Table