> [!NOTE]
> This version is no longer recommended for use and will be retired in 2025.
Identity data verification checks personal information such as name, address, date of birth and/or national ID from various data sources to quickly confirm if an individual is who they claim to be.
## LookupPerson 🇸🇪, 🇫🇮, 🇩🇰
LookupPerson service looks up the address data for residents existing in the national population register by `countryCode` and a national `PersonalNumber`. A lookup by `PhoneNumber` is also available. The response can be either exactly one **[address](https://docs.zignsec.com/faq/common-data/#addressmodel)** hit, or empty if no match was found. For found persons the return field PersonStatus indicates the status, where empty status is the default and normal value, see below table.
**PersonStatus:**
- `Missing` or ""
- `Active` represents an active person and is the normal value.
- `Protected` – a person with protected identity
- `Emigrated` – a emigrated person will show this status for a "limited period".
- `Deceased` – a deceased person will show this status for a "limited period".
- `DeRegistered` – internal deletion code
- `Unknown status` – the earlier status was most likely Deceased or Emigrated but the indication is automatically lost after the above “limited period” has elapsed, and Unknown status is shown instead.
In case of a set PersonStatus the name and address fields are blanked out.
**Note:** eID authentications are able to automatically include address data. (currently Swedish BankID and BankingAPI): Set parameter LookupPersonAddress to true to do an address lookup towards the population register with the authenticated PersonalNumber.
## Parameters
In the Query node level:
| | |
|---|---|
|CountryCode|Mandatory parameter. Sets the country to query in.|
|FirstName||
|LastName||
|DateOfBirth|In the form YYYYMMDD or YYYY-MM-DD|
|Phone|Enables search by phone number where service is available.|
|Address|Street name and number etc.|
|PostalCode||
|City||
In the root node level:
| | |
|---|---|
|Environment|Optional parameter. See **[Environment](https://docs.zignsec.com/faq/common-data/#environment)** at the Common Data documentation.|
|_DataSource|Optional parameter. For specifying the underlying search provider to be used.|
[Sample of Test persons can be found here.](http://docs.zignsec.com/faq/test-persons-for-searchperson/)
### Example request for a Swedish search
```swift
POST https://test.zignsec.com/v2/ekyc/lookupperson HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: your_key_here
{
"CountryCode":"SE",
"PersonalNumber":"197001102222"
}
```
### Response fields
[See Common data structures](http://docs.zignsec.com/faq/common-data/)
#### Response example:
```swift
{
"id": "d352e761-45a4-465b-b290-e4d2bd65683f",
"errors": [],
"WasFound": true,
"Person":
{
"PersonStatus": "",
"MainFirstName": "Linda",
"FirstName": "Linda Marie",
"LastName": "Hassan Ahmed",
"DateOfBirth": "19700110",
"BirthYear": 1970,
"BirthMonth": 1,
"BirthDayOfMonth": 10,
"Age": 48,
"PersonalNumber": "197001102222",
"Address": "Kumlagatan 3 lgh 1205",
"Address2": null,
"PostalCode": "53392",
"Location": null,
"City": "Lundsbrunn",
"Province": null,
"CountryCode": "se",
"Phone": null,
"Email": null,
"PhoneNumbers": ["070-7001127", "070-7001130"],
"_DataSource": null,
"FullName": "Linda Marie Hassan Ahmed"
}
}
```
---
## SearchPerson 🇸🇪, 🇳🇴, 🇫🇮, 🇩🇰
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](https://developers.zignsec.com/legacy/register-checks#searchperson)
where `env` is API or test.
## Parameters
In the Query node level:
| | |
|---|---|
|CountryCode|Mandatory parameter. Sets the country to query in.|
|FirstName||
|LastName||
|DateOfBirth|In the form YYYYMMDD or YYYY-MM-DD|
|Phone|Enables search by phone number where service is available.|
|Address|Street name and number etc.|
|PostalCode||
|City||
In the root node level:
| | |
|---|---|
|Environment|Optional parameter. See **[Environment](https://docs.zignsec.com/faq/common-data/#environment)** at the Common Data documentation.|
|_DataSource|Optional parameter. For specifying the underlying search provider to be used.|
[Sample of Test persons can be found here.](http://docs.zignsec.com/faq/test-persons-for-searchperson/)
### Example request for a Swedish search
Example of Response with 2 hits from above query (Swedish population register) : The PersonsFound node contains an array of **[address](https://docs.zignsec.com/faq/common-data/#addressmodel)** 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](https://docs.zignsec.com/faq/common-data/#subscore) array.
```swift
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"
}
}
```
#### Response
```swift
{
"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
```swift
{
"Query":{
"FirstName":"Jens",
"LastName":"Mortensen",
"CountryCode":"dk",
"postalcode":"6800",
"address":"Boulevarden 101"
}
}
```
Example of a Danish population register search Response:
```swift
{
"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
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.
```swift
{
"Query":{
"CountryCode": "no",
"City": "oslo",
"FirstName": "Ole",
"LastName": "Bramserud",
"Address": " ",
"DateOfBirth": "1959-11-23
}
}
```
#### Response
```swift
{
"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)
```swift
{
"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.
```swift
{
"Query":
{
"LastName":"Duncan",
"CountryCode":"fi",
"City":"Helsinki"
},
"environment":"test"
}
```
Response for SearchPerson Finland:
```swift
{
"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"
}
]
}
```
---
## VerifyPerson 🇸🇪
VerifyPerson service looks up a citizen’s address and birth data from the national population registry, by a narrowing query workflow with 18 separate query steps. The query must include the `countryCode`, and currently only countryCode “se”, Sweden, is supported.
The response count is currently limited to at most one best hit. But in case of not single best hit available a “No hit” will be returned.
The hit is of type: **[address](https://docs.zignsec.com/faq/common-data/#addressmodel)** .
### API
[Set up:](https://developers.zignsec.com/legacy/register-checks#verifyPerson) POST to _https://`env`.zignsec.com/v2/ekyc/verifyperson_ where `env` is **API** or **test**.
## Request
|**Name**|**Description**|**Required**|
|---|---|---|
|Query|[Address](https://docs.zignsec.com/faq/common-data/#addressmodel) model|Required|
|PersonalNumber|Personal number. Give as 12 digits.|Optional|
|DateOfBirth|Give as `yyyymmdd`/`yyyy-mm-dd`, `yyyymm`/`yyyy-mm` or `yyyy`. The hyphen separating the date parts is optional.|Optional|
|MatchSteps|Gives a possibility to limit what kind of queries to include. Default is all rules: 1,2,3,...18<br><br>- 1 – personalNumber, firstName, lastName, address, postalCode, city<br>- 2 – personalNumber, firstName, lastName, postalCode<br>- 3 – personalNumber, firstName, lastName, city<br>- 4 – personalNumber, firstName, lastName<br>- 5 – personalNumber, phoneNr<br>- 6 – personalNumber<br>- 7 – firstName, lastName, address, postalCode, city<br>- 8 – firstName, lastName, address, postalCode<br>- 9 – firstName, lastName, address, city<br>- 10 – firstName, lastName, address<br>- 11 – firstName, lastName, postalCode, city<br>- 12 – firstName, lastName, postalCode<br>- 13 – firstName, lastName, postalCode(first two)<br>- 14 – firstName, lastName, city<br>- 15 – firstName, lastName<br>- 16 – firstName, lastName, phoneNr<br>- 17 – firstName, postalCode, phoneNr<br>- 18 – lastName, postalCode, phoneNr|Optional|
|VerifyAge|Sets the Verify Age of searched person. There is `AgeVerificationFaulted` in response model that set verified user or not.|Optional|
**Request example:**
```swift
POST https://test.zignsec.com/v2/ekyc/verifyperson HTTP/1.1
Content-Type: application/json; charset=UTF-8
Authorization: yourkey-here.
{
"Query":{
"FirstName":"Sara Maria",
"LastName":"Karlsson",
"Gender":"Female",
"Address":"Vasavägen",
"PostalCode":"67040",
"CountryCode": "se"
}
}
```
**Response**
on root level
|**Name**|**Description**|
|---|---|
|WasFound|Boolean.|
|Persons|Array of hits, currently at most one best hit. [Address](http://docs.zignsec.com/api/common-data/#addressmodel) model.|
|ResponseCode|String. Possible values `SingleMatch`, `MultipleMatches`, `TooManyMatches`, `NoMatch`.|
Address model you can find [here](https://docs.zignsec.com/faq/common-data/#addressmodel). There are additional fields to model:
|**Name**|**Description**|
|---|---|
|AgeVerificationFaulted|Boolean. Indicates that the user has a verified by age set in the request field `VerifyAge`|
|MatchedStep|Specifies, which rule was run to get the hit(s).|
|MatchedStepDescription|Specifies, in [text form](https://developers.zignsec.com/legacy/register-checks#MatchStepDescription), which rule was run to get the hit(s). `personalNumber` string can be replaced by `personalNumber (partial)` if the search includes a `dateOfBirth` field.|
### How to test
Here is a link to an excel sheet which contains test data which can be used to test the products.
[Link to testdata](https://25357801.fs1.hubspotusercontent-eu1.net/hubfs/25357801/Support%20Files/TestdatabasPersoner.xlsx)
---
## Validate Identity global
This service verifies a person’s address or identity information such as name and address via background data source lookups in a multitude of registers. The list of supported countries is large and is expanded through quick configuration.
### APIs
[Set up:](https://developers.zignsec.com/legacy/register-checks#validateIdRequest)POST to https://`env`.zignsec.com/v2/ekyc/validateidentity where `env` is API or test.
### MatchLevel
The main response is a `MatchLevel` set to HIGH, MEDIUM or LOW indicating the similarity between the in-data and the best found match in the specified country.
- **HIGH** – a very good match – The data item (ex user) should be accepted as referring to the same item (ex individual).
- **MEDIUM** – a **business decision**. Maybe the item (ex user) could be accepted but needs manual inspection.
- **LOW** – a poor match – The data item (ex user) should **not** be accepted as the items are too different.
### ValidationMethod and the Pricing Level
To know more about the price level, please contact sales.
## 1. ValidationMethods:
**Validate identity id1x1:**
Queries until found in one data source allows:
- a. validate identity fields. See more details in [zignsec_id_1x1-1.pdf](https://docs.zignsec.com/wp-content/uploads/2022/04/zignsec_id_1x1-1.pdf)
- b. Validate Name, National ID and Date of birth. [NID matchguide](https://docs.zignsec.com/wp-content/uploads/2021/05/Validate_Identity_Remaining-matchguide_V2.pdf)
- c. Validate Name_Address_ID. [NAI_Match Guide](https://docs.zignsec.com/wp-content/uploads/2021/06/NAI_Match-Guide.pdf)
- d. Validate Name_Address_ID. [NAI_v2_Match Guide](https://docs.zignsec.com/wp-content/uploads/2021/06/NAI_v2_Match-Guide.pdf)
- e. Validate Name_Address
**2. Validate identity id2x2:** Queries until found in two data sources. Suitable for UK.
[MatchGuide for Validate_Identity_Default_2x2](https://docs.zignsec.com/wp-content/uploads/2021/06/MatchGuide_Validate_Identity_Default_2x2.pdf)
Note that the different tenants described above are available in different countries. You can check the coverage with sales or support service. You can select a specialized query configuration with the `ValidationMethod` parameter. Contact ZignSec for the correct set up.
### Test Data and Tuning
[In our test environment we query against a cache of test persons listed in a table here.](http://docs.zignsec.com/wp-content/uploads/2018/06/testdata.htm)
The test cache is designed for integration testing and validation not for quality or match rate tuning, we would suggest using live data for that.
[Here is a link to global_sourcebook](https://www.grcdi.nl/gsb/global%20sourcebook.html) – a site with excellent coverage of address formats country per country. Click on the Country, and then on the link Addresses or Address examples.
## Parameters
On the Query node level:
| | |
|---|---|
|CountryCode|Mandatory parameter. Sets the country to query in. This should be in the 2 digit code format (ISO 3166-1) [https://www.nationsonline.org/oneworld/country_code_list.htm](https://www.nationsonline.org/oneworld/country_code_list.htm)|
|FirstName||
|LastName||
|DateOfBirth|In the form YYYY-MM-DD|
|PersonalNumber|The national identity number|
|MobileNumber|Enables search by phone number where service is available.|
|Address|First address line, normally street name and number, possibly other info such as floor.|
|Address2|An optional second address line.|
|PostalCode||
|City||
On the root level:
| | |
|---|---|
|**Environment**|Optional parameter. Can switch between test/prod for easier testing. See [Environment](http://docs.zignsec.com/api/common-data/#environment) at the Common Data documentation.|
|**QuerySettings**|Optional settings for the query. ValidationMethod: Use a specified validation method, for example requiring that two data sources are needed.|
|**ResponseFormat**|Possible values: <br>`flat`: Strings format. Readable format. <br>`structured`: Object format. JSON parsing format.|
**Request example:**
```swift
POST https://test.zignsec.com/v2/ekyc/validateIdentity HTTP/1.1
User-Agent: Fiddler
Content-Length: 200
Content-Type: application/json; charset=UTF-8
Authorization: YOUR ACCESS TOKEN
Host: test.zignsec.com
{
"Query": {
"FirstName":"Viktor",
"LastName":"Rydberg",
"CountryCode":"SE",
"Address":"SOMMARBO 207",
"PostalCode":"13767",
"City":"JORDBRO",
"DateOfBirth":"1971-02-01"
}
}
```
**Response example**
```swift
{
"id": "adc94a88-262a-428e-b721-93213c5d3d00",
"errors": [],
"DetailCode": "WS-646267.2019.10.29.8.55.27.643",
"MatchLevel": "HIGH",
"VerifiedAge":48,
"WasFound": true,
"ValidationMethod": "GDC_ValidateIdentitySvc_env (tenant=zignsec_test)",
"ValidationDetailsFLAT": [
"Total match level: HIGH",
"Validation strategy: 1+1",
"Validation country: SE",
"Match results per field:",
"CompleteName | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | FullName=Victor Rydberg",
"FirstInitial | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | =...",
"FirstName | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | FirstName=Victor",
"LastName | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | LastName=Rydberg",
"Address | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | Address=SOMMARBO 207",
"HouseNumber | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | Address=SOMMARBO 207",
"ThoroughFare | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | Address=SOMMARBO 207",
"Locality | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | City=JORDBRO",
"PostalCode | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | PostalCode=13767",
"DateOfBirth | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | DateOfBirth=1971-02-01",
"DayOfBirth | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | DateOfBirth=1",
"MonthOfBirth | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | DateOfBirth=2",
"YearOfBirth | Total=MTC | CNS1=MTC | GVT1=MTC | TEL2=MTC | DateOfBirth=1971",
"SubPremise | Total= | CNS1=_X_ | GVT1=_X_ | TEL2=_X_ | Address=SOMMARBO 207"
],
"ValidationDetails": {
"1MT-SE-CNS1-COMPLETENAME": "Full match was made on Complete Name",
"1MT-SE-CNS1-FIRSTINITIAL": "Full match was made on First Initial",
"1MT-SE-CNS1-FIRSTNAME": "Full match was made on First Name/Given Name",
"1MT-SE-CNS1-LASTNAME": "Full match was made on Last Name/Surname ",
"1MT-SE-CNS1-ADDRESS": "Full match was made on address elements provided in Address Lines",
"1MT-SE-CNS1-HOUSENUMBER": "Full match was made on House Number/Street Number",
"1MT-SE-CNS1-THOROUGHFARE": "Full match was made on Street/Thoroughfare",
"1MT-SE-CNS1-LOCALITY": "Full match was made on City/Locality",
"1MT-SE-CNS1-POSTALCODE": "Full match was made on Postal Code/Zip Code",
"1MT-SE-CNS1-DATEOFBIRTH": "Full match was made on Date of Birth",
"1MT-SE-CNS1-DAYOFBIRTH": "Full match was made on Day of Birth",
"1MT-SE-CNS1-MONTHOFBIRTH": "Full match was made on Month of Birth",
"1MT-SE-CNS1-YEAROFBIRTH": "Full match was made on Year of Birth",
"4MT-SE-CNS1-SUBPREMISE": "Datasource does not contain element Sub Premise Descriptors provided in Address Lines",
"1MT-SE-GVT1-COMPLETENAME": "Full match was made on Complete Name",
"1MT-SE-GVT1-FIRSTINITIAL": "Full match was made on First Initial",
"1MT-SE-GVT1-FIRSTNAME": "Full match was made on First Name/Given Name",
"1MT-SE-GVT1-LASTNAME": "Full match was made on Last Name/Surname ",
"1MT-SE-GVT1-ADDRESS": "Full match was made on address elements provided in Address Lines",
"1MT-SE-GVT1-HOUSENUMBER": "Full match was made on House Number/Street Number",
"1MT-SE-GVT1-THOROUGHFARE": "Full match was made on Street/Thoroughfare",
"1MT-SE-GVT1-LOCALITY": "Full match was made on City/Locality",
"1MT-SE-GVT1-POSTALCODE": "Full match was made on Postal Code/Zip Code",
"1MT-SE-GVT1-DATEOFBIRTH": "Full match was made on Date of Birth",
"1MT-SE-GVT1-DAYOFBIRTH": "Full match was made on Day of Birth",
"1MT-SE-GVT1-MONTHOFBIRTH": "Full match was made on Month of Birth",
"1MT-SE-GVT1-YEAROFBIRTH": "Full match was made on Year of Birth",
"4MT-SE-GVT1-SUBPREMISE": "Datasource does not contain element Sub Premise Descriptors provided in Address Lines",
"1MT-SE-TEL2-COMPLETENAME": "Full match was made on Complete Name",
"1MT-SE-TEL2-FIRSTINITIAL": "Full match was made on First Initial",
"1MT-SE-TEL2-FIRSTNAME": "Full match was made on First Name/Given Name",
"1MT-SE-TEL2-LASTNAME": "Full match was made on Last Name/Surname ",
"1MT-SE-TEL2-ADDRESS": "Full match was made on address elements provided in Address Lines",
"1MT-SE-TEL2-HOUSENUMBER": "Full match was made on House Number/Street Number",
"1MT-SE-TEL2-THOROUGHFARE": "Full match was made on Street/Thoroughfare",
"1MT-SE-TEL2-LOCALITY": "Full match was made on City/Locality",
"1MT-SE-TEL2-POSTALCODE": "Full match was made on Postal Code/Zip Code",
"1MT-SE-TEL2-DATEOFBIRTH": "Full match was made on Date of Birth",
"1MT-SE-TEL2-DAYOFBIRTH": "Full match was made on Day of Birth",
"1MT-SE-TEL2-MONTHOFBIRTH": "Full match was made on Month of Birth",
"1MT-SE-TEL2-YEAROFBIRTH": "Full match was made on Year of Birth",
"4MT-SE-TEL2-SUBPREMISE": "Datasource does not contain element Sub Premise Descriptors provided in Address Lines",
"1AU-425-COMPLETENAME": "Full match was made on Complete Name",
"1AU-375-FIRSTINITIAL": "Full match was made on First Initial",
"1AU-350-FIRSTNAME": "Full match was made on First Name/Given Name",
"1AU-400-LASTNAME": "Full match was made on Last Name/Surname ",
"1AU-200-ADDRESS": "Full match was made on address elements provided in Address Lines",
"1AU-150-HOUSENUMBER": "Full match was made on House Number/Street Number",
"1AU-175-THOROUGHFARE": "Full match was made on Street/Thoroughfare",
"1AU-250-LOCALITY": "Full match was made on City/Locality",
"1AU-275-POSTALCODE": "Full match was made on Postal Code/Zip Code",
"1AU-550-DATEOFBIRTH": "Full match was made on Date of Birth",
"1AU-575-DAYOFBIRTH": "Full match was made on Day of Birth",
"1AU-600-MONTHOFBIRTH": "Full match was made on Month of Birth",
"1AU-625-YEAROFBIRTH": "Full match was made on Year of Birth",
"Codes": "1AU-150-HOUSENUMBER;1AU-175-THOROUGHFARE;1AU-200-ADDRESS;1AU-250-LOCALITY;1AU-275-POSTALCODE;1AU-350-FIRSTNAME;1AU-375-FIRSTINITIAL;1AU-400-LASTNAME;1AU-425-COMPLETENAME;1AU-550-DATEOFBIRTH;1AU-575-DAYOFBIRTH;1AU-600-MONTHOFBIRTH;1AU-625-YEAROFBIRTH;1MT-SE-CNS1-ADDRESS;1MT-SE-CNS1-COMPLETENAME;1MT-SE-CNS1-DATEOFBIRTH;1MT-SE-CNS1-DAYOFBIRTH;1MT-SE-CNS1-FIRSTINITIAL;1MT-SE-CNS1-FIRSTNAME;1MT-SE-CNS1-HOUSENUMBER;1MT-SE-CNS1-LASTNAME;1MT-SE-CNS1-LOCALITY;1MT-SE-CNS1-MONTHOFBIRTH;1MT-SE-CNS1-POSTALCODE;1MT-SE-CNS1-THOROUGHFARE;1MT-SE-CNS1-YEAROFBIRTH;1MT-SE-GVT1-ADDRESS;1MT-SE-GVT1-COMPLETENAME;1MT-SE-GVT1-DATEOFBIRTH;1MT-SE-GVT1-DAYOFBIRTH;1MT-SE-GVT1-FIRSTINITIAL;1MT-SE-GVT1-FIRSTNAME;1MT-SE-GVT1-HOUSENUMBER;1MT-SE-GVT1-LASTNAME;1MT-SE-GVT1-LOCALITY;1MT-SE-GVT1-MONTHOFBIRTH;1MT-SE-GVT1-POSTALCODE;1MT-SE-GVT1-THOROUGHFARE;1MT-SE-GVT1-YEAROFBIRTH;1MT-SE-TEL2-ADDRESS;1MT-SE-TEL2-COMPLETENAME;1MT-SE-TEL2-DATEOFBIRTH;1MT-SE-TEL2-DAYOFBIRTH;1MT-SE-TEL2-FIRSTINITIAL;1MT-SE-TEL2-FIRSTNAME;1MT-SE-TEL2-HOUSENUMBER;1MT-SE-TEL2-LASTNAME;1MT-SE-TEL2-LOCALITY;1MT-SE-TEL2-MONTHOFBIRTH;1MT-SE-TEL2-POSTALCODE;1MT-SE-TEL2-THOROUGHFARE;1MT-SE-TEL2-YEAROFBIRTH;4MT-SE-CNS1-SUBPREMISE;4MT-SE-GVT1-SUBPREMISE;4MT-SE-TEL2-SUBPREMISE;",
"1MT-SE-MATCHED-1+1": "Full Match for 1+1 verification"
}
}
```