Migration Guide

Migrating to 2025-01-01

Summary

This version introduces a major shift from plain integer amounts to structured MonetaryAmount objects across all insurance types, unifies the holder field into a single Holder schema (replacing the previous per-market oneOf variants), and consolidates market-specific schemas into shared objects. Several fields have been removed or relocated, and the insuranceCompany field has changed from a fixed enum to an open string.

Breaking Changes

1. Monetary fields changed from integer to MonetaryAmount

All fields that previously returned a bare integer now return a MonetaryAmount object with amount (number) and currency (string) properties.

Action: Update your parsing logic wherever you read these fields. Instead of accessing the value directly (e.g., discountAmount: 500), you now receive an object (e.g., discountAmount: { amount: 500, currency: "DKK" }).

Affected fields by insurance type:

2. MonetaryAmount field renamed: currencyCode to currency

The MonetaryAmount object's currencyCode field has been renamed to currency. The type has also changed from a string enum to an open string (still ISO 4217 values, but additional currencies may appear in the future).

Action: Replace all references to currencyCode with currency. If you validate against a fixed set of currency codes, update your validation to accept any ISO 4217 string.

3. holder changed from oneOf to unified Holder

The holder field on all insurance types previously used a oneOf with market-specific variants (e.g., DanishHolder). It is now a single Holder object with a flat structure containing name, email, phoneNumber, streetAddress, postalCode, city, otherInsuranceHolder, and @market.

Action: Remove any oneOf / discriminator logic for holder parsing. Access holder fields directly from the unified Holder object.

4. InsuranceCar coverage enum changed

On InsuranceCar, the coverage enum value COMPREHENSIVE has been removed.

Action: If you match on COMPREHENSIVE, remove that case.

5. Insured amount fields changed from integer to MonetaryAmount on person insurance types

The following fields that were previously plain integers are now MonetaryAmount objects on their respective insurance types:

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

6. CollectionRequestV5 renamed to CollectionRequest

The CollectionRequestV5 schema has been renamed to CollectionRequest. If you generate client code from the OpenAPI spec, update your type references.

7. Market-specific schemas consolidated

Per-market schemas such as DanishHolder, SwedishHolder, DanishInsuranceCar, SwedishInsuranceCar, etc. have been removed. Their fields are now included directly in the base objects (e.g., Holder, InsuranceCar) with a @market discriminator field.

Action: If you parsed specific market variant schemas, refactor to use the unified base objects. Use the @market field to determine market-specific behavior if needed.

8. insuranceCompany enum reduced

The insuranceCompany field on all insurance types has changed from a fixed enum to an open string. If you validated against a hardcoded set of company codes, update your validation.

9. CollectionStatusInformationMap field removed

The field RESEND_CODE_THRESHOLD_SECONDS has been removed from CollectionStatusInformationMap.

Action: Remove any references to this field.

10. Item.type enum reduced

The type field on Item has been reduced from 23 values to 5: EMAIL, LOGIN_METHOD, PASSWORD, TWO_FACTOR_TOKEN, USERNAME.

Action: If you match on any of the removed values (e.g., NORWEGIAN_BANKID_OTP, ESTONIAN_PERSONAL_NUMBER, UK_DATE_OF_BIRTH, etc.), remove those cases.

Migration Checklist

• Update Insurely-Version header to 2025-01-01
• Update all monetary field parsing to handle MonetaryAmount objects ({ amount, currency }) instead of plain integers
• Replace currencyCode references with currency in MonetaryAmount
• Refactor holder parsing from oneOf discriminated union to unified Holder object
• Remove handling for COMPREHENSIVE car coverage enum value
• Update insured amount fields on person insurance types (InsuranceAccident, InsuranceChild, InsuranceLife, InsurancePregnancy) from integer to MonetaryAmount
• Remove RESEND_CODE_THRESHOLD_SECONDS from collection status info handling
• Update Item.type enum handling to the reduced set of 5 values
• Rename CollectionRequestV5 to CollectionRequest in any generated client code
• Update insuranceCompany handling from fixed enum to open string
• Refactor any market-specific schema parsing (e.g., DanishHolder, DanishInsuranceCar) to use unified base objects with @market discriminator

Field Mapping Table