People Monitoring REST - Implementation guide

Terms

Term	Description
Datasource	Datasource is the origin of the data. Notice datasource is more or less technical term, and doesn't necessarily refer to a legal actor (e.g. vrk). Currently we support following datasources: Vrk: will contains all VRK related basic data (does not contain address history) Original: Original contains the data customer have delivered to Bisnode. In near future we will add support for following datasources: Snoy: will contain one phonenumber per person. Will be implemented later. Bric: Bric classification Predictions: Bisnode Prediction classes
Package	Package defined what data customer gets from datasources. Package is also used in billing.
Field	a field in data source
Operation	All change to your register are called operations. Currently following operations are supported: Upsert: Update or insert a person to register. Delete: Remove a person from register by using reference key
Operation batch	In order to change your information in register you must POST a operation batch to batch endpoint. Operation batch is an array of operations (see above).
Change batch	You you download changes from register you will get a change batch. Change batch is a snapshot of prepared changes from all datasets included in monitoring.
Reference Key	All person in the register must have unique reference key. If you don't give reference key, the service will generate it for the person.
BisnodeId	Bisnode id is Bisnode Finland's internal idenfier for a person. Bisnode id is used to track changes to person.
BisnodeGedi	Bisnode Gedi is Bisnode's corporate wide identifier for a person. If you use Bisnode services, for instance, in other nordic countries, you can use Bisnode Gedi as a reference to person.
Matching	Matching is a process where try to get BisnodeId for a person in the monitorable register.
Register Event	Register event is any changes to the data in register. Currently we have following events: Upsert: Update or insert data,will rematch if field related to the match are inluded in upsert object, see below Delete: Remove an item from register. Match start: Sent upserted items to match (if needed) Match end: Sent upserted items to match (if needed) Populate match results: Links BisnodeId to reference key if person matched. Notice this is billable action. We need to pay VRK for all additions to the register. Thus, if you resend address of same person this can be expensive. There are still some open details here. From customer point of view it would be better, if you did not prepare changes set immediately, but when customer next time prepared changes. E.g. consider case where new row is added to register on monday, row changes on tuesday and customer retrieves changes at wednesday, now it is not yet clear whether customer must pay for "addition to the register" and "change", or only "addition to the register". (When changes where delivered once per week this was not a relevant problem.) Prepare Changes: Get changes for identified persons. Notice prepare changes has two steps: Get changes for person that have been identified after given date (latest download date or explicitly given date) Get changes for persons whose monitored data have changes after given date (late download date or explicitly given date) There are some billing and regulation related details that are open at the moment. E.g. if persons phone number have changed, create snapshot of VRK data that have not changes. If we do so, customer must pay VRK for changes even if he have the last version of the data. This will be billable action, if customer does not actually download the data relating changes he prepares, he will be billed anyway. For VRK data customer has one month time to download the changes, after that he will not get the changes, but he will be charged anyway. Download Changes: download prepared changes. Notice we return last snapshot of all datasources if allowed by datasource retention rules. This means, that implementation should not presume that all datasources contains data.