Ratkaisut Bisnodesta Syvennä osaamistasi Tietosuoja MyBisnode Asiakaspalvelu Osta verkosta
Etsi
People Monitoring REST - Implementation guide

Batch endpoint - Insert, update and delete items

Use batch endpoint to upload or change your register.

Implementation guide
Implementation guide

Endpoint parameters

NametypeDescription
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
Operations Http Request 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.  

Upsert operation

Upsert operation allows you to enter ANT data to the register. While there are no mandatory fields in the operations, you should include sufficient information for matching (see table "Upsert operation fields"). If insufficient amount of data for matching is included, you will get no changes to the person (see download changes). In addition to the field listed in "Upsert operation fields" table you can enter any useful metadata to a row. E.g. you can store to the service persons ID in your CRM or ERP. When you query changes, you will get this information in the response.

Upsert operation attributes
Field name[1]Type, length[2]Should containUsed in matchExample, notes
_op "Upsert" Yes No  
ReferenceKey String,255 Yes No Unique identifier of person in the client system. E.g. '90134', 'maija@meikalainen.fi'
FirstName String,255 Yes3 Yes One or many first names, eg. 'Maija', 'Maija Ilona'
LastName String,255 Yes3 Yes Surname of person, with or without prefixes. E.g. 'Meikäläinen', 'von Wright'
StreetAddress String,255 Yes3 Yes Street address including number of house, stair letter and appartment number, e.g. 'Kumpulantie 3', 'Esimerkkikatu 12 B 15'
PostCode String,255 Yes3 Yes Matching presume that this is Finnish postal code in format of /[0-9]{5}/ (five digits), e.g. 00100.
PostOffice String,255 Yes3 Yes Name of Finnish post office. E.g. 'Helsinki'
TelephoneNumber String,255 No

No

 Finnish telephone number with or without Finnish area code (+358). E.g. '+358 12 3456 789' '012 3456 789'
BisnodeId String,255 No Yes Unique identifier delivered by Bisnode. E.g. 'FI0212345678912'
Email String,255 No No Email address. E.g. 'maija@meikalainen.fi'.
DayOfBirth String,255 No In roadmap Day of birth in ISO 8601 format ({year}-{month}-{day}) or as serialized JSON datetime. E.g. '1980-12-31'.
Age String,255 No In roadmap Age in as integer. E.g. 32
BisnodeGedi String,255 No In roadmap  
Gender String,255 Maybe4 In roadmap M for male, and F for female. We may use this later in match. Currently VRK requires special permission if Gender information is returned to customer. In addition customer must have information about the gender or otherwise he cannot get update data, even if customer knows gender implicitly (e.g. he have person's social security number, that contains information on gender).
SocialSecurityNumber String,255 Maybe3 Yes This requires special permission from VRK. While we have BisnodeId SocialSecurity number mapping there are limitations how we can utilize the mapping.
$ACustomField$ String, 1000 No No

Register can contain any of other fields.

The extended field can be used for instance: To store data needed for integration to other system. Custom field name must start with ASCII letter (a-z), should not be any of the basic fields. Name can contain letter, numbers and underscores (_) and numbers. E.g. CRM_id, customer_region. Currently all data must be serialized to string.

Notice: If you use swagger dokumentation Swagger will not hint that you could push almost any data. For sake of conveniencemodel shows the fields listed above with examples. However, the real data model is more dynamic.

1) Field names are case insensitive. While client system can push variety to data to the system the fields listed her have special meaning and thus should not be used for different.

2) Field used in match can have max length 255 (for performance reasons), other field don't have max length. Notice, all customer data is stored as string in database. 255 character long phone number or post code is probably wrong and matching on basis of it will fail. Nevertheless data is stored and returned if requested.

3) For VRK address and name maintenance customer must deliver name and address data to Bisnode. If customer also delivers social security, we use it in match. Obviously match is 100% sure for valid and existing Bisnode id.

4) In order to get updates to gender and social security number, customer must deliver them to Bisnode (so that VRK "knows" that customer have already the data that is maintained).

Delete operation

Delete operation allows you to remove and person from register by using reference key. Operation object have two mandatory parameters, _op (that must be "Delete") and ReferenceKey. If reference does not exist in register or is already remove it will be removed. If you add a person with a reference key that have been remove, the person will a considered as a new person. 

Delete operation attributes
Field name1Type, length 2Example, notes
_op "Delete"  
ReferenceKey String,255 Unique identifier of person in the client system. E.g. '90134', 'maija@meikalainen.fi'

Request and response examples

POST people/register-monitor/v2/register/1/batch
Content-type: application/json
x-api-key: [removed]

[
  {
    "_op":"Delete",
    "referenceKey":"123"
  }
  {
    "_op":"Delete",
    "referenceKey":"not-found"
  }
  {
    "_op": "Upsert",
    "referenceKey":"124",
    "firstName": "Maija",
    "lastName": "Meikäläinen",
    "streetAddress": "Esimerkkikatu 12 B 15",
    "postCode":"00100",
    "postOffice":"HELSINKI",
    "crm_reference": "you can enter arbitrary custom metadata to the register row"
  }
]

[
	{
	"type": "ValidationWarning",
   	"referenceKey": "124",
    	"message": "Many instances of ReferenceKey was found. Operations are done in following order: 1. Delete, 2. Upsert. Last operation may override data/value over previous operation."
  	},
	{
	"type": "OperationDone",
    	"referenceKey": "124",
	"op": "Delete"
	},
	{
	"type": "OperationDone",
	"op": "Upsert",
	"referenceKey": "124"
	},
  	{
	"type": "OperationFaild",
    	"referenceKey": "not-found",
	"op": "Delete",
	"message": "ReferenceKey not found. No action."
  	}
]

Notice the response array contain response for each operation indicating whether operation was succeed or failed. In addition you may get warning e.g. if you had many operations having same reference key.