Batch

To access the API, you must have a valid environment-specific Register ID and API Key. These credentials are provided by DnB Customer Service.

Include the API Key in the custom HTTP request header named x-api-key.

If the API Key is valid, the request is authenticated successfully and the API returns an HTTP 200 (OK) response. If the API Key is invalid or missing, the request is rejected with an HTTP 401 (Unauthorized) response.

All API requests must be made over HTTPS to ensure secure communication.

 

API Key Expiration and Rotation

API keys have a limited validity period and must be rotated before they expire.

The expiration date of the currently active API key is returned in the response header X-Api-Key-Expiration-Date. Clients should monitor this value and rotate their API key before the expiration date is reached.

A new API key can be generated using the following endpoint:

POST /register/{registerId}/rotatekey

The endpoint returns a new API key. The newly generated key does not immediately replace the current key. Instead, it becomes the active key the first time it is used in an API request. After activation, the previous key is no longer valid.

If an API key expires before it has been rotated, access to the key rotation endpoint is also revoked. In this case, a new API key must be requested from DnB Customer Service.

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
M = Mandatory

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": "124oth4-5fd9-4eff-01f3-ab5a012277ds:58255",
"socialsecuritynumber": "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": "124oth4-5fd9-4eff-01f3-ab5a012277ds:58255",
"message": null
},
{
"type": "OperationDone",
"op": "Upsert",
"referenceKey": "FI2101010969661",
"message": null
}
]
}