How to deploy people register monitor service

Step 1: Initialize service for your register

Contact Bisnode Sales department [email protected]i. Your salesperson at Bisnode will help you with all necessary permits and provide the credentials to the People Register Monitor Service.

Once PRC (Population Register Centre) grants a permit, you will receive RegisterID and API key to the test and production environment to start the implementation.

Example

Test environment:
· Service base url: https://api-test.bisnode.fi/people/register-monitor/v2
· Swagger API documentation: https://api-test.bisnode.fi/people/register-monitor/v2/swagger
· Register Id: 10
· API key: 12345678900987654321EROISA

Production environment:
· Service base url: https://api.bisnode.fi/people/register-monitor/v2
· Register Id: 12
· API key: EFGDSOSI12345678900987654321

Step 2: Implement integration on your system(s)

1. How to upload new persons to the register for monitoring. See section "How to implement data upload and delete person to register?".
2. How to get changes relating the persons already in monitoring. See section “How to implement data download?”.

Notice: During development, you should use test environment even if you have production credentials available. Production environment is always subject to charge negotiated in the contract.

Simple example flow

1. Load the first batch using _op = Upsert, POST register/{registerId}/batch. The batch should not be larger than what you can retrieve from the items endpoint at a time. Save the response message correlationId.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'x-api-key: {x-api-key}' -d '[ \
{ \
"_op": "Upsert", \
"referenceKey": "FI2101010969659", \
"firstName": "Anna Minna", \
"lastName": "Meikäläinen", \
"streetAddress": "Birkanpolku 15 R 44", \
"postOffice": "VANTAA", \
"postCode": "01200" \
}, \
{ \
"_op": "Upsert", \
"referenceKey": "FI2101010969658", \
"firstName": "Yjö Veikko", \
"lastName": "Svensson", \
"streetAddress": "Birkanpolku 15 R 44", \
"postOffice": "VANTAA", \
"postCode": "01200" \
} \
]' 'https://api-test.bisnode.fi/people/register-monitor/v2/register/{registerId}/batch'

Response;

{
"correlationId": "fdfa09c4-d199-47fa-9846-a0df8845dbc5",
"operationResults": [
{
"type": "OperationDone",
"op": "Upsert",
"referenceKey": "FI2101010969659",
"message": null
},
{
"type": "OperationDone",
"op": "Upsert",
"referenceKey": "FI2101010969658",
"message": null
}
]
}

2. Check the batch status at the registerinfo endpoint, GET register/{registerId}.

curl -X GET --header 'Accept: application/json' --header 'x-api-key: {x-api-key}' 'https://api-test.bisnode.fi/people/register-monitor/v2/register/{registerId}'

When event typeId 5, 'Populated matching results' is found for correlationId, the matching is completed. If this is not found within a reasonable amount of time, (within one day,) run the upsert-batch again.

Response;

{
"registerId": {registerId},
"registerName": "{registerName}",
"itemCount": 2,
"matchedItemCount": 2,
"events": [

{
"id": 254063,
"typeId": 1,
"typeName": "Upsert items",
"timestamp": "2022-02-03T09:06:18.157Z",
"metadata": [
{
"okRows": 2,
"errorRows": 0,
"totalRows": 2,
"newRows": 2,
"modifiedRows": 0
}
],
"correlationId": "fdfa09c4-d199-47fa-9846-a0df8845dbc5"
},
{
"id": 254064,
"typeId": 3,
"typeName": "Matching started",
"timestamp": "2022-02-03T09:06:18.343Z",
"metadata": null,
"correlationId": "fdfa09c4-d199-47fa-9846-a0df8845dbc5"
},
{
"id": 254065,
"typeId": 4,
"typeName": "Matching ended",
"timestamp": "2022-02-03T09:06:20.437Z",
"metadata": null,
"correlationId": "fdfa09c4-d199-47fa-9846-a0df8845dbc5"
},
{
"id": 254066,
"typeId": 5,
"typeName": "Populated matching results",
"timestamp": "2022-02-03T09:06:20.483Z",
"metadata": null,
"correlationId": "fdfa09c4-d199-47fa-9846-a0df8845dbc5"
}
],
"accesses": [
{
"package": "VRK Base",
"access": "VRK Basic package without SSN or Gender"
}
]
}

3. Download the batch from items-endpoint using action=PrepareAndGetData, GET register/{registerId}/items?Action=PrepareAndGetData.

curl -X GET --header 'Accept: application/json' --header 'x-api-key: {x-api-key}' 'https://api-test.bisnode.fi/people/register-monitor/v2/register/{registerId}/items?action=PrepareAndGetData'

You will receive the entire batch you have uploaded for batch endpoints, as well as the people whose information has changed. The response message also has a batchId, which you can use to retrieve the same response later with the Action=GetData parameter.

Response;

{
"batchId": 254089,
"errors": [],
"rows": [
{
"errors": [],
"referencekey": "FI2101010969658",
"bisnodeid": "FI2101010969658",
"metadata": {
"match_status": "MATCH",
"created_at": "2022-02-03T09:06:18.28Z",
"last_retrieved_at": "2022-02-03T09:13:34.363Z",
"removed_at": null,
"last_identified_at": "2022-02-03T09:06:20.5Z",
"modified_at": "2022-02-03T09:06:18.28Z",
"first_identified_at": "2022-02-03T09:06:20.5Z"
},
"vrk": {
"_rowtype": "Match",
"_lastchangedat": "2021-12-15T15:01:48.697Z",
"permanentaddr_addresstype": null,
"firstnames": "Yjö Veikko",
"lastname": "Svensson",
"permanentaddr_streetaddress": null,
"permanentaddr_postcode": null,
"permanentaddr_postoffice": null,
"dateofdeath": null,
"permanentaddr_startdate": null,
"permanentaddr_municipalitycode": null,
"permanentaddr_municipalityname": null,
"permanentaddr_countrycode_iso3165_numeric": null,
"permanentaddr_countryname": null,
"isunderaged": false
},
"original": {
"firstname": "Yjö Veikko",
"lastname": "Svensson",
"postcode": "01200",
"postoffice": "VANTAA",
"streetaddress": "Birkanpolku 15 R 44"
}
},
{
"errors": [],
"referencekey": "FI2101010969659",
"bisnodeid": "FI2101010969659",
"metadata": {
"match_status": "MATCH",
"created_at": "2022-02-03T09:06:18.28Z",
"last_retrieved_at": "2022-02-03T09:13:34.363Z",
"removed_at": null,
"last_identified_at": "2022-02-03T09:06:20.5Z",
"modified_at": "2022-02-03T09:06:18.28Z",
"first_identified_at": "2022-02-03T09:06:20.5Z"
},
"vrk": {
"_rowtype": "Match",
"_lastchangedat": "2020-01-16T10:02:51.103Z",
"permanentaddr_addresstype": "Domestic",
"firstnames": "Anna Minna",
"lastname": "Meikäläinen",
"permanentaddr_streetaddress": "Birkanpolku 15 R 44",
"permanentaddr_postcode": "01200",
"permanentaddr_postoffice": "VANTAA",
"dateofdeath": null,
"permanentaddr_startdate": "2006-01-01T00:00:00Z",
"permanentaddr_municipalitycode": "092",
"permanentaddr_municipalityname": "Vantaa",
"permanentaddr_countrycode_iso3165_numeric": "246",
"permanentaddr_countryname": "Finland",
"isunderaged": false
},
"original": {
"firstname": "Anna Minna",
"lastname": "Meikäläinen",
"postcode": "01200",
"postoffice": "VANTAA",
"streetaddress": "Birkanpolku 15 R 44"
}
}
]
}

Step 3: Deploy service to production

Simply change URL, RegisterID and API key from test to production.