Migrate from V2 to V3¶

Data Coverage¶

Find replaces Match and Search¶

The Find API V3 replaces the existing functionality of Search and Match APIs in V2.

The endpoint /markets/SE/persons/_find represents an API endpoint in Consumer Intelligence (CI) used to search for individuals in a specific market. In this instance, the specific market is Sweden, denoted by the country code SE. Other markets could be represented, for example, by the country codes NO, DK, FI.

To search within a market, the client must have the necessary permissions.

Endpoint V2	Endpoint V3
`GET:/v2/person/search`	`POST:/v3/markets/{market}/persons/_find`
`POST:/v2/person/match`	`POST:/v3/markets/{market}/persons/_find`

No more bulk operations

Synchronous match operations in bulk (more than one match query per request) are no longer supported.

Subscription replaces Portfolio and List¶

Consumer Intelligence (CI) version 3 simplifies the subscription process by allowing you to manage subscriptions with a single API call (postConsumers) to the upload consumers API. This eliminates the need for the two-step process required in v2.

Endpoint V2	Endpoint V3
`PUT:/v2/portfolio/{portfolioId}/record/{clientReferenceId}`	`POST:/v3/consumers`
`DELETE:/v2/portfolio/{portfolioId}/record/{clientReferenceId}`	`DELETE:/v3/consumers`
`GET:/v2/portfolio/{portfolioId}/record/{clientReferenceId}`	Not yet available
`GET:/v2/portfolio/{portfolioId}/records`	`GET:/v3/consumers`
`GET:/v2/list/{listId}`	`GET:/v3/subscriptions/persons`

Person data changes¶

