Etsi
People Monitoring APIs

Batch

This API is for the insert, update, and delete register items.

Only Population Register Centre people related basic information (e.g., name, address, deceased) is available through APIs. To use of that basic information requires permission issued by Population Register Centre. Bisnode's data elements (e.g., credit remarks, predictions) can be used without the Population Register Centre permission through APIs.

To use the API, you must have a valid environment-specific REGISTER ID and API KEY. You will get a valid REGISTER ID and API KEY from the Bisnode's Customer Service. The API KEY must be sent in the request custom header element (named: x-api-key). If the API KEY value is valid, then the API request will be successful (HTTP status code 200). Otherwise, it will fail (HTTP status code 401). All API requests must be made over HTTPS.

SWAGGER - Developer REST API documentation - read more »

API endpoints

  • https://api.bisnode.fi/people/register-monitor/v2/register/{REGISTER ID}/batch - PROD
  • https://api-test.bisnode.fi/people/register-monitor/v2/register/{REGISTER ID}/batch - TEST

API request

Parameter Description  
id Register ID M
body

Body is an array of operations. Each operation is a JSON object that have one mandatory parameter _op (operation type).

Currently there are two kind of operation (_op - attribute):

· Upsert (insert or update)
· Delete

Other required parameters depends on the type. E.g. Delete operation requires only reference key, and Upsert operations requires field you want to insert to the your register.

If array contains JSON-object that does not have _op attribute, the objects are simply ignored. If array contains other JSON elements than object you endpoint returns Bad Request HTTP error.

M

POST https://api-test.bisnode.fi/people/register-monitor/v2/register/{id}/batch

API response

Element Description
operationResults An array contains all operations results.
referenceKey Operation target. Customers reference key for the item (unique identifier).
op Operation (Upsert or Delete)
type The element presents the operation status related to the specific reference key. The successful operation value is OperationDone. If the operation could not perform, then the value is OperationFaild or ValidationWarning.
message If the operation could not perform (type is not OperationDone), then the element contains more detailed information about the issue.

API request and response example

curl 'https://api-test.bisnode.fi/people/register-monitor/v2/register/371/batch' -X POST -d 
'[
    {
        "_op":  "Upsert",
        "referenceKey":  "050535-905F",
        "firstName":  "Olavi Janne",
        "lastName":  "Meikalainen",
        "streetAddress":  "Franzéninkatu 3 E 45",
        "postCode":  "00500",
        "postOffice":  "Helsinki"
    },
    {
        "_op":  "Upsert",
        "referenceKey":  "FI2101010969661",
        "firstName":  "Aino Minna",
        "lastName":  "Meikäläinen",
        "streetAddress":  "Aholammentie 562",
        "postCode":  "99600",
        "postOffice":  "SODANKYLÄ"
    }    
]' 
-H 'x-api-key: ABC1234567890' -H 'Content-Type: application/json'

Successful API request returns results in JSON format.

{
    "operationResults": [
        {
            "type": "OperationDone",
            "op": "Upsert",
            "referenceKey": "050535-905F",
            "message": null
        },
        {
            "type": "OperationDone",
            "op": "Upsert",
            "referenceKey": "FI2101010969661",
            "message": null
        }
    ]
}

More detailed implementation guide for the API - read more »