Consumer Intelligence V3 released ¶

The Consumer Intelligence API has existed for over 7 years, and started out as a simple phone book service. It has since come a long way, and become a completely different product than it initially envisioned as. With all the knowledge we've gained over the years with our customers, we know that we can do better in terms of how we represent our APIs, for both existing and new customers.

In Consumer Intelligence API V3 we apply our learnings V2, and create an easier and more thoughtful API, that will ease integration for newcomers, and return more value for our existing customers.

With that said, let's dig in to what's new!

What's new in V3¶

Webhooks¶

V3 adds support of webhooks in order to subscribe to events within Consumer Intelligence. See our how-to guide on how to work with webhooks.

Imprecise dates always represented as dates with a precision¶

Imprecise dates has been reworked into something easier to consume for those integrating with our APIs. Instead of having separated fields for each date component, we have date field along with a precision field for those that need to understand the precision of an imprecise date.

Example of V2 imprecise date:

{
  "startDate": null,
  "startYear": 2024,
  "startMonth": 3,
  "startDay": null
}

Example of V3 imprecise date:

{
  "startDate": "2024-03-01",
  "startDatePrecision": "MONTH"
}

Note

Fall back values for date components may differ for different date fields, it will always fall back to the most conservative value depending on context.

For example, a birthDate of 2005-??-?? would result in an imprecise date of 2005-12-31. Whereas a deceasedDate of 2005-??-?? would result in an imprecise date of 2005-01-01.

New person data¶

New fields to the person object have been added to v3.

Field	Description
`estimatedAge`	The person's estimated age based on their date of birth and today's date (or date of death if person is deceased).
`possibleNicknames`	List of possible nicknames for the person based on the person's preferred first name and common nicknames for that name in the data provider's country.
`addresses.verified`	Indicates if the address has been validated and verified as an existing address.
`addresses.district`	Textual representation of the district.
`metadata.sources.market`	The country of which a data source operates in.
`status.missing`	New type of deregistered status.
`status.movedAbroad`	New type of deregistered status.

What's changed from V2¶

A full migration guide from V2 to V3 is available here.

Find replaces Search and Match¶

To simplify our onboarding product we've merged the Search and Match functionality from V2 into a single API, the Find API.

No more bulk operations

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

Bulk match operations is now referred to the Consumer API.

Get by GEDI is now only available for Monitoring¶

Get by GEDI is now only available for those with Monitoring access.

Person data model¶

The Person data model for V3 has been heavily reworked. Our goals have been:

Easy to find relevant information
Easy to interpret data
Reduce cognitive complexity

The result is quite major for those coming from V2, but we've collected a list of all changes to make it easier for you, as a user, to make the switch.

Enrichment variables¶

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>"
  }
}

See the migration guide for a detailed overview of removed and renamed enrichment variables.

Custom enrichment¶

Naming conventions for custom enrichment remain the same; however, the data model has changed slightly, with added support of a textual representation of a value (label).

Example

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

Custom enrichment can now be found at customEnrichment.*.