Batch endpoint - Insert, update and delete items

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
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 contain	Used in match	Example, 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	Yes³	Yes	One or many first names, eg. 'Maija', 'Maija Ilona'
LastName	String,255	Yes³	Yes	Surname of person, with or without prefixes. E.g. 'Meikäläinen', 'von Wright'
StreetAddress	String,255	Yes³	Yes	Street address including number of house, stair letter and appartment number, e.g. 'Kumpulantie 3', 'Esimerkkikatu 12 B 15'
PostCode	String,255	Yes³	Yes	Matching presume that this is Finnish postal code in format of /[0-9]{5}/ (five digits), e.g. 00100.
PostOffice	String,255	Yes³	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	Maybe⁴	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	Maybe³	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.

₁₎ 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.

²⁾ 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.

³⁾ 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.

⁴⁾ 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 name¹	Type, length ²	Example, 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.