A country-specific search – for finding the best matching persons and their addresses by a query towards the national population register.

It will return an array of the best matches according to the specific querying rules for the national population register provider. 

For example:

  • Swedish search results always include the field PersonalNumber
  • Denmark only includes the fields PersonalNumber and DateOfBirth if given in the query and also is correctly matched with the other search parameters.
  • Norwegian search results only include the street address automatically when there is exacly one match in the search results. This is because address is fetched separately. 

API

POST to https://env.zignsec.com/v2/ekyc/searchperson

where env is api or test.

Parameters

In the Query node level:

CountryCodeMandatory parameter. Sets the country to query in.
FirstName 
LastName 
DateOfBirthIn the form YYYYMMDD or YYYY-MM-DD
PhoneEnables search by phone number where service is available.
AddressStreet name and number etc.
PostalCode 
City 

In the root node level:

EnvironmentOptional parameter. See Environment at the Common Data documentation.
_DataSourceOptional parameter. For specifying the underlying search provider to be used.

Sample of Test persons can be found here.

Example request for a Swedish search

POST https://test.zignsec.com/v2/ekyc/searchperson HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: your_key_here

{
   "Query":{
       "CountryCode":"se",
       "FirstName":"Daniel",
       "LastName":"Eriksson",
       "City":"BERGSJÖ",
       "DateOfBirth":"1942-02-28"
   }
}

Example of Response with 2 hits from above query (Swedish population register) :
The PersonsFound node contains an array of address objects.

There are three fields in a matching address row that represents the matching degree against the query, for example the SubScoresDescription compactly describes the SubScore array.

{
    "id": "3a950fb4-3514-478b-a0ad-bf0fd7aa2cad",
    "errors": [],
    "ResultCount": 1,
    "MatchLevelScoringExpression": "85%/60% | FullName;1;ld | Address;0.6;ld | Address2;0.4;ldx | Location;0.4;ldx | PostalCode;0.6;ld | City;0.8;ld | DateOfBirth;5;eqx",
    "PersonsFound": [
        {
            "_MatchLevel": "MEDIUM 84% | FullName 100%;1;ld_0 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 100%;0,8;ld_0 | DateOfBirth 100%;5;eqx_True",
            "_SortIndexAtSource": 0,
            "PersonStatus": "",
            "Gender": null,
            "MainFirstName": "Daniel",
            "FirstName": "Daniel",
            "LastName": "Eriksson",
            "DateOfBirth": "19420228",
            "BirthYear": 1942,
            "BirthMonth": 2,
            "BirthDayOfMonth": 28,
            "Age": null,
            "PersonalNumber": "194202281111",
            "Address": "Vasavägen",
            "Address2": null,
            "PostalCode": "82070",
            "Location": null,
            "City": "BERGSJÖ",
            "Municipality": "Nordanstig",
            "Province": null,
            "CountryCode": "se",
            "Phone": null,
            "Email": null,
            "PhoneNumbers": null,
            "_DataSource": "DP05",
            "Url": null,
            "FullName": "Daniel Eriksson"
        }
    ]
}

Example request for a Danish search person existing in Test environment

{
   "Query":{
      "FirstName":"Jens",
      "LastName":"Mortensen",
      "CountryCode":"dk",
      "postalcode":"6800",
      "address":"Boulevarden 101"
   }
}

Example of a Danish population register search Response:

