People API

Match external

External match API is perfect for you, if you want to identify a person by using the name and address information. API is using external data sources, so you can use this API to confirm person's identification. API is really simple to use and return results in JSON format.

API endpoints

  • - production environment
  • - test environment

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 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 is always null.

API request parameters

firstName First name (or names) of the person. e.g. Matti X
lastName Last name of the person. e.g. Pouta X
streetAddress Street address. e.g. Kauppakatu 63 A 2 X
postalCode Postal code. e.g. 78200 X
postOffice Post office. e.g. Helsinki X

Developer REST API documentation - read more »

API request and response example

curl '' -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": 1,
        "lastNameEstimate": 1,
        "postalCodeEstimate": 1,
        "postOfficeEstimate": 1,
        "streetAddressEstimate": 1
    "matchType": "Match",
    "person": {
        "bisnodeId": null,
        "firstName": "Matti",
        "lastName": "Pouta",
        "postalCode": "00980",
        "postOffice": "HELSINKI",
        "streetAddress": "Kumpulantie 3",
"adult": "yes",
"status": "alive"
    "phoneNumberMatch": null,
    "matchTypeDataSource": "ExternalDatasource",
    "validationStatus": [
            "matchDataSources": "ExternalDatasource",
            "error": null,
            "isInputValid": true

Läs mer om våra tjänster på Bisnode