Migration Guide

Migrating from Wealth API 2024-06-01 to 2025-01-01

Summary

The 2025-01-01 version of the Wealth API removes the contact form input endpoint (replaced by the existing supplement-info endpoint), introduces new financial product types for savings accounts, adds ETF as a holding type, and extends pension and investment objects with new fields for transactions, sub-classifications, and protection details. Most changes are additive, but the endpoint removal and some enum/field changes require updates to your integration.

Breaking Changes

Endpoint removed: add-contact-form-input

The POST /wealth/collection/{collectionId}/add-contact-form-input endpoint has been removed. Contact form values should now be provided as a CollectionInput to the POST /wealth/collection/{collectionId}/supplement-info endpoint.

Action: Replace any calls to /wealth/collection/{collectionId}/add-contact-form-input with calls to /wealth/collection/{collectionId}/supplement-info, using the CollectionInput request body format.

Schema renamed: CollectionRequestV5 and CollectionStatusV5

The versioned schema names CollectionRequestV5 and CollectionStatusV5 have been replaced by CollectionRequest and CollectionStatus respectively. The ContactFormInput schema has also been removed (replaced by the supplement-info flow).

Action: Update any code that references CollectionRequestV5, CollectionStatusV5, or ContactFormInput to use the new schema names.

Item type enum reduced

The type field on Item has been significantly reduced. The following types have been removed: ESTONIAN_PERSONAL_NUMBER, ESTONIAN_PHONE_NUMBER, LASTNAME, LATVIAN_PERSONAL_NUMBER, LITHUANIAN_PERSONAL_NUMBER, LITHUANIAN_PHONE_NUMBER, MEMBERSHIP_NUMBER, NORWEGIAN_BANKID_OTP, NORWEGIAN_BANKID_PASSWORD, NORWEGIAN_FULL_PERSONAL_NUMBER, NORWEGIAN_PERSONAL_NUMBER, NORWEGIAN_PHONE_NUMBER, POSTCODE, REGION, TRADE_UNION_MEMBERSHIP, UK_DATE_OF_BIRTH.

The remaining valid types are: EMAIL, LOGIN_METHOD, MOBILE_PHONE_NUMBER, PASSWORD, SWEDISH_PERSONAL_NUMBER, TWO_FACTOR_TOKEN, USERNAME.

Action: If your integration handles any of the removed Item types, remove that logic. No other market-specific input types are returned in this version.

CollectionStatusInformationMap fields removed

The fields RESEND_CODE_THRESHOLD_SECONDS and NORWEGIAN_BANKID_WORDS have been removed from CollectionStatusInformationMap.

Action: Remove any handling of RESEND_CODE_THRESHOLD_SECONDS and NORWEGIAN_BANKID_WORDS from your status polling logic.

PensionManagementInstitution.name changed to enum

The name field on PensionManagementInstitution has changed from a free-text string to a fixed enum: Avtalat, Fora, Valcentralen, Pensionsvalet, SPV.

Action: If you were doing custom parsing or matching on the management institution name, update your logic to handle these specific enum values instead of arbitrary strings.

New Features

These are additive changes. Your existing integration will continue to work without handling them, but you may want to adopt them.

New product types: GeneralSavingsAccount and GeneralSavingsAccountFixedPeriod

Two new financial product types have been added to FinancialProduct:

• GeneralSavingsAccount -- a standard savings account with interest rates and withdrawal conditions.
• GeneralSavingsAccountFixedPeriod -- a fixed-period savings account with binding period and deposit details.

The type enum on all product schemas (ISK, KF, CustodyAccount, etc.) has been extended with GENERAL_SAVINGS_ACCOUNT and GENERAL_SAVINGS_ACCOUNT_FIXED_PERIOD.

Action: Add handling for these new product types if you want to display savings account data. At minimum, ensure your code does not break on unknown type values.

New holding type: ETF

ETF has been added as a possible value for type on Holding and TransactionInstrument.

Action: Add display handling for ETF holdings if desired.

New field: Holding.fundAccountNumber

A fundAccountNumber field has been added to Holding.

New field: Insurance.protectionDetails

A protectionDetails field has been added to Insurance, using the new ProtectionDetails schema.

New fields on pension types: subClassification, benefitType, and transactions

The following pension product types have new optional fields:

• subClassification added to: PensionCollectiveOccupational, PensionIPS, PensionOccupational, PensionPrivate, PensionUnknown
• benefitType added to: PensionCollectiveOccupational
• transactions added to: PensionCollectiveOccupational, PensionIPS, PensionOccupational, PensionPrivate, PensionUnknown, KF

New endpoint: GET /wealth/public-pension-collection

A new endpoint for initiating public pension data collections has been added.

Migration Checklist

• Update the Insurely-Version header to 2025-01-01
• Replace calls to /wealth/collection/{collectionId}/add-contact-form-input with /wealth/collection/{collectionId}/supplement-info
• Update references from CollectionRequestV5 / CollectionStatusV5 / ContactFormInput to the new schema names
• Remove handling of removed Item types (Norwegian, Estonian, Lithuanian, etc.)
• Remove handling of RESEND_CODE_THRESHOLD_SECONDS and NORWEGIAN_BANKID_WORDS from status information
• Update PensionManagementInstitution.name handling from free-text to enum values
• (Optional) Add support for GeneralSavingsAccount and GeneralSavingsAccountFixedPeriod product types
• (Optional) Add support for ETF holding and transaction instrument type
• (Optional) Use new GET /wealth/public-pension-collection endpoint for public pension data
• (Optional) Use new fields: protectionDetails, subClassification, benefitType, transactions, fundAccountNumber
• Verify your code handles unknown enum values gracefully (defensive parsing)

Field Mapping Table