{
  "id": "8a6da3c9-00ce-4901-a18c-b2d0776cc729",
  "errors": [],
  "ResultCount": 1,
  "MatchLevelScoringExpression": "85%/60% | FullName;0,5;ld | Address;0,5;ld | PostalCode;1;ld | City;1;ld",
  "PersonsFound": [
    {
      "_MatchLevel": "MEDIUM 63% | FullName 100%;0,5;ld_0 | Address 75%;0,5;ld_5 | PostalCode 100%;1;ld_0 | City 0%;1;ld_nodata",
      "_SortIndexAtSource": 0,
      "PersonStatus": "",
      "MainFirstName": null,
      "FirstName": "Jens",
      "LastName": "Mortensen",
      "DateOfBirth": "",
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": 0,
      "PersonalNumber": null,
      "Address": "Boulevarden 101,1 mf",
      "Address2": null,
      "PostalCode": "6800",
      "Location": null,
      "City": "Varde",
      "Province": null,
      "CountryCode": "dk",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP02",
      "FullName": "Jens Mortensen"
    }
  ]
}

Example request for a Norwegian search person existing in Test environment

{
   "Query":{
      "FirstName":"Hans",
      "LastName":"Hansen",
      "CountryCode":"no",
      "City":"Oslo"
   }
}

Example of a Norwegian population register search Response:

Note: The personalnumber returned in the this response not is the real personal number but a reference number used by our supplier.

{
  "id": "afadb7df-01e3-4096-a114-8cb1afb4c5f8",
  "errors": [],
  "ResultCount": 10,
  "MatchLevelScoringExpression": "85%/60% | FullName;1;ld | Address;0.6;ld | Address2;0.4;ldx | Location;0.4;ldx | PostalCode;0.6;ld | City;0.8;ld | DateOfBirth;5;eqx",
  "PersonsFound": [
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/2179299S1",
      "_MatchLevel": "LOW 33% | FullName 100%;1;ld_0 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 0,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "2179299S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0654",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/ensjoe/hans-hansen_2179299S1/",
      "FullName": "Hans Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/207995927S1",
      "_MatchLevel": "LOW 33% | FullName 100%;1;ld_0 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 1,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "207995927S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0597",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/oslo/hans-hansen_207995927S1/",
      "FullName": "Hans Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/209149305S1",
      "_MatchLevel": "LOW 19% | FullName 58%;1;ld_8 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 2,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Albrigh",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "209149305S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0187",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/groenland/hans-albrigh-hansen_209149305S1/",
      "FullName": "Hans Albrigh Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/19470453S1",
      "_MatchLevel": "LOW 18% | FullName 53%;1;ld_10 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 3,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Christian",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "19470453S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "1170",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/nordstrand/hans-christian-hansen_19470453S1/",
      "FullName": "Hans Christian Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/149556S1",
      "_MatchLevel": "LOW 23% | FullName 69%;1;ld_5 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 4,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Erik",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "149556S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0383",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/ullern/hans-erik-hansen_149556S1/",
      "FullName": "Hans Erik Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/5203960S1",
      "_MatchLevel": "LOW 23% | FullName 69%;1;ld_5 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 5,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Erik",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "5203960S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0956",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/roedtvedt/hans-erik-hansen_5203960S1/",
      "FullName": "Hans Erik Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/17258408S1",
      "_MatchLevel": "LOW 23% | FullName 69%;1;ld_5 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 6,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Inge",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "17258408S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0456",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/adamstua/hans-inge-hansen_17258408S1/",
      "FullName": "Hans Inge Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/1462055S1",
      "_MatchLevel": "LOW 22% | FullName 65%;1;ld_6 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 7,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans-Jacob",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "1462055S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0374",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/vinderen/hans-jacob-hansen_1462055S1/",
      "FullName": "Hans-Jacob Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/2180403S1",
      "_MatchLevel": "LOW 23% | FullName 69%;1;ld_5 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 8,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Knud",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "2180403S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0682",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/skoeyenaasen/hans-knud-hansen_2180403S1/",
      "FullName": "Hans Knud Hansen"
    },
    {
      "GetFullDetailsUrl": "https://test.zignsec.com/v2/ekyc/searchperson/no/209664633S1",
      "_MatchLevel": "LOW 18% | FullName 55%;1;ld_9 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 0%;0,8;ld_nodata",
      "_SortIndexAtSource": 9,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Hans Kristian",
      "LastName": "Hansen",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": "209664633S1",
      "Address": null,
      "Address2": null,
      "PostalCode": "0581",
      "Location": null,
      "City": null,
      "Municipality": null,
      "Province": null,
      "CountryCode": "no",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP12",
      "Url": "https://www.1881.no/person/oslo/alnabru/hans-kristian-hansen_209664633S1/",
      "FullName": "Hans Kristian Hansen"
    }
  ]
}

