Migration Guide

Migrating to 2025-01-01

Summary

This guide covers migrating from Insurance API version 2023-03-15 to 2025-01-01, spanning two version jumps (2023-03-15 to 2024-06-01 to 2025-01-01). The major changes are: all collection endpoints have moved from /insurance-collection/ to /insurance/collection/, policyholder fields have been consolidated into a new Holder object, the Premium type has changed from a flat object to a oneOf union, and several monetary fields have changed from plain integers to MonetaryAmount objects. The insuranceCompany field has also changed from a fixed enum to an open string.

Breaking Changes

Endpoint paths restructured

All collection-related endpoints have moved from /insurance-collection/ to /insurance/collection/. The company availability endpoint has also moved.

Action: Update all API endpoint URLs. The /insurance-collection/get-parameters and /insurance-collection/parameters/{country} endpoints have been removed entirely -- use the new CollectionRequest schema when starting collections.

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

The following fields have been removed entirely with no equivalent on the Holder:

• insuranceHolderDateOfBirth
• insuranceHolderGender
• insuranceHolderOccupation

Action: Replace all reads of insurance.insuranceHolderName, insurance.insuranceHolderEmail, etc. with the corresponding fields on insurance.holder. Remove any usage of insuranceHolderDateOfBirth, insuranceHolderGender, and insuranceHolderOccupation — these fields are no longer available.

Premium type changed from object to oneOf

The Premium type has changed from a flat object to a oneOf union type with market-specific variants. This affects all insurance types that include a premium field.

Field changes on the base Premium:

• amount is now a MonetaryAmount object (was a plain number)
• frequency (string enum) has been renamed to paymentFrequency (integer — number of payments per year)
• period (PremiumPeriod) is a new field describing the billing period
• taxation has been removed

Action: Update your premium parsing logic to handle the new oneOf structure. Rename premium.frequency to premium.paymentFrequency and update the type from string enum to integer. Read premium.amount as a MonetaryAmount object. Remove any usage of premium.taxation.

MonetaryAmount structure changed

The MonetaryAmount object has changed:

• minorUnitAmount (long, minor units) has been replaced by amount (decimal, major units)
• currencyCode is now currency (type changed from string enum to string)

Warning: This is a semantic change, not just a rename. The old minorUnitAmount was expressed in minor currency units (e.g., 1032 for 10.32 EUR). The new amount is expressed in major currency units (e.g., 10.32). Simply renaming the field without adjusting the value interpretation will cause ~100x magnitude errors.

Action: Replace monetaryAmount.currencyCode with monetaryAmount.currency. Replace monetaryAmount.minorUnitAmount with monetaryAmount.amount and remove any minor-to-major unit conversion logic (e.g., dividing by 100), since amount is already in major units.

Fields changed from integer to MonetaryAmount

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

• discountAmount on all insurance types
• insuredMovablesAmount on InsuranceHome, InsuranceVilla
• insuredMonthlyAmount, insuredAmount on InsuranceIncome

Note: insuredMovablesAmount on InsuranceCottage and animalPurchasePrice, veterinaryCareAmount, veterinaryCareAmountRemaining on InsuranceAnimal are new MonetaryAmount fields that did not exist in 2023-03-15. insuredMovablesAmount on InsuranceFarm remains an integer.

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 -- replaced by id on FullInsuranceWrapper and CollectionItem
• paymentMethod — moved to DanishPremium
• premiumAmountYearRounded -- use the new premium object instead
• premiumFrequency -- now part of the premium object

Additionally, the parameters field has been removed from FullInsuranceWrapper.

Action: Replace externalId references with id. Move paymentMethod reads to premium.paymentMethod on DanishPremium. Remove any usage of premiumAmountYearRounded and parameters. Get frequency information from the new premium object.

CollectionStatus field renames

On CollectionStatus:

• insuranceCompany renamed to company
• status is now a strict enum with many new values (see below)

New status values your polling logic must handle:

• ACCOUNT_TEMPORARILY_LOCKED — end user's access temporarily blocked; retry after ~15 minutes
• AUTHENTICATION_CANCELLED — user cancelled the authentication flow
• AUTHENTICATION_CONFLICT — another authentication session is already in progress
• AUTHENTICATION_MISMATCH — authenticated identity does not match the expected user
• AUTHENTICATION_TIMEOUT — authentication was not completed in time
• COLLECTION_INPUT_PENDING — waiting for additional input via supplement-info
• COLLECTION_INPUT_TIMEOUT — supplement-info input was not provided in time
• CONTACT_FORM — a contact form must be completed to proceed
• CONTACT_FORM_PENDING — waiting for contact form submission
• CUSTOMER_ENROLLMENT_REQUIRED — user must enroll with the provider before data can be collected
• FAILED_PDF_PARSE — PDF document could not be parsed
• FAILED_PDF_USER_INPUT — user-provided PDF input was invalid
• KYC_FORM — a KYC form must be completed
• THIRD_PARTY_ERROR — the insurance provider returned an unexpected error
• TWO_FACTOR_METHOD_SELECTION_TIMEOUT — two-factor method selection was not completed in time
• WAITING_FOR_USER_ACTION — collection is paused until the user takes action

