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

It will return 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.

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
MobileNumberEnables 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":"",
      "LastName":"Lennartsson",
      "City":"Västerås"
   }
}

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": "090a27ff-1f57-4dba-aa2c-a4ef58353425",
  "errors": [],
  "ResultCount": 2,
  "MatchLevelScoringExpression": "80%/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 36% | FullName 29%;1;ld_15 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 100%;0,8;ld_0",
      "_SortIndexAtSource": 0,
      "PersonStatus": "",
      "MainFirstName": "",
      "FirstName": "Irina Kristina",
      "LastName": "Lennartsson",
      "DateOfBirth": "19531009",
      "BirthYear": 1953,
      "BirthMonth": 10,
      "BirthDayOfMonth": 9,
      "Age": 0,
      "PersonalNumber": "195310098620",
      "Address": "Lugna gatan 4 lgh 1111",
      "Address2": null,
      "PostalCode": "23456",
      "Location": "Västerås",
      "City": "Västerås",
      "Province": null,
      "CountryCode": "se",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP05",
      "FullName": "Irina Kristina Lennartsson"
    },
    {
      "_MatchLevel": "LOW 39% | FullName 36%;1;ld_11 | Address 0%;0,6;ld_nodata | PostalCode 0%;0,6;ld_nodata | City 100%;0,8;ld_0",
      "_SortIndexAtSource": 1,
      "PersonStatus": "",
      "MainFirstName": "Hjalmar",
      "FirstName": "Per Hjalmar",
      "LastName": "Lennartson",
      "DateOfBirth": "19770906",
      "BirthYear": 1977,
      "BirthMonth": 9,
      "BirthDayOfMonth": 6,
      "Age": 0,
      "PersonalNumber": "197709067777",
      "Address": "Rufusvägen 12",
      "Address2": null,
      "PostalCode": "23458",
      "Location": "Västerås",
      "City": "Västerås",
      "Province": null,
      "CountryCode": "se",
      "Phone": null,
      "Email": null,
      "PhoneNumbers": null,
      "_DataSource": "DP05",
      "FullName": "Per Hjalmar Lennartson"
    }
  ]
}

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