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 the countries Sweden, Norway and Finland. In Denmark you will get a single response. 

For example:

  • Swedish search results always include the field PersonalNumber
  • Denmark only include the field DateOfBirth if given in the query and also is correctly matched with the other search parameters. (It is possible to send in PersonalNumber in Denmark but not recommended as this will override the other fields in the query)
  • Norwegian search results only include the street address automatically when there is exactly 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"
    }
  ]
}