On CollectionStatusInformationMap:

• requiredInputTypes renamed to REQUIRED_INPUT_TYPES
• DANISH_NEM_ID_CARD_CODE_LOOKUP, SELECTED_TWO_FACTOR_METHOD removed

Action: Rename collectionStatus.insuranceCompany to collectionStatus.company. Rename informationMap.requiredInputTypes to informationMap.REQUIRED_INPUT_TYPES. Handle the new collection status values. At minimum, treat unknown statuses as non-terminal so your polling loop continues. Remove handling for DANISH_NEM_ID_CARD_CODE_LOOKUP and SELECTED_TWO_FACTOR_METHOD information map keys.

CompanyAvailability field renames

On CompanyAvailability:

• insuranceCompany renamed to company
• insuranceCompanyDisplayName renamed to companyDisplayName
• New field: companyGroup

Action: Rename insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName.

InsuranceCar coverage enum updated

On InsuranceCar, the coverage enum has changed:

• Removed: COMPREHENSIVE
• Added: THIRD_PARTY, THIRD_PARTY_PLUS

The insuranceLevel field has been removed.

Action: Replace any handling of COMPREHENSIVE with the appropriate new value. Remove usage of insuranceLevel.

InsuranceWrapper variants reduced

The InsuranceWrapper oneOf has been reduced from 12 variants to 8: InsuranceAnimal, InsuranceVehicle (oneOf InsuranceCar, InsuranceOtherVehicle), InsurancePerson, InsuranceHouseContent (oneOf InsuranceHome, InsuranceVilla), InsuranceIncome, InsuranceCottage, InsuranceFarm, InsuranceGeneral. The removed top-level types InsuranceAccident, InsuranceChild, InsurancePregnancy, and InsuranceLife are now sub-types of InsurancePerson, along with a new CoreInsurancePerson variant for generic person/health insurance. Market-specific types (e.g., DanishInsuranceCar, DanishInsuranceHome) have been folded into the base types with a @market discriminator field.

Action: If you previously matched on InsuranceAccident, InsuranceChild, InsurancePregnancy, or InsuranceLife as top-level wrapper variants, access them through the InsurancePerson wrapper instead. Handle the new CoreInsurancePerson variant. Use the @market field on insurance objects to determine market-specific behavior.

Item type enum scoped down

The type enum on Item (used for collection input requirements) has been reduced to: EMAIL, LOGIN_METHOD, PASSWORD, TWO_FACTOR_TOKEN, USERNAME.

Action: Remove handling for removed input types such as NORWEGIAN_PERSONAL_NUMBER, ESTONIAN_PERSONAL_NUMBER, UK_DATE_OF_BIRTH, etc.

New Features

Holder object

A new Holder object provides structured policyholder information, replacing the flat insuranceHolder* fields. This is available on all insurance types via the holder field.

Coverage object

A new Coverage object is available on FullInsuranceWrapper, providing structured coverage details.

New collection endpoints

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

Collection endpoint improvements

• The CollectionItem now uses id instead of externalId for clearer identification

New insurance object fields

Several insurance types have gained new fields for richer data:

• InsuranceCar: brand, model, registrationNo
• InsuranceOtherVehicle: brand, model, registrationNo
• Property types (InsuranceCottage, InsuranceFarm, InsuranceHome, InsuranceVilla): insuranceObjectCity, insuranceObjectPostalCode, insuranceObjectPropertyCode, insuranceObjectStreetAddress, livingArea, numberOfResidents, purchaseYear, and more

Migration Checklist

• Update Insurely-Version header to 2025-01-01
• Update all endpoint URLs from /insurance-collection/ to /insurance/collection/
• Update company availability endpoint from /insurance-company/status to /companies/availability
• Replace all insuranceHolder* field reads with the new holder object
• Update premium parsing: rename frequency to paymentFrequency (now integer), read amount as MonetaryAmount, remove taxation
• Update MonetaryAmount reads: minorUnitAmount to amount, currencyCode to currency
• Update all integer monetary fields to read from MonetaryAmount objects (e.g., discountAmount.amount)
• Replace externalId with id on collection items and insurance wrappers
• Rename insuranceCompany to company on CollectionStatus and CompanyAvailability
• Rename insuranceCompanyDisplayName to companyDisplayName on CompanyAvailability
• Rename requiredInputTypes to REQUIRED_INPUT_TYPES on CollectionStatusInformationMap
• Handle new collection status values (see full list above): ACCOUNT_TEMPORARILY_LOCKED, AUTHENTICATION_TIMEOUT, THIRD_PARTY_ERROR, WAITING_FOR_USER_ACTION, and others
• Update InsuranceCar coverage enum handling (COMPREHENSIVE removed, THIRD_PARTY/THIRD_PARTY_PLUS added)
• Move paymentMethod reads to premium.paymentMethod on DanishPremium
• Remove usage of deleted fields: premiumAmountYearRounded, premiumFrequency, insuranceLevel
• Update InsuranceWrapper handling: InsuranceAccident, InsuranceChild, InsurancePregnancy, InsuranceLife are now sub-types of InsurancePerson
• Remove handling for removed Item input types
• Test end-to-end collection flow with new endpoints and response shapes

Field Mapping Table