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

POST to https://env.zignsec.com/v2/ekyc/validateidentity
where env is api or test.

Note: ValidateAddress is a older method without possibility to check PersonalNumber or DateOfBirth.

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

The pricing level can be set automatically to the cheapest option for the actual query combination and the countryCode.
ValidationMethods:

  • addr1x1: Queries until found in one data source and does Not validate any of the identity fields DateOfBirth and PersonalNumber
  • id1x1: Queries until found in one data source and allows validation of identity fields
  • id2x2: Queries until found in two data sources. Suitable for UK.

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 betwween 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.

Example call for ValidateIdentity:

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

Example Response:

{
	"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)",
	"ValidationDetailsFLAT": [
		"Total match level: HIGH",
		"Validation strategy: Not set",
		"Validation country: Not set",
		"Match results per field:",
		"CompleteName    | Total=MTC | CNS2=MTC | FullName=Victor Cassel",
		"FirstInitial    | Total=MTC | CNS2=MTC | =...",
		"FirstName       | Total=MTC | CNS2=MTC | FirstName=Victor",
		"LastName        | Total=MTC | CNS2=MTC | LastName=Cassel",
		...
	],
	"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"
	}
}
DetailCodeA call-unique reference string from GDC, 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.
ValidationDetailsFLATFlat readable format of validation result.
ValidationDetailsStructuredStructured format of validation result.
ValidationDetailsValidation details format from GDC.
ValidationMethodIs the actual validation method used during the querying, wheter 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.  

Example call for ValidateIdentity for 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"
}

Example Response:

{
	"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 from GDC.
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, accross 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