Migration Guide

Migrating to 2026-04-01

Summary

This guide covers migrating from Insurance API version 2023-03-15 to 2026-04-01, spanning three version jumps (2023-03-15 to 2024-06-01 to 2025-01-01 to 2026-04-01). The major changes are: all collection endpoints have moved from /insurance-collection/ to 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 new Holder object, the premium fields have been collected in the Premium object, several monetary fields have changed from plain integers to MonetaryAmount objects, and collection status values now use underscores instead of spaces.

Breaking Changes

Endpoint paths restructured

All collection-related endpoints have moved from /insurance-collection/ to a shared, top-level /collections resource, with the insurance data read from a product sub-path. The company availability endpoint has also moved.

Action: Update all API endpoint URLs, and remove calls to /insurance-collection/get-parameters and /insurance-collection/parameters/{country}.

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.

// 2023-03-15
{
  "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" }
  ]
}

All Swedish BankID login methods, including the _TEST and _MOCK variants, use the same SWEDISH_BANKID parameter.

The trade-union consent only matters if your integration is set up to require consent for sensitive data; it then decides whether policy documents are collected. A leftover consents array is ignored rather than rejected, so without a TRADE_UNION_CONSENT parameter the consent counts as not given.

Action: Rename insuranceCompany to company and convert each input key, consent and session identifier into a typed entry in parameters.

Policyholder fields moved to Holder object

Across all insurance types (InsuranceCar, InsuranceHome, InsuranceVilla, InsuranceIncome, InsuranceOtherVehicle, and others), the following flat fields have been removed and consolidated into a new holder field of type Holder:

• 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 insurance.insuranceHolderName, insurance.insuranceHolderEmail, etc. with the corresponding fields on insurance.holder.

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 2023-03-15. Its fields are renamed, and the MonetaryAmount object in premium.amount is restructured:

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

Fields changed from integer to MonetaryAmount

Several fields that were previously plain integers are now MonetaryAmount objects:

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

The values themselves are unchanged and still in kronor: discountAmount: 500 becomes discountAmount: { "amount": 500, "currency": "SEK" }.

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

Removed fields

The following fields have been removed from all insurance types that previously had them:

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

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

Action: Read id on the data response item instead of insurance.externalId. Use the premium object instead of premiumAmountYearRounded and premiumFrequency. Remove any usage of veterinaryCareCovered and numberOfToilets.

CollectionStatus field renames

On CollectionStatusResponse, returned by GET /collections/{collectionId}/status:

• insuranceCompany renamed to company
• status values are renamed and split (see Collection status values renamed and split below)

On CollectionStatusInformationMap:

• requiredInputTypes renamed to REQUIRED_INPUT_TYPES
• AUTOSTART_TOKEN, the precompiled bankid:/// app link, has been removed. Build the link from SWEDISH_MOBILE_BANKID_AUTOSTART_TOKEN, which is unchanged

Action: Rename collectionStatus.insuranceCompany to collectionStatus.company. Rename informationMap.requiredInputTypes to informationMap.REQUIRED_INPUT_TYPES. Stop reading AUTOSTART_TOKEN.

Supplement-info request changed

POST /insurance-collection/supplement-info is replaced by POST /collections/{collectionId}/supplement-info. The collection ID moves from the request body into the path, and the body is the object you previously sent in supplementalInformation, without the wrapper.

The body types that apply to Swedish insurance collections:

In RESPONSE_OBJECT, each header value is now a list of strings instead of a single string, because some headers (such as Set-Cookie) can repeat.

Action: Move the collection ID into the path and send one of the typed bodies above.

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.

Action: Read coverage.parameters instead of parameters.

Collection status values renamed and split

In 2023-03-15, status values were space-separated (for example COMPLETED PARTIAL). In 2026-04-01 every value uses underscores, WAITING FOR AUTHENTICATION is renamed to AUTHENTICATION_TIMEOUT, and FAILED, LOGIN and CONTACT FORM are split into more specific statuses:

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.

CompanyAvailability field renames

On CompanyAvailability:

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

Action: Rename insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName. Handle the DEGRADED_PERFORMANCE status.

InsuranceCar fields removed

The usedForWork and insuranceLevel fields have been removed from InsuranceCar.

Action: Remove usage of usedForWork and insuranceLevel.

New Features

New collection endpoints

• DELETE /collections/{collectionId} — delete a collection and its associated data

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
• Update company availability endpoint from /insurance-company/status to /companies/availability
• Replace all insuranceHolder* field reads with the new holder object
• 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
• Update all integer monetary fields to read from MonetaryAmount objects (e.g., discountAmount.amount)
• Read id on the data response item instead of insurance.externalId
• Read coverage.parameters instead of parameters
• Send supplement-info to /collections/{collectionId}/supplement-info with the typed body directly
• Build the BankID app link from SWEDISH_MOBILE_BANKID_AUTOSTART_TOKEN instead of AUTOSTART_TOKEN
• Rename insuranceCompany to company on the status response and CompanyAvailability
• Rename insuranceCompanyDisplayName to companyDisplayName on CompanyAvailability
• Rename requiredInputTypes to REQUIRED_INPUT_TYPES on CollectionStatusInformationMap
• Handle the DEGRADED_PERFORMANCE company availability status
• Update status handling to the 2026-04-01 status names (including WAITING FOR AUTHENTICATION → AUTHENTICATION_TIMEOUT), and the values that FAILED, LOGIN and CONTACT FORM are split into
• Remove usage of deleted fields: usedForWork, insuranceLevel, veterinaryCareCovered, numberOfToilets
• Test end-to-end collection flow with new endpoints and response shapes

Field Mapping Table