Migration Guide

Migrating from Pension API to Wealth API

Summary

The Pension API (2022-09-26) has been superseded by the Wealth API (2025-01-01), which covers pensions, investment accounts, savings accounts, loans, and more. This migration spans two version jumps: Pension 2022-09-26 to Wealth 2024-06-01, then Wealth 2024-06-01 to 2025-01-01. The major changes are: all endpoints have moved from /pension-collection/ to /wealth/collection/, the flat PensionData object has been split into typed product objects (e.g., PensionOccupational, PensionPrivate), monetary fields have been restructured as MonetaryAmount objects, and holder/organization data has been consolidated into a Holder object.

Breaking Changes

API renamed from Pension to Wealth

The Pension API has been replaced by the Wealth API, which is a superset covering pensions and additional financial product types. You must use the Wealth API endpoints and set Insurely-Version: 2025-01-01.

Action: Replace all Pension API calls with Wealth API equivalents. Update the Insurely-Version header to 2025-01-01.

Endpoint paths restructured

All /pension-collection/* and /insurance-company/* endpoints have been replaced with new paths under /wealth/collection.

Action: Update all endpoint URLs. The add-contact-form-input endpoint has been merged into supplement-info -- use CollectionInput as the request body. The collectionId for supplement-info is now a path parameter instead of a request body field.

PensionData replaced by typed product objects

The single PensionData object has been replaced by a FinancialProduct oneOf union with typed variants:

• PensionCollectiveOccupational
• PensionOccupational
• PensionPrivate
• PensionIPS
• PensionUnknown

The pensionType field is now type on each product, and pensionClassification is now classification.

Action: Update your data parsing to handle the oneOf product structure. Use the type field to determine which product variant you received.

Collection request schema renamed

CollectionRequestV2 is now CollectionRequest. The insuranceCompany field has been renamed to company. The ContactFormInput schema has been removed (use the supplement-info flow with CollectionInput instead).

Action: Update schema references and rename insuranceCompany to company in collection requests.

CollectionStatus field renames

On CollectionStatus:

• insuranceCompany renamed to company

• pollingInterval removed

• collectionItems removed

• status is now a strict enum with underscore-delimited values (e.g., COMPLETED_EMPTY instead of COMPLETED EMPTY)

• WAITING FOR AUTHENTICATION renamed to AUTHENTICATION_TIMEOUT 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 — replaces WAITING FOR AUTHENTICATION

• 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 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

Action: Rename insuranceCompany to company. Update status string matching to use the new underscore-delimited enum values. Handle the new status values. At minimum, treat unknown statuses as non-terminal so your polling loop continues.

CollectionStatusInformationMap changes

On CollectionStatusInformationMap:

• requiredInputTypes renamed to REQUIRED_INPUT_TYPES
• Removed: AUTOSTART_TOKEN, DANISH_NEM_ID_CARD_CODE_LOOKUP, NORWEGIAN_BANKID_WORDS

Action: Rename requiredInputTypes to REQUIRED_INPUT_TYPES. Remove handling for AUTOSTART_TOKEN, DANISH_NEM_ID_CARD_CODE_LOOKUP, and NORWEGIAN_BANKID_WORDS.

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.

Policyholder fields moved to Holder object

The flat insuranceHolderName and insuranceHolderOrgNumber fields, along with organizationAlternatives and insuranceHolderOrganization, have been consolidated into a Holder object with name, organization, and organizationSuggestions sub-objects.

Action: Replace insuranceHolderName with holder.name. Replace insuranceHolderOrganization reads with holder.organization. Replace organizationAlternatives with holder.organizationSuggestions. Remove insuranceHolderOrgNumber and insuranceHolderOrgTurnover reads (these have been removed).

Fee fields grouped into Fees object

The flat feeFixed, feeVariable, feesCollected, and feesPreviousYear fields on PensionData have been grouped into a Fees object. Additionally, feeFixed and feesPreviousYear are now MonetaryAmount objects instead of plain numbers.

Action: Replace pension.feeFixed with product.fees.feeFixed.amount. Replace pension.feesPreviousYear with product.fees.feesPreviousYear.amount.

Financial data grouped into ProductFinancialInformation

The currentValue and totalPaid fields have been moved into ProductFinancialInformation and are now MonetaryAmount objects. totalPaid has been renamed to totalDeposits.

Action: Replace pension.currentValue with product.financialInformation.currentValue.amount. Replace pension.totalPaid with product.financialInformation.totalDeposits.amount.

MonetaryAmount structure changed

The MonetaryAmount object has been restructured:

• minorUnitAmount (long, minor units) replaced by amount (decimal, major units)
• currencyCode replaced by currency (type changed from string enum to open 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.

Holdings restructured

The holding array has been renamed to holdings. Individual holdings have changed:

• shareCount renamed to quantity
• value changed from number to MonetaryAmount
• currencyCode removed (currency is now on each MonetaryAmount)
• feeFixed removed
• valueInPercent removed
• New fields: type (EQUITY, FUND, ETF, UNKNOWN), acquisitionValue, fundAccountNumber, marketIdentifierCode

Action: Rename holding to holdings, shareCount to quantity, and update value reads to use .amount and .currency.

Insurance-related fields grouped into Insurance object

hasSurvivorsProtection is now insurance.survivorsProtection and insuredPersonName is now insurance.insuredPersonName, grouped under the Insurance object.

Action: Replace pension.hasSurvivorsProtection with product.insurance.survivorsProtection. Replace pension.insuredPersonName with product.insurance.insuredPersonName.

Movability management institutions moved

The movability.managementInstitutions array has been moved to a top-level managementInstitutions field on the product. It is now included for all pensions of type COLLECTIVE_OCCUPATIONAL_PENSION with a known classification, not just movable pensions. The movability.evaluatedRules field has been removed. The movability.result enum has new values: MOVABLE_VALCENTRAL and MOVABLE_MEETING.

Action: Replace pension.movability.managementInstitutions with product.managementInstitutions. Remove any usage of movability.evaluatedRules. Handle the new movability.result values.

insuranceBeneficiaryName removed

The insuranceBeneficiaryName field has been removed with no replacement.

Action: Remove any usage of insuranceBeneficiaryName.

Item type enum reduced

The type field for collection input items has been reduced to Swedish-market values only: EMAIL, LOGIN_METHOD, MOBILE_PHONE_NUMBER, PASSWORD, SWEDISH_PERSONAL_NUMBER, TWO_FACTOR_TOKEN, USERNAME.

Action: Remove handling for non-Swedish input types (Norwegian, Estonian, Lithuanian, Latvian, UK, etc.).

Login methods scoped to Swedish market

The loginMethod enum on CollectionRequest has been reduced to Swedish-market methods only (e.g., SWEDISH_MOBILE_BANKID_*, SWEDISH_SECURITY_TOKEN, EMAIL). Non-Swedish login methods have been removed.

Action: Remove handling for non-Swedish login methods (Danish, Estonian, Latvian, Lithuanian, Norwegian, UK) and generic methods (PDF_UPLOAD, MANUAL_SELECT, USERNAME_AND_PASSWORD).

New Features

Additional financial product types

The Wealth API supports product types beyond pensions:

• ISK, KF, CustodyAccount -- investment accounts
• LoanMortgage, UnsecuredLoan -- loan products
• GeneralSavingsAccount, GeneralSavingsAccountFixedPeriod -- savings accounts
• PublicPension -- public pension data

Public pension collection endpoint

A new GET /wealth/public-pension-collection endpoint has been added for initiating public pension data collections.

New pension fields

• subClassification on all pension types
• benefitType on PensionCollectiveOccupational
• transactions on all pension types and KF
• insurance.protectionDetails with family/repayment/survivors protection details

New collection status values

Many new status values have been added to CollectionStatus — see the Breaking Changes section above for the full list.

Migration Checklist

• Update Insurely-Version header to 2025-01-01
• Replace all /pension-collection/* endpoints with /wealth/collection/* equivalents
• Replace /insurance-company/status with /companies/availability
• Merge add-contact-form-input calls into supplement-info using CollectionInput
• Update data parsing from single PensionData to typed FinancialProduct variants
• Rename insuranceCompany to company in collection requests, statuses, and company availability
• Rename insuranceCompanyDisplayName to companyDisplayName
• Update CollectionStatus.status string matching to underscore-delimited enum values
• Handle new collection status values (see full list above): ACCOUNT_TEMPORARILY_LOCKED, AUTHENTICATION_TIMEOUT, THIRD_PARTY_ERROR, WAITING_FOR_USER_ACTION, and others
• Rename requiredInputTypes to REQUIRED_INPUT_TYPES on CollectionStatusInformationMap
• Migrate insuranceHolderName to holder.name and organization fields to holder.organization
• Move fee field reads to the fees sub-object; update feeFixed/feesPreviousYear to MonetaryAmount
• Move currentValue/totalPaid reads to financialInformation; rename totalPaid to totalDeposits
• Update MonetaryAmount reads: minorUnitAmount to amount, currencyCode to currency
• Rename holding to holdings, shareCount to quantity, update value to MonetaryAmount
• Move hasSurvivorsProtection to insurance.survivorsProtection
• Move movability.managementInstitutions to top-level managementInstitutions; remove movability.evaluatedRules; handle new movability.result values
• Remove insuranceBeneficiaryName, holding[].currencyCode, holding[].feeFixed, holding[].valueInPercent
• Remove handling for non-Swedish login methods, generic methods (PDF_UPLOAD, MANUAL_SELECT, USERNAME_AND_PASSWORD), and non-Swedish input types
• (Optional) Handle new product types: ISK, KF, CustodyAccount, loans, savings accounts
• (Optional) Use new fields: subClassification, benefitType, transactions, protectionDetails
• Test end-to-end collection flow with new endpoints and response shapes

Field Mapping Table

Pension Data Fields

Holdings Fields

Organization Fields

Endpoint Mapping

Collection & Status Fields