ValidateIdentity

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: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 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 need a 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.

ValidationMethods:

  1. id1x1: Queries until found in one data source allows:
    1. validate identity fields see more details in Match Guide_Default_1x1
    2. Validate Name, National ID and Date of birth NID matchguide
    3. Validate Name_Address_ID NAI_Match Guide
    4. Validate Name_Address_ID v2 NAI_v2_Match Guide
    5. Validate Name_Address
  2. id2x2: Queries until found in two data sources. Suitable for UK.
    1. MatchGuide for Validate_Identity_Default_2x2

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.

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 – 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

FirstName 
LastName 
DateOfBirthIn the form YYYY-MM-DD
PersonalNumberThe national identity number
MobileNumberEnables search by phone number where service is available.
AddressFirst address line, normally street name and number, possibly other info such as floor.
Address2An optional second address line.
PostalCode 
City 

On the root level:

EnvironmentOptional parameter. Can switch between test/prod for easier testing. See Environment at the Common Data documentation.
QuerySettings

Optional settings for the query.

ValidationMethodUse a specified validation method, for example requiring that two data sources are needed.
ResponseFormat

Type of response. Possible values:

flatStrings format. Readable format.
structuredObject format. JSON parsing format.
QuerySettingsabcdCDEF
Testing

Request example:

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:

{
    "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"
    }
}
DetailCodeA call-unique reference string for tracing and support issues, for example “WS-2437007.2018.1.14.4.10.57.804”
MatchLevel indicating the similarity between the in-data and the the best found match in the specified country.
VerifiedAgeIf dateOfBirth was validated, this field is set to the person’s current age.
ValidationDetailsFLATFlat readable format of validation result.
ValidationDetailsStructuredStructured format of validation result.
ValidationDetailsValidation details format.
ValidationMethodIs the actual validation method used during the querying, whether automatically or manually selected.

ValidationDetailsFlat

Readable format.

  • First row show Total match level
  • Second row display Validation strategy.
  • Third row display Validation сountry.
  • Match results per field: Informational row.
  • Table view present following columns Source field​, then Total match type, data sources match type and Query.

Types of matching

fzzElement has a degree of fuzzy matching or distance calculation applied his is described in the message.
MTCElement fully matched with the data source.
__0Element did not match with the data source.
_PtElement partially matched with the data source.
_X_Element is not contained in the data source.  

Request Example with structured format:

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"
	},
	"ResponseFormat": "structured"
}

Response Example with structured format:

{
	"id": "2923bcb6-95f2-4e3f-bdf6-392be54b636e",
	"errors": [],
	"DetailCode": "WS-8810289.2019.3.9.7.32.25.23",
	"MatchLevel": "HIGH",
	"ValidationMethod": "GDC_ValidateIdentitySvc_env  (tenant=zignsec_test)",
	"ValidationDetailsStructured": {
	  "TotalMatchLevel": "HIGH",
	  "ValidationStrategy": "1+1",
	  "ValidationCountry": "se",
	  "Details": [
	      {
	        "DataSource": "TOTAL",
	        "MatchLevel": "MTC",
	        "SourceField": "CompleteName",
	        "FieldName": "FullName",
	        "Query": "Viktor Ryd..."
   	     },
  	     {
	        "DataSource": "TOTAL",
	        "MatchLevel": "MTC",
	        "SourceField": "FirstInitial",
	        "FieldName": null,
	        "Query": "..."
	     },
	     {
	        "DataSource": "TOTAL",
	        "MatchLevel": "MTC",
	        "SourceField": "FirstName",
	        "FieldName": "FirstName",
	        "Query": "Viktor"
	     },
	     {
	        "DataSource": "TOTAL",
	        "MatchLevel": "MTC",
	        "SourceField": "LastName",
	        "FieldName": "LastName",
	        "Query": "Rydberg"
	     },
	     {
	        "DataSource": "TOTAL",
	        "MatchLevel": "MTC",
	        "SourceField": "Address",
	        "FieldName": "Address",
	        "Query": "SOMMARBO 2..."
	     }
	     ...
      ]
	},
	"ValidationDetails":
	{
		"1MT-SE-CNS1-COMPLETENAME": "Full match was made on Complete Name",
		"1MT-SE-CNS1-FIRSTINITIAL": "Full match was made on First Initial",
		...,
		"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"
	}
}

ValidationDetailsStructured

Structured format of validation result.

Top Level model

TotalMatchLevelThe overall validation result classification.
ValidationStrategyValidation strategy. Ex: 1+1.
ValidationCountryValidation country.
DetailsList of details item per each data source and field.

Details model

DataSourceData source of validation result.
MatchLevelMatch level type.
SourceFieldSource field for validating.
FieldNameField name from request model.
QueryValue of field from request model.

ValidationDetails

MT stands for match type.

  • 1MT Element fully matched with the data source.
  • 2MT Element did not match with the data source.
  • 3MT Element partially matched with the data source.
  • 4MT Element is not contained in the data source.  

AU Is a summed up match, across all available data sources.

  • 1AU Indicates a complete match was made with the data source from the input element.  
  • 2AU Indicates a non-match of the input element and the data source.
  • 3AU Indicates a partial match was made with the data source from the input element.

Data source types

Note that data source names are not displayed, only the category name:

  • CRD Credit
  • GVT Government
  • CMM Commercial
  • CNS Consumer
  • OTH Other (including social)
  • UTL Utility
  • PRP Proprietary
  • TEL Teleco
  • PST Postal
Copyright © 2024 Zignsec AB. All right reserved