People rest 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.

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

  • - production environment
  • - test environment

API response

Data elementDescription
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 (includes the following elements: bisnodeId, firstName, lastName, postalCode, postOffice, streetAddress) or No_Match.
person The element contains a person's information. Includes the following elements: bisnodeId, firstName, postalCode, postOffice, streetAddress.
bisnodeId The unique person id. e.g. null or FI2101004932316
firstName Person's first names (or name). e.g. Matti
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
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