People Monitoring REST - Implementation guide
Items endpoint
Items endpoint will return: -
Endpoint parameters
| Name | type | Description |
|---|---|---|
| RegisterId | URl part | |
| X-api-key | Custom HTTP header | Register API key, or valid ticket from Bisnode permission API |
| Content-Type | HTTP header | Application/JSON |
| action | Query string | Defined query type, this is the only mandatory parameter
|
| after | Query string, optional | If you want to prepare data after date you may use this. By default batch is prepare after last change that was delivered to you, no matter when you prepared batch. This means that by default you will get all changes just once. |
| batchId | Query string, optional | If you PrepareData and GetData as a separate batch as a separate batch you must use batch id returned by operateion in GetData query. |
Notice: VRK will bill every time customer check if there are changes. However, we want to prepare for errors and thus, we want to allow that customer can retrieve data many times without need to pay extra. Thus getting changes have two phases:
PrepareData creates a snapshot of the data.
GetData return lasts row of a snapshot per datasource, if allowed by datasource retention rules. I.e. customer can retrieve vrk changes for on month, and he does not need to pay extra.
PrepareAndGetData is combination of these two. It allows customer to prepare and get changes with one call. This option is created for sake of convenience-
Request and response examples
GET people/register-monitor/v2/register/{register_id}/items?action=PrepareAndGetData Content-type: application/json x-api-key: {x-api-key}
Successful request and the API return results in JSON format.
{
"batchId": 2632,
"errors": [],
"rows": [
{
"errors": [],
"referencekey": "RefKey1",
"bisnodeid": "FI2101004055080",
"gedi": "A2YZ88G6C67N",
"vrk": {
"_rowtype": "Change",
"_lastchangedat": "2017-03-29T21:10:43.567Z",
"permanentaddr_addresstype": "domestic",
"firstnames": "Esko",
"lastname": "Esimerkki",
"permanentaddr_streetaddress": "Esimerkkitie 1234",
"permanentaddr_postcode": "12345",
"permanentaddr_postoffice": "ESIMEMERKKINIEMI",
"dateofdeath": null,
"permanentaddr_startdate": "2011-03-26T00:00:00Z",
"permanentaddr_municipalitycode": "263",
"permanentaddr_municipalityname": "Kiuruvesi",
"permanentaddr_countrycode_iso3165_numeric": "246",
"permanentaddr_countryname": "Finland",
"languagegroupcode": "Finnish",
"isunderaged": false
},
"original": {
"customer_datafield2": "CUSTOMER DATAFIELD 2",
"firstname": "Esko",
"lastname": "Esimerkki",
"postcode": "12345",
"streetaddress": "Esimerkkitie 1234"
}
}
]
}
How it works actually?
Changes are allows prepared in two phases:
PrepareData aggregate data from data sources. Then it creates a snapshot you can download (GetData). There are few things you should pay attention:
- Prepare data billable action so you should pay attention how often you request changes - especially if you request them explicitly after a specific date. Notice that you are billed even if you don't download the data if there are changes for you.
- Avoid use of after in ordinary use case. There is no guarantee that the are changes available after a date you since data is updated a background job. Its better you let system check what changes you have got.
- Prepare data action return batchId. Use it to get data related to that batch later.
GetData returns a snapshot that you have prepared earlier.
- _lastchangedat tells when the data have been changed in Bisnode tracking system. Is is not the data it is really changed. This data is used to track what changes should be returned. It is not possible to use real changes date for this purpose as changes are delivered as batch processing.
- _rowtype tells why this changes is delivered. Changes means that you have got "first update" and this is a "change" after it. "Match" indicate that you have added a new person to your register and we have identified it. You will be informed once data relating this person changes. Rematch indicate that you have changes an existing person and we have checked again if we can identify it.
- Notice: row data is returned in lowercase.
- The are limitations how long a prepared batch is available for download. In case of vrk data, you can download the data for 30 days. After that GetData for a batch, won't return vrk data. It will return still data that does not have this kind of limitations.
PrepareAndGetData does first PrepareData and then GetData of the prepared batch. Things to take into account when you design the system:
- When you first time upload whole register matching may take hours. Actual upload should take less than minute, but upload just saves data to database. Actual processing happens as a background process.
- Also when you first time prepare and get changes after you have uploaded thousands of rows this takes times, and you can expect to get tens of megabytes data as response. Here you have some guideline
- 100 000 rows
- Matching: 5-10 minutes by average, may take sometimes 1h. Quality of register matters a lot. (After upsert)
- PrepareData: usually less than minute.
- GetData: usually less than minute. You get you should expect to get ~20Mb as a response first time.
- 500 000 rows
- Matching: 20-40 minutes by average, may take sometimes few hours. Quality of register matters a lot. (After upsert)
- PrepareData: usually less than minute.
- GetData: usually less than minute. You get you should expect to get ~20Mb as a response.