People Rest api
Match
Match API is perfect for you, when you want to identify a person by using the name and address information or just the phone number. API is really simple to use and return results in JSON format.
In order to use the API you must have the valid environment-specific username and password. Before any API requests, you need to obtain an API KEY. You will get a valid API KEY (it's called a ticket) by using the ticket API (Please, read how to use ticket API).
The API KEY must be sent in the request custom header element (named ticket or x-api-key). If the API KEY value is valid then 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.
API endpoints
- https://api.bisnode.fi/people-match/v2/match - production environment
- https://api-test.bisnode.fi/people-match/v2/match - test environment
API response
| Data element | Description |
|---|---|
| requestParameters | List of all request parameters with the used values. Includes the following elements: firstName, lastName, streetAddress, postalCode, postOffice. |
| fieldMatchAccuracy | This element shows of the accuracy of the matching. The exact match will be shown as value 1.0 (available value range is from 0.01 to 1.0). Includes the following elements: firstNameEstimate, lastNameEstimate, streetAddressEstimate, postalCodeEstimate, postOfficeEstimate. |
| matchType | Indicates were we able to do a person identify or not. The element include these values: Match (bisnodeId, firstName, lastName, postalCode, postOffice, streetAddress, adults, status) or No_Match. |
| person | The element contains a person's information. |
| bisnodeId | The unique person id. e.g. FI2101005032547 |
| firstName | Person's first names (or name). e.g. Matti Esko |
| lastName | Person's last name. e.g. Pouta |
| postalCode | Person's current postal code. e.g. 00980 |
| postOffice | Person's current post office. e.g. HELSINKI |
| streetAddress | Person's current street address. Kumpulantie 3 |
| adult | Indicates whether the person is adult or not. Available options: yes, no or unknown. |
| status | Indicates whether the person is alive or not. Available options: alive, dead or unknown. |
| phoneNumberMatch | The element contains a person's information. This element is used only on the phone number match. |
| telephoneNumber | Person or company phone number. e.g. 0442379701 |
| firstName | Person's first names (or name). e.g. Matti Esko |
| lastName | Person's last name. e.g. Pouta |
| streetAddress | Person's current street address. e.g. Kumpulantie 3 |
| postalCode | Person's current postal code. e.g. 00980 |
| postOffice | Person's current post office. e.g. HELSINKI |
| companyName | Company name. |
API request parameters
| Parameter | Description | |
|---|---|---|
| firstName | First name (or names) of the person. e.g. Matti | X1 |
| lastName | Last name of the person. e.g. Pouta | X1 |
| streetAddress | Street address. e.g. Kauppakatu 63 A 2 | X1 |
| postalCode | Postal code. e.g. 78200 | X1 |
| postOffice | Post office. e.g. Helsinki | X1 |
| phoneNumber | Person or company phone number. e.g. 0442379701 | X2 |
| X1 = Mandatory on name and address match, X2 = Mandatory on the phonenumber match | ||
API request and response example: Simple name and address match
curl 'https://api.bisnode.fi/people-match/v2/match' -X POST -d '{
"firstName": "Matti",
"lastName": "Pouta",
"streetAddress": "Kumpulantie 3",
"postalCode": "00980",
"postOffice": "HELSINKI"
}' -H 'x-api-key: 1234567890ABC' -H 'Content-Type: application/json'
Successful request and the API return results in JSON form
{
"requestParameters": {
"firstName": "Matti",
"lastName": "Pouta",
"streetAddress": "Kumpulantie 3",
"postalCode": "00980",
"postOffice": "HELSINKI"
},
"fieldMatchAccuracy": {
"firstNameEstimate": 0.9,
"lastNameEstimate": 1.0,
"postalCodeEstimate": 1.0,
"postOfficeEstimate": 1.0,
"streetAddressEstimate": 1.0
},
"matchType": "Match",
"person": {
"bisnodeId": "FI2101005032547",
"firstName": "Matti Esko",
"lastName": "Pouta",
"postalCode": "00980",
"postOffice": "HELSINKI",
"streetAddress": "Kumpulantie 3",
"adult": "no",
"status": "alive"
},
"phoneNumberMatch": null,
"matchTypeDataSource": "BisnodePeopleDatasource",
"validationStatus": [
{
"matchDataSources": "BisnodePeopleDatasource",
"error": null,
"isInputValid": true
}
]
}
API request and response example: Simple phonenumber match
curl 'https://api.bisnode.fi/people-match/v2/match' -X POST -d '{
"phonenumber": "0442379701"
}' -H 'x-api-key: 1234567890ABC' -H 'Content-Type: application/json'
Successful request and the API return results in JSON form
{
"requestParameters": {
"phonenumber": "0442379701"
},
"fieldMatchAccuracy": {
"firstNameEstimate": null,
"lastNameEstimate": null,
"postalCodeEstimate": null,
"postOfficeEstimate": null,
"streetAddressEstimate": null
},
"matchType": "Match",
"person": {
"bisnodeId": null,
"firstName": null,
"lastName": null,
"postalCode": null,
"postOffice": null,
"streetAddress": null,
"adult": null,
"status": null
},
"phoneNumberMatch": {
"telephoneNumber": "0442379701",
"firstName": "Matti Esko",
"lastName": "Pouta",
"streetAddress": "Kumpulantie 3",
"postalCode": "00980",
"postOffice": "HELSINKI",
"companyName": ""
},
"matchTypeDataSource": "Phone",
"validationStatus": [
{
"matchDataSources": "Phone",
"error": null,
"isInputValid": true
},
{
"matchDataSources": "BisnodePeopleDatasource",
"error": "Insufficient data for match. Provide at least BisnodeId, or FirstName, LastName, StreetAddress and PostalCode, or FirstName, LastName and TelephoneNumber. More data you provide more likely will be the match.",
"isInputValid": false
}
]
}