How to use the API
This guide is intended to help you get going with your integration against the Bisnode Consumer Intelligence API. It serves as a complement to the Endpoint Reference and aims to bring a high level understanding of the key concepts of the platform.
For questions and support, please contact Bisnode at email@example.com
A key concept in Bisnode Consumer Intelligence is the Generic Entity Data Identifier (GEDI) referred to as unique ID below. It is designed to be a unique, persistent identifier of entities within Bisnode.
To use any of the consumer data management functionality provided by this API, a step referred to as Connect is required. In practice this means obtaining a GEDI - for the persons of interest. Using the GEDI you can then download the available information for that person and continually receive updates as they occur.
There are three methods available to find the right GEDI for a Person: "Search“ (searchPersons), “Verify” (matchPersons) and "Match“ (matchPersons)
Search for a consumer via an integrated Point of Sales system, app or webpage Data such as "phone number", "first name, family name and date of birth" or “social security number (SE)” can be used as input. See endpoint reference for searchPersons.
Match existing customer databases and offline-registered customers to get the keys to connect to Bisnode’s services and data streams. See endpoint reference for matchPersons.
Download consumer data related to an identified person using the provided GEDI (unique persistent identifier). Default data or specific dataSlices can be provided. See endpoint reference for getPerson.
Monitor Changes Over Time
This process ensures you always have correct data on connected customers
Run periodically, set up by the integrator to support the business needs. Get changes from Bisnode, providing a since-date indicating when last update was queried. If helpful, analyze the updates to identify what properties that has been updated. Update the customer data with the updates. Remember the since-date received in the response, to be used in the next iteration.
Add one or more customers to your subscription list to monitor for changes over time. See endpoint reference for editList.
Download changes related to your monitored customers since last time. Default data or specific dataSlices can be provided. See endpoint reference for getChangedItems.
The Bisnode Consumer Intelligence API aims at providing unified consumer data regardless of market. However, due to contractual and legislative reasons, a few market specific limitations need to be considered.
Detailed information about request and response parameters per country can be found in the document BCI Request and Response Parameters. Other local difference that needs to be considered are listed below.
Data source lacks information about:
- Date of Birth
- Year of Birth
The search response are lacking streetNumber and postalCode, that information is retrieved through download request (get by GEDI/memento).
Data source lacks information about:
Monitoring finnish data
Access to monitoring individuals requires a signed contract between the customer and the Finnish government PRC (Population Register Center).
Since this service is provided by Finnish authorities (only supplier of this service) it has some differences in behavior:
- Match existing customers to get GEDIs.
- “ADD” GEDI + firstName*, familyName*, streetAddress* & postalCode* to editList endpoint (sourceCountry=FI)
- The submitted information will be forwarded to PRC (population register central) for monitoring.
- It will be match and added to monitoring list
- The first delivery in getChanges will be the full PRC record, it make take some time for PRC to perform the match and initial delivery.
- Future deliveries will be changed properties only and not full person objects**.
- Changes can only be stored during a period of 30 days. It is therefore important that you subscribe to changes on a higher frequency than that.
*Mandatory for Finland
**Note that we will never deliver full BCI person objects from Finnish monitoring. The first delivery will return a PRC record (firstName, familyName, streetAddress, postalCode, city), future changes will return changed properties only.
Sweden is the only country in which Legal ID (Swedish personal identity number) can be used as a request parameter during Search and Match. Legal ID will always guarantee the highest hit rate.
Search services is not available on Austrian data
Search service is not available on German data.
Phone number and year of birth are not a part of basic response, but can be added through the parameter dataSlice, reach out to your contact person at Bisnode for more information.
Information about request- and response parameters can be found in the document "BCI Request and Response Parameters".
Search services is not available on Belgian data.
The match service will not return any Belgian person information in the response but match-codes for validation of the input per field will be.