NOTE: there is an additional field for Norwegian person search: GetFullDetailsUrl – while we don’t have a separate /lookupperson endpoint for Norway you can get person details from this url (don’t forget to pass authorization header there, it returns response similar to /lookupperson)

{
  "id": "1382190a-269a-4737-9cfc-25e05bc3269d",
  "errors": [],
  "WasFound": true,
  "Person": {
    "PersonStatus": "",
    "Gender": null,
    "MainFirstName": null,
    "FirstName": "Hans Albrigh",
    "LastName": "Hansen",
    "DateOfBirth": null,
    "BirthYear": 0,
    "BirthMonth": 0,
    "BirthDayOfMonth": 0,
    "Age": null,
    "PersonalNumber": "209149305S1",
    "Address": "Lakkegata 53 ",
    "Address2": null,
    "PostalCode": "0187",
    "Location": "Oslo",
    "City": null,
    "Municipality": null,
    "Province": null,
    "CountryCode": "no",
    "Phone": null,
    "Email": null,
    "PhoneNumbers": [
      "41450581"
    ],
    "_DataSource": "DP12",
    "Url": "https://www.1881.no/person/oslo/groenland/hans-albrigh-hansen_209149305S1/",
    "FullName": "Hans Albrigh Hansen"
  }
}

Example request for a search person in Finland

NOTE: Supported only following parameters: LastName, FirstName, City, Phone. Other parameters are ignored.
{
   "Query":
   {
      "LastName":"Duncan",
      "CountryCode":"fi",
      "City":"Helsinki"
   },
   "environment":"test"
}

Example search Response for Finland:

{
  "id": "66a4c09e-eaf9-4ab5-a73a-ca3822cfd116",
  "errors": [],
  "ResultCount": 2,
  "MatchLevelScoringExpression": "85%/60% | FullName;1;ld | Address;0.6;ld | Address2;0.4;ldx | Location;0.4;ldx | PostalCode;0.6;ld | City;0.8;ld | DateOfBirth;5;eqx",
  "PersonsFound": [
    {
      "_MatchLevel": "LOW 43% | FullName 50%;1;ld_6 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 100%;0,8;ld_0",
      "_SortIndexAtSource": 0,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Aada",
      "LastName": "Duncan",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": null,
      "Address": "Töölönlahdenkatu 4",
      "Address2": null,
      "PostalCode": "00100",
      "Location": null,
      "City": "Helsinki",
      "Municipality": null,
      "Province": null,
      "CountryCode": "fi",
      "Phone": "040 503 0707",
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": null,
      "Url": null,
      "FullName": "Aada Duncan"
    },
    {
      "_MatchLevel": "LOW 38% | FullName 34%;1;ld_12 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 100%;0,8;ld_0",
      "_SortIndexAtSource": 1,
      "PersonStatus": "",
      "Gender": null,
      "MainFirstName": null,
      "FirstName": "Olaph",
      "LastName": "Duncan",
      "DateOfBirth": null,
      "BirthYear": 0,
      "BirthMonth": 0,
      "BirthDayOfMonth": 0,
      "Age": null,
      "PersonalNumber": null,
      "Address": "Töölönlahdenkatu 9",
      "Address2": null,
      "PostalCode": "00770",
      "Location": null,
      "City": "Helsinki",
      "Municipality": null,
      "Province": null,
      "CountryCode": "fi",
      "Phone": "047 017 0569",
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": null,
      "Url": null,
      "FullName": "Olaph Duncan"
    }
  ]
}