Field V2	Field V3
`lastModified`	`metadata.updatedTimestamp`
`sourceList`	`metadata.sources.name`
`person.gedi`	Removed
`person.legalId.socialSecurityNumberTemporary`	`legalId.temporary`
`person.legalId.socialSecurityNumberValidityPeriod`	`legalId.validityPeriod`
`person.deprecatedLegalIds`	`legalId.history`
`person.protectedIdentity`	`status.protected`
`person.diplomaticImmunity`	`diplomaticImmunity`
`person.firstNames`	`firstNames`
`person.preferredFirstName`	`preferredFirstName`
`person.additionalName`	`additionalName`
`person.familyName`	`familyName`
`person.honorificPrefix`	`honorificPrefix`
`person.honorificSuffix`	`honorificSuffix`
`person.shortenedFullName`	`shortenedFullName`
`person.gender`	`gender`
`person.dateOfBirth`	`birthDate`
`person.yearOfBirth`	`birthDate`
`person.deceased`	`status.deceased`
`person.dateOfDeath`	`status.deceasedDetails.deceasedDate`
`person.yearOfDeath`	`status.deceasedDetails.deceasedDate`
`person.foundDeadDate`	`status.deceasedDetails.foundDeadDate`
`person.communicationLanguageScript`	`languageTag`
`person.directMarketingRestriction`	`directMarketingRestriction`
`person.charityMarketingRestriction`	`charityMarketingRestriction`
`person.onlineMarketingRestriction`	`onlineMarketingRestriction`
`person.phoneList.type`	`phoneNumbers.type`
`person.phoneList.number`	`phoneNumbers.number`
`person.phoneList.telemarketingRestriction`	`phoneNumbers.telemarketingRestriction`
`person.placeOfBirth`	`placeOfBirth` (see below for address changes)
`person.addressList.type`	`addresses.postal`¹
`person.addressList.subType`	`addresses.type`²
`person.addressList.restricted`	`addresses.restricted`
`person.addressList.careOf`	`addresses.careOf`
`person.addressList.streetName`	`addresses.streetName`
`person.addressList.streetNumber`	`addresses.streetNumber`
`person.addressList.entrance`	`addresses.entrance`
`person.addressList.apartment`	`addresses.apartment`
`person.addressList.floor`	`addresses.floor`
`person.addressList.postOfficeBox`	`addresses.postOfficeBox`
`person.addressList.postalCode`	`addresses.postalCode`
`person.addressList.city`	`addresses.city`
`person.addressList.areaId`	Removed
`person.addressList.county`	`addresses.county`
`person.addressList.countyCode`	`addresses.countyCode`
`person.addressList.districtCode`	`addresses.districtCode`
`person.addressList.locality`	Removed
`person.addressList.municipality`	`addresses.municipality`
`person.addressList.municipalityCode`	`addresses.municipalityCode`
`person.addressList.province`	Removed
`person.addressList.region`	`addresses.region`
`person.addressList.xcoordinate`	`addresses.longitude`
`person.addressList.ycoordinate`	`addresses.latitude`
`person.addressList.country`	`addresses.countryCode`
`person.addressList.dispatchingInformation`	`addresses.dispatchingInformation`
`person.addressList.fullStreetAddress`	`addresses.baseAddressLines`³
`person.addressList.formattedAddress`	`addresses.postalFormattedAddress`
`person.addressList.propertyDetails.addressId`	`addresses.addressId`
`person.addressList.propertyDetails.addressCode`	`addresses.municipalAddressCode`
`person.addressList.propertyDetails.areaIdChurch`	`addresses.parishCode`
`person.addressList.propertyDetails.areaIdElection`	`addresses.constituencyCode`
`person.addressList.propertyDetails.areaIdSchool`	`addresses.schoolDistrictCode`
`person.addressList.propertyDetails.buildingType`	`addresses.buildingType`
`person.addressList.propertyDetails.propertyIdentification`	`addresses.cadastralIndexCode`
`person.relationshipList.hierarchicalRelationship=Beneficiary`	`relationships.beneficiaries`
`person.relationshipList.hierarchicalRelationship=Child`	`relationships.children`
`person.relationshipList.hierarchicalRelationship=LegalCustodian`	`relationships.custodians`
`person.relationshipList.hierarchicalRelationship=LegalGuardian`	`relationships.guardians`
`person.relationshipList.hierarchicalRelationship=Parent`	`relationships.parents`
`person.relationshipList.hierarchicalRelationship=Trustee`	`relationships.trustees`
`person.relationshipList.hierarchicalRelationship=Ward`	`relationships.wards`
`person.relationshipList.nonHierarchicalRelationship`	`relationships.partners`
`person.relationshipList.guardianshipType`	`relationships.guardians.type`
`person.relationshipList.startDate`	`relationships.*.validityPeriod.startDate`
`person.relationshipList.endDate`	`relationships.*.validityPeriod.endDate`
`person.relationshipList.legalId`	`relationships.*.legalId`
`person.relationshipList.firstNames`	`relationships.*.firstNames`
`person.relationshipList.preferredFirstName`	`relationships.*.preferredFirstName`
`person.relationshipList.additionalName`	`relationships.*.additionalName`
`person.relationshipList.familyName`	`relationships.*.familyName`
`person.relationshipList.honorificPrefix`	`relationships.*.honorificPrefix`
`person.relationshipList.honorificSuffix`	`relationships.*.honorificSuffix`
`person.relationshipList.dateOfBirth`	`relationships.*.birthDate`
`person.relationshipList.gender`	`relationships.*.gender`
`person.relationshipList.dateOfDeath`	`relationships.*.deceasedDate`
`person.relationshipList.citizenship`	`relationships.*.citizenship`
`person.relationshipList.deregistered`	Removed
`person.relationshipList.deceased`	`relationships.*.deceased`
`person.relationshipList.deregisteredReason`	Removed
`person.deceasedEstates`	`relationships.estateParties`
`person.deregistered`	`status.*`⁴
`person.merged`	`status.merged`
`person.removed`	`status.removed`
`person.seeOther`	`status.mergedDetails`
`person.relocationEvents`	`relocationEvents`
`person.futureAuthorization`	`authority.futureLegalAuthorization`
`person.identificationClaim`	`authority.identificationClaim`
`person.citizenship`	`citizenship`
`person.civilStatus`	`maritalStatus`
`person.deregisteredReason`	`status.*.baseReason`⁴
`person.deregisteredDate`	`status..Date`⁴
`person.underage`	`minor`
`person.lastModifiedSource`	`metadata.sources.updatedTimestamp`

Enrichment changes¶

Enrichment has also undergone quite major changes, both in naming and presentation. The enrichment variable model has changed for an easier interpretation of the values, but with same semantics as before.

globalValue has split into harmonizedValue and harmonizedLabel
description has been removed
localValue has split into baseValue and baseLabel
precision has been renamed to basePrecision

Example

{
  "<enrichmentVariableName>": {
    "harmonizedValue": "<the harmonized value across all countries>",
    "harmonizedLabel": "<textual representation of the harmonized value>",
    "baseValue": "<the base value of the variable from the person's country>",
    "baseLabel": "<textual representation of the base value>",
    "basePrecision": "<precision of the base value>"
  }
}

A description of variable changes is described in the following table:

Enrichment variable V2	Enrichment variable V3
`purchasingPower`	Removed
`phaseOfLife`	Removed
`housingType`	Removed
`education`	Removed
`housingOwnership`	Removed
`carOwner`	`ownsCar`
`householdId`	`householdId`
`automotive.carOwner`	`ownsCar`
`automotive.carCount`	Removed
`automotive.caravanOwner`	`ownsCaravan`
`automotive.camperOwner`	`ownsCamper`
`automotive.electricCarOwner`	`carTypeElectric`
`automotive.hybridCarOwner`	`carTypeHybrid`
`automotive.electricMopedOwner`	`carElectricMoped`
`automotive.carTypePremium`	`carTypePremium`
`automotive.carTypeFamily`	`carTypeFamily`
`automotive.carTypeSedan`	`carTypeSedan`
`automotive.carTypeMidsize`	`carTypeMidsize`
`automotive.carTypeSmall`	`carTypeSmall`
`automotive.carTypeSUV`	`carTypeSUV`
`automotive.carTypeCab`	`carTypeCab`
`automotive.carTypeOther`	`carTypeOther`
`automotive.moreThanOneCar`	`ownsMultipleCars`
`automotive.newCarProbability`	Removed
`automotive.typeOfCar`	Removed
`behavioral.cruiseAffinity`	Removed
`behavioral.culturalCapital`	Removed
`behavioral.electionResults`	Removed
`behavioral.impulsiveness`	`behaviorImpulsive`
`behavioral.newCarBuyer`	`newCarBuyer`
`behavioral.installmentAffinity`	`behaviorInstallment`
`behavioral.perceivedPurchasingPower`	`perceivedPurchasingPower`
`behavioral.consumption`	`behaviorConsumption`
`behavioral.culturalClass`	`culturalClass`
`behavioral.financialClass`	`financialClass`
`behavioral.mailOrderAffinity`	`behaviorMailOrder`
`behavioral.profileNewspaper`	`behaviorNewspaper`
`behavioral.profileOnlineMedia`	`behaviorOnlineMedia`
`carPrediction.carPurchasePrediction`	`carPurchasePrediction`
`carPrediction.carPurchasePredictionUsed`	`carPurchasePredictionUsed`
`charity.charityScore`	`charityScore`
`company.companyRole`	`companyRole`
`company.companyBoard`	`companyBoard`
`company.companyCEO`	`companyCEO`
`company.companyOther`	`companyOther`
`eCommerce.eCommerceScore`	`eCommerceScore`
`employment.unemployment`	Removed
`family.noOfChildren`	Removed
`family.personsInHousehold`	`personsInHousehold`
`family.personsInHousehold18plus`	`personsInHousehold18Plus`
`family.personsInHousehold18to24`	`personsInHousehold18To24`
`family.probabilityChildren0to6`	`probabilitySmallChildren`
`family.probabilityChildren0to17`	`probabilitySmallChildren` & `probabilitySchoolChildren`
`family.probabilityChildren10to17`	`probabilitySchoolChildren`
`family.probabilityChildren13to17`	`probabilitySchoolChildren`
`family.probabilityChildren7to12`	`probabilitySchoolChildren`
`family.probabilityChildren7to17`	`probabilitySchoolChildren`
`family.relationshipStatus`	Removed
`finance.consumerCredit`	Removed
`finance.familyAssets`	`incomeFamilyAsset`
`finance.familyIncome`	`incomeFamily`
`finance.monthlyIncome`	Removed
`finance.personAssets`	`incomePersonAssets`
`finance.personIncome`	`incomePerson`
`finance.assets`	Removed
`finance.mortgageLoan`	Removed
`finance.sharePaymentRemark`	Removed
`finance.disposableShare`	`incomeDisposableShare`
`finance.housingExpense`	`spendHousing`
`finance.housingValue`	Removed
`finance.livingExpense`	`spendLiving`
`area.areaId`	`areaId`
`area.coastal`	`areaCoastal`
`area.foreignBorn`	`areaShareForeignBorn`
`area.inboundMoving`	`areaInboundMoving`
`area.taxrate`	`taxRate`
`area.neighborhoodDensity100m`	Removed
`area.urbanization`	`urbanization`
`area.areaType`	Removed
`household.householdId`	`householdId`
`housing.housingGarden`	Removed
`housing.housingOwner`	`ownsHousing`
`housing.ownsVacationHome`	`ownsVacationHome`
`housing.ownsResidenceType`	Removed
`housing.propertyOwnership`	`ownsProperty`
`housing.vacationHomeOwner`	Removed
`lifestyle.ageInterval`	`ageInterval`
`lifestyle.housingCooperative`	Removed
`lifestyle.typeOfHousing`	`housingType`
`lifestyle.lifeStage`	`lifeStage`
`lifestyle.purchasePower`	`purchasingPower`
`lifestyle.singmulthousehold`	Removed
`lifestyle.levelOfEducation`	`levelOfEducation`
`lifestyle.educationYears`	Removed
`move.firstTimeMover`	`moveFirstTime`
`move.householdMoved`	`moveHousehold`
`move.somebodyMovedIn`	`moveIntoHousehold`
`movePrediction.predictedMove`	`movePrediction`
`personas.partnerpersona`	Removed
`personas.persona`	Removed
`reliability.reliabilityScore`	`reliabilityScore`
`modelling.principalComponent1`	Removed
`modelling.principalComponent2`	Removed
`modelling.principalComponent3`	Removed
`modelling.principalComponent4`	Removed
`modelling.principalComponent5`	Removed
`modelling.lifePhase`	Removed
`cameo.cameoType`	Removed
`cameo.cameoGroup`	Removed
`eventHouse.moveToHouse1`	`moveToHouse1`
`eventHouse.moveToHouse6`	`moveToHouse6`
`eventHouse.moveToHouse6`	`moveToHouse12`
`eventCouple.singleToCouple1`	`singleToCouple1`
`eventCouple.singleToCouple6`	`singleToCouple6`
`eventCouple.singleToCouple12`	`singleToCouple12`
`eventApartment.moveToApartment1`	`moveToApartment1`
`eventApartment.moveToApartment6`	`moveToApartment6`
`eventApartment.moveToApartment12`	`moveToApartment12`
`wallet.groceryWallet`	`spendGroceries`
`wallet.savingsPotentialEstimate`	`savingsPotentialEstimate`
`wallet.savingsRegularPotential`	`savingsRegularPotential`
`wallet.savingsPensionEstimate`	`savingsPensionEstimate`
`wallet.capitalStockEstimate`	`savingsCapitalEstimate`
`eventArea.moveToUrbanization1`	`moveToUrbanization1`
`eventArea.moveToUrbanization6`	`moveToUrbanization6`
`eventArea.moveToUrbanization12`	`moveToUrbanization12`
`coordinates.xCoordinate`	Removed
`coordinates.yCoordinate`	Removed
`coordinates.xcoordinate`	Removed
`coordinates.ycoordinate`	Removed

Custom enrichment¶

Naming conventions for custom enrichment remain the same; however, the data model has changed slightly, with added support of labels.

Example

{
  "customAlphaNum1": {
    "value": "<value of the custom enrichment variable>",
    "label": "<textual representation of the value>"
  }
}

Custom enrichment can now be found at customEnrichment.*.

Flag replaces type=Postal in V2. ↩
NoDomicile has been renamed to TEMPORARY. ↩
Base address from source, either split by newline separator or gathered from addressLine1...addressLineN. ↩
deregistered is split into more specific reasons such as merged, missing, movedAbroad, removed. Only one type of status can be active at the same time, e.g. status.removed=true, status.movedAbroad=true, status.missing=true, status.merged=true with potential details in status.*Details. The path will depend on the type, a reason for a missing status might thus have the path status.missingDetails.baseReason and date status.missingDetails.missingDate. Similarly the status removed will look like status.removedDetails.baseReason and corresponding date status.removedDetails.removedDate. ↩↩↩