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) :
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. |
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 | 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' |
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 ( 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 name1 | Type, length 2 | 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.