Migration Guide

Migrating to 2025-01-01

Summary

This migration covers three version jumps (2021-01-01 -> 2023-03-15 -> 2024-06-01 -> 2025-01-01) and includes significant restructuring of the API. The collection endpoints have been reorganized under a new /insurance/collection path, policyholder fields have been consolidated into a dedicated Holder object, monetary integer fields have been replaced with MonetaryAmount objects, and the Premium structure has changed to a oneOf polymorphic type.

Breaking Changes

Endpoint paths restructured

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

Action: Update all endpoint URLs in your integration according to the mapping below.

Policyholder fields moved to Holder object

The insuranceHolder* fields and otherInsuranceHolder have moved from individual insurance objects into a new Holder object, accessible via the holder field on each insurance type:

• insuranceHolderName → holder.name
• insuranceHolderEmail → holder.email
• insuranceHolderPhoneNumber → holder.phoneNumber
• insuranceHolderStreetAddress → holder.streetAddress
• insuranceHolderPostalCode → holder.postalCode
• insuranceHolderCity → holder.city
• otherInsuranceHolder → holder.otherInsuranceHolder

The fields insuranceHolderDateOfBirth, insuranceHolderGender, and insuranceHolderOccupation have been removed entirely with no replacement.

Action: Replace all reads of insuranceHolder* fields with the equivalent fields on the holder object. For example, change insurance.insuranceHolderName to insurance.holder.name and insurance.otherInsuranceHolder to insurance.holder.otherInsuranceHolder.

Removed fields from Insurance base object

The following fields have been removed from Insurance and all insurance type objects:

• externalId
• paymentMethod
• premiumAmountYearRounded
• premiumFrequency
• discountAmount
• discountPercentage
• renewalDate

Action: Remove any references to these fields. Premium frequency and amount information is now available through the restructured Premium object.

MonetaryAmount structure changed

The MonetaryAmount object has been restructured:

• currencyCode has been renamed to currency (type changed from string enum to string, still ISO 4217)
• minorUnitAmount (long, minor units) has been replaced by amount (decimal, major units)

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.

Integer monetary fields changed to MonetaryAmount

Multiple fields across insurance types that were previously plain integer values are now MonetaryAmount objects with amount and currency fields. This affects:

• veterinaryCareAmount, veterinaryCareAmountRemaining on InsuranceAnimal (note: animalPurchasePrice has been removed entirely)
• insuredMovablesAmount on InsuranceCottage, InsuranceHome, InsuranceVilla
• insuredAmount and insuredMonthlyAmount on InsuranceIncome
• insuredAmountBaseEconomicalDisability, insuredAmountBaseMedicalDisability, insuredAmountLife, insuredAmountMaxMedicalDisability on InsuranceAccident, InsuranceChild
• insuredAmountLife on InsuranceLife
• insuredAmountBaseMedicalDisability on InsurancePregnancy

Note: insuredMovablesAmount on InsuranceFarm remains an integer.

Action: Update all reads of these fields from field (integer) to field.amount (number) and field.currency (string).

Premium structure changed

The Premium object has changed from a flat object to a oneOf polymorphic type with market-specific variants.

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 moved to FrenchPremium (still available in FR)

Action: Update your Premium parsing logic to handle the new polymorphic structure. Rename premium.frequency to premium.paymentFrequency and update the type from string enum to integer. Read premium.amount as a MonetaryAmount object. Access taxation via the FrenchPremium variant.

InsuranceCar coverage enum changed

On InsuranceCar, the coverage enum value COMPREHENSIVE has been removed and THIRD_PARTY and THIRD_PARTY_PLUS have been added.

Action: Update any logic that checks for the COMPREHENSIVE coverage value. Map it to the appropriate new value (THIRD_PARTY or THIRD_PARTY_PLUS) based on your use case.

Removed fields on specific insurance types

• insuranceLevel removed from InsuranceCar

Action: Remove any references to these fields in your code.

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., FrenchInsuranceCar, FrenchInsuranceHome) have been folded into the base types with a @market discriminator field.

Action: Update your insurance type handling logic. 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.

CompanyAvailability field renames

On CompanyAvailability:

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

Action: Update field references from insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName.

CollectionStatus information map changes

The CollectionStatusInformationMap has new keys and removed keys:

• Added: AVAILABLE_TWO_FACTOR_METHODS, INSTRUCTIONS, REFERENCE_NUMBER, REQUIRED_INPUT_TYPES, RESEND_CODE_THRESHOLD_SECONDS, TWO_FACTOR_AUTHENTICATION_INSTRUCTION
• Removed: SELECTED_TWO_FACTOR_METHOD

Action: Update your status polling logic to handle the new information map keys. The two-factor authentication flow has been restructured around the new AVAILABLE_TWO_FACTOR_METHODS and TWO_FACTOR_AUTHENTICATION_INSTRUCTION keys.

New Features

New collection endpoints

• DELETE /insurance/collection/{collectionId} — delete a collection and its associated data
• GET /insurance/collection/{collectionId}/policy/{policyId}/document/{documentId} — download policy documents

New collection status values

The CollectionStatus status enum includes many new values that your status-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

Action: Ensure your status-polling logic handles these new values gracefully. At minimum, treat unknown statuses as non-terminal so your polling loop continues.

Holder object

The new Holder object provides a structured representation of the policyholder, replacing the flat insuranceHolder* fields.

Coverage and document objects

New Coverage and ApiCoverageDocument objects on FullInsuranceWrapper provide structured coverage details and associated documents.

Additional fields on insurance types

• brand, model, registrationNo added to InsuranceCar and InsuranceOtherVehicle
• Property details (insuranceObjectCity, insuranceObjectPostalCode, insuranceObjectStreetAddress, livingArea, numberOfResidents) added to InsuranceHome, InsuranceCottage, and InsuranceVilla
• Extended property fields (additionalBuildings, ancillaryArea, constructionYear, hasBasement, numberOfBathrooms, numberOfFloors, purchaseYear, rental, farmProperties) added to InsuranceFarm
• Extended property fields (additionalBuildings, hasBasement, numberOfBathrooms, numberOfFloors, purchaseYear, rental) added to InsuranceVilla

Migration Checklist

• Update Insurely-Version header to 2025-01-01
• Update all endpoint URLs from /insurance-collection/* to /insurance/collection/*
• Replace /insurance-company/status and /insurance-collection/get-parameters with /companies/availability
• Update insuranceCompany to company and insuranceCompanyDisplayName to companyDisplayName in company availability responses
• Migrate all insuranceHolder* field reads to the new holder object
• Remove references to externalId, paymentMethod, premiumAmountYearRounded, and premiumFrequency
• Update all integer monetary fields to read from MonetaryAmount objects (.amount and .currency)
• Rename currencyCode to currency in any existing MonetaryAmount handling
• Update premium parsing: rename frequency to paymentFrequency (now integer), read amount as MonetaryAmount, access taxation via FrenchPremium
• Replace COMPREHENSIVE with THIRD_PARTY or THIRD_PARTY_PLUS in car coverage logic
• Update InsuranceWrapper handling: InsuranceAccident, InsuranceChild, InsurancePregnancy, InsuranceLife are now sub-types of InsurancePerson
• Update two-factor authentication flow to use new CollectionStatusInformationMap keys
• Handle new collection status values (see full list above): ACCOUNT_TEMPORARILY_LOCKED, AUTHENTICATION_TIMEOUT, THIRD_PARTY_ERROR, WAITING_FOR_USER_ACTION, and others
• Remove references to insuranceLevel (car)

Field Mapping Table