Ratkaisut Bisnodesta Syvennä osaamistasi Toimialat Asiakaspalvelu Osta verkosta
Etsi
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.

People REST APIs
People REST APIs

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. REQUEST THE username and password

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 elementDescription
requestParameters List of all request parameters with the used values.
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 or No_Match
person The element contains a person's information.
bisnodeId The unique person id.
firstName Person's first names (or name)
lastName Person's last name
streetAddress Person's current street address
postalCode Person's current postal code
postOffice Person's current post office
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
firstName Person's first names (or name)
lastName Person's last name
streetAddress Person's current street address
postalCode Person's current postal code
postOffice Person's current post office
companyName Company name

API request parameters

ParameterDescription 
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

Swagger - Developer REST API documentation - read more »

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
        }
    ]
}