Verfiy Identity
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.
Step 1 : Start Identity Verification Session
POST to
Test enviornment : https://test-gateway.zignsec.com/core/api/sessions/identity_check/gdc
Production enviornment : https://gateway.zignsec.com/core/api/sessions/identity_check/gdc
ValidationMethod and the Pricing Level
To know more about the price level, please contact sales.
ValidationMethods:
- id1x1: Queries until found in one data source allows:
- validate identity fields see more details in Match Guide_Default_1x1
- Validate Name, National ID and Date of birth NID matchguide
- Validate Name_Address_ID NAI_Match Guide
- Validate Name_Address_ID v2 NAI_v2_Match Guide
- Validate Name_Address
- id2x2: Queries until found in two data sources. Suitable for UK.
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.
1.1 Request example
POST https://test-gateway.zignsec.com/core/api/sessions/identity_check/gdc
Content-Type : application/json
Authorization : 12345678-YOUR-ACCESS-TOKEN-5352305c9fb0
Content-Length :725
{
"metadata": {
"address": {
"address_line1": "DAVTASHEN 4TAX 4-22",
"city": "YEREVAN",
"country_code": "AM",
"house_number": "4-22",
"postal_code": "10"
},
"birth_date": "1974-02-17",
"first_name": "MESROP",
"last_name": "MASHTOTS",
"national_id": "AH0278181",
"options": [
"IdentityVerify"
]
},
"relay_state": "string",
"webhook": "string"
}
1.2 Description of request model
| Parameter | Description | Required |
| metadata | Contain parameters like : address_line1, city , country_code etc | Yes |
| address | addressLine1 , addressLine2 , addressLine3 | |
| city | City | |
| country_code | Two letter ISO country code | |
| house_number | House number | |
| province | Region dependent. (For example can be used to specify USA state) | |
| birth_date | Date of birth (YYYY-MM-DD or YYYYMMDD) | |
| first_name | First name | |
| last_name | Last name | |
| national_id | National ID (ex. Social Security Number – SSN) | |
| options | IdentityVerify – For those countries that support this feature the service will attempt to verify the identity with the best match using all provided input data. Note that when running this option, the input data may be corrected in the data quality step and this may affect identity results. NativeOutputScript – Address option. Return the validated or verified result in the native alphabet. For example Greek for Greece, Cyrillic for Russia, and Arabic for the UAE. LowerCase – Address option. Return all data in lower case where possible. GeoCoding – Address option. Attempt to geocode the address results AFTER verification and append a latitude and longitude to the return., | |
| provider_parameters | Provider parameters. (Used to pass request parameters to the upstream data provider) | |
| tenant | Tenant. Optional parameter to overwrite default tenant | |
| relay_state | Optional Custom Parameter to be included in webhook calls | |
| webhook | Webhook URL where your backend will receive session events. |
Note:
* The system requires a minimum of Complete Name, Zip Code and Country code to make a minimal Identity Verification check. Generally speaking, the more information that is provided with the request, the better the confidence in the match.
Additionally, it is best practice to provide additional inputs when making an Identity call such as DOB. Certain countries and data sources have mandatory, required fields that are necessary to successfully obtain a result from the service. The required input fields vary by country. In Argentina, China, Brazil and Mexico is best practice to provide a National Identifier. In the United States, it is best practice to provide State (Administrative Area).
In the test environment the ValidateAddress and ValidateIdentity calls query against a table of pre-defined set of test persons per country. See it in Test_cache
1.3 Example of Response Body
{
"data": {
"errors": [],
"id": "cdb06f85-1327-4e72-a1ed-ea08db5be46e",
"result": {
"fieldMatches": [
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Complete Name",
"fieldName": "COMPLETENAME",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on First Initial",
"fieldName": "FIRSTINITIAL",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on First Name/Given Name",
"fieldName": "FIRSTNAME",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Last Name/Surname ",
"fieldName": "LASTNAME",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Postal Code/Zip Code",
"fieldName": "POSTALCODE",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on National ID",
"fieldName": "NATIONALID",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Date of Birth",
"fieldName": "DATEOFBIRTH",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Day of Birth",
"fieldName": "DAYOFBIRTH",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Month of Birth",
"fieldName": "MONTHOFBIRTH",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Full match was made on Year of Birth",
"fieldName": "YEAROFBIRTH",
"matchType": "FullMatch"
},
{
"countryCode": "AM",
"dataSource": "Commercial",
"dataSourceNumber": 9,
"description": "Partial match made on element Address Lines",
"fieldName": "ADDRESS",
"matchType": "PartialMatch"
}
],
"matchLevel": "Medium",
"providerData": {
"address": {
"timezone": "",
"countryISO3": "ARM",
"countryName": "Armenia",
"addressLine10": "",
"countryCode": "AM",
"lotNumber": "",
"formalCountryName": "Republic of Armenia",
"dpvFootnotes": "",
"houseNumberAddition": "",
"premise": "",
"dpvIsVacant": "",
"addressLine2": "YEREVAN",
"postIndicator": "",
"addressLine5": "",
"dpvIsPBSA": "",
"latitude": "",
"dpvIsCMRA": "",
"dpvCoded": "",
"countyCode": "",
"addressLine4": "",
"eggCode": "",
"municipalityCode": "",
"lacsIndicator": "",
"locality": "",
"hausCode": "",
"census": "",
"department": "",
"addressLine7": "",
"dpvIsNoStat": "",
"county": "",
"postBox": "",
"addressLine8": "",
"postTown": "",
"longitude": "",
"congressionalDistrict": "",
"addressLine6": "",
"urbanization": "",
"cebucoCode": "",
"province": "string",
"codes": {
"adaptation": "30",
"detailCode": "WS-851504.2022.3.28.8.44.22.393",
"detailList": "",
"detail_list": "",
"messages": [],
"options": "Debug;IdentityVerify;MessageVerbose",
"reliability": "30"
},
"addressLine1": "DAVTASHEN 4TAX 4-22",
"postalCode": "10",
"houseNumber": "4-22",
"countryNumber": "51",
"urbanArea": "",
"building": "",
"subDistrict": "",
"addressLine9": "",
"dpvIndicator": "",
"district": "",
"name": "",
"thoroughfare": "string",
"preIndicator": "",
"addressLine3": "",
"provinceCode": "",
"organization": ""
},
"codes": {
"adaptation": "30",
"detailCode": "WS-851504.2022.3.28.8.44.22.393",
"detailList": "",
"detail_list": "",
"messages": [],
"options": "Debug;IdentityVerify;MessageVerbose",
"reliability": "30"
},
"email": {
"addressee": "",
"codes": {
"adaptation": "30",
"detailCode": "WS-851504.2022.3.28.8.44.22.393",
"detailList": "",
"detail_list": "",
"messages": [
{
"code": "WV",
"value": "Email could not be verified. Original input returned."
}
],
"options": "Debug;IdentityVerify;MessageVerbose",
"reliability": "30"
},
"countryCode": "AM",
"displayName": "",
"display_name": "",
"domain": "",
"fullEmailAddress": "",
"full_email_address": "",
"topLevel": "",
"top_level": ""
},
"identity": {
"indicator": "",
"gender": "",
"nationalid": "AH0278181",
"qualification_int_second": "",
"surname_prefix_first": "",
"organization_name": "",
"surname_prefix_second": "",
"countryCode": "AM",
"businessid": "",
"qualificationIntFirst": "",
"passport": "",
"organizationName": "",
"formofaddress": "",
"qualification_int_first": "",
"givennameinitials": "",
"surnamePrefixFirst": "",
"qualificationIntSecond": "",
"contact_type": "",
"givenfullname": "MESROP",
"qualification_suceeding": "",
"completename": "",
"surname_first": "MASHTOTS",
"surnamePrefixSecond": "",
"qualificationpreceding": "",
"name_qualified": "",
"contactType": "",
"codes": {
"adaptation": "0",
"detailCode": "WS-851504.2022.3.28.8.44.22.393",
"detailList": "",
"detail_list": "",
"messages": [
{
"code": "1MT-AM-CMM9-COMPLETENAME",
"value": "Full match was made on Complete Name"
},
{
"code": "1MT-AM-CMM9-FIRSTINITIAL",
"value": "Full match was made on First Initial"
},
{
"code": "1MT-AM-CMM9-FIRSTNAME",
"value": "Full match was made on First Name/Given Name"
},
{
"code": "1MT-AM-CMM9-LASTNAME",
"value": "Full match was made on Last Name/Surname "
},
{
"code": "1MT-AM-CMM9-POSTALCODE",
"value": "Full match was made on Postal Code/Zip Code"
},
{
"code": "1MT-AM-CMM9-NATIONALID",
"value": "Full match was made on National ID"
},
{
"code": "1MT-AM-CMM9-DATEOFBIRTH",
"value": "Full match was made on Date of Birth"
},
{
"code": "1MT-AM-CMM9-DAYOFBIRTH",
"value": "Full match was made on Day of Birth"
},
{
"code": "1MT-AM-CMM9-MONTHOFBIRTH",
"value": "Full match was made on Month of Birth"
},
{
"code": "1MT-AM-CMM9-YEAROFBIRTH",
"value": "Full match was made on Year of Birth"
},
{
"code": "3MT-AM-CMM9-ADDRESS",
"value": "Partial match made on element Address Lines"
},
{
"code": "1AU-425-COMPLETENAME",
"value": "Full match was made on Complete Name"
},
{
"code": "1AU-375-FIRSTINITIAL",
"value": "Full match was made on First Initial"
},
{
"code": "1AU-350-FIRSTNAME",
"value": "Full match was made on First Name/Given Name"
},
{
"code": "1AU-400-LASTNAME",
"value": "Full match was made on Last Name/Surname "
},
{
"code": "1AU-275-POSTALCODE",
"value": "Full match was made on Postal Code/Zip Code"
},
{
"code": "1AU-525-NATIONALID",
"value": "Full match was made on National ID"
},
{
"code": "1AU-550-DATEOFBIRTH",
"value": "Full match was made on Date of Birth"
},
{
"code": "1AU-575-DAYOFBIRTH",
"value": "Full match was made on Day of Birth"
},
{
"code": "1AU-600-MONTHOFBIRTH",
"value": "Full match was made on Month of Birth"
},
{
"code": "1AU-625-YEAROFBIRTH",
"value": "Full match was made on Year of Birth"
},
{
"code": "3AU-200-ADDRESS",
"value": "Partial match made on element Address Lines"
},
{
"code": "Codes",
"value": "1AU-275-POSTALCODE;1AU-350-FIRSTNAME;1AU-375-FIRSTINITIAL;1AU-400-LASTNAME;1AU-425-COMPLETENAME;1AU-525-NATIONALID;1AU-550-DATEOFBIRTH;1AU-575-DAYOFBIRTH;1AU-600-MONTHOFBIRTH;1AU-625-YEAROFBIRTH;1MT-AM-CMM9-COMPLETENAME;1MT-AM-CMM9-DATEOFBIRTH;1MT-AM-CMM9-DAYOFBIRTH;1MT-AM-CMM9-FIRSTINITIAL;1MT-AM-CMM9-FIRSTNAME;1MT-AM-CMM9-LASTNAME;1MT-AM-CMM9-MONTHOFBIRTH;1MT-AM-CMM9-NATIONALID;1MT-AM-CMM9-POSTALCODE;1MT-AM-CMM9-YEAROFBIRTH;3AU-200-ADDRESS;3MT-AM-CMM9-ADDRESS;"
}
],
"options": "Debug;IdentityVerify;MessageVerbose",
"reliability": "20"
},
"surnameFirst": "MASHTOTS",
"function": "",
"nationality": "",
"nameQualified": "",
"dob": "02/17/1974",
"qualificationSuceeding": ""
},
"phone": {
"areaCode": "",
"area_code": "",
"callingCode": "",
"callingFrom": "",
"calling_code": "",
"calling_from": "",
"codes": {
"adaptation": "30",
"detailCode": "WS-851504.2022.3.28.8.44.22.393",
"detailList": "",
"detail_list": "",
"messages": [
{
"code": "WV",
"value": "Phone could not be verified. Original input returned."
}
],
"options": "Debug;IdentityVerify;MessageVerbose",
"reliability": "30"
},
"countryCode": "AM",
"formattedInternational": "",
"formatted_international": "",
"internationalPrefix": "",
"international_prefix": "",
"lineType": "",
"line_type": "",
"name": "",
"number": "",
"phoneNumber": "",
"phone_number": "",
"timezone": "",
"trunk": ""
}
}
},
"status": "Finished"
}
}
1.4 Description of Response Body
| id | Unique session identifier, used for GET Request . |
| country_code | Country code |
| data_source | [Credit – Data sources containing Credit Bureau, Credit Registry, Credit Monitoring Services and/or other credit related data sources which can be used in a country to identify an individual. Examples of credit could be Credit Header Records from Bureau data, Credit Monitoring databases, debt management, and potentially bankruptcy or financial statements., Government – A government, public, or public/private partnership providing data sources covering individuals or citizens in a country or countries. Examples of government could be electoral rolls, census data, citizenship databases, and real estate or tax data sets., Commercial – Commercial data is sourced from commerce-based transaction data, registers of professionals, consumer and marketing data sources. Examples of commercial include professional membership directory data, publishing and media (including television) subscriber data, direct mail, e-commerce consumer and loyalty card program databases., Consumer – Consumer data is a sub-set of Commercial data that comes from marketing sources with opt-in/consent. Examples of consumer could be digital consumer data sources, direct mail, e-commerce, and loyalty card programs, and lead generation., Utility – Data sourced from utility billing, customer profile, provisioning and management records for electric, gas, water, sewer, internet, cable, and public/private utility companies in a country or region. Examples of utility could be electric bill statements data, customer records on delivery of electrical or gas services, and utility databases used for customer communication., Proprietary – Data sources which are typically either unique to a region or country, private in the nature of the data acquisition, and cannot be classified into any other specific data source type., TelephoneCompany – Data sources from telephone/telco companies and their affiliates which include mobile, landline and telephone registry data. Examples of telco could be whitepages telco registries, HLR/VLR databases, telco customer databases and customer billing and invoicing records., Postal – Data sources from government and quasi-governmental postal authorities. These data sets may also include delivery data from private couriers, package delivery, and geospatial providers. Examples of postal could range from Change of Address (COA) databases, receipt and delivery verification databases, and postal address registries., OtherDataSource – Other data source] |
| data_source_number | Data source number. Often multiples of the same type of data source are available in a specific country this number helps to distinguish between them |
| field_name | Name of the field that was matched |
| match_type | [ NoMatch, PartialMatch, FullMatch, Missing ] NoMatch – Element did not match with the data source, PartialMatch – Element partially matched with the data source, FullMatch – Element fully matched with the data source, Missing – Element is not contained in the data source |
| match_level | [ High, Medium, Low ] High – A very good match, Medium – Could be accepted but need a manual inspection, Low – A poor match |
| provider_data | Data returned from provider |
| status | [ Created, Finished, Failed, Timeout ] |
Step 2 : Get Session Result
GET to https://test-gateway.zignsec.com/core/api/sessions/{sessionId}
Swagger Links
Test enviornment : https://test-gateway.zignsec.com/#/Session%20Data/getSessionById
Production enviornment : https://gateway.zignsec.com/#/Session%20Data/getSessionById
Gets GDC identity verification session by ID
Data Source List
Name | Definition |
| Credit | – Data sources containing Credit Bureau, Credit Registry, Credit Monitoring Services and/or other credit related data sources which can be used in a country to identify an individual. Examples of credit could be Credit Header Records from Bureau data, Credit Monitoring databases, debt management, and potentially bankruptcy or financial statements. |
| Government | – A government, public, or public/private partnership providing data sources covering individuals or citizens in a country or countries. Examples of government could be electoral rolls, census data, citizenship databases, and real estate or tax data sets. |
| Commercial | – Commercial data is sourced from commerce-based transaction data, registers of professionals, consumer and marketing data sources. Examples of commercial include professional membership directory data, publishing and media (including television) subscriber data, direct mail, e-commerce consumer and loyalty card program databases. |
| Consumer | Consumer data is a sub-set of Commercial data that comes from marketing sources with opt-in/consent. Examples of consumer could be digital consumer data sources, direct mail, e-commerce, and loyalty card programs, and lead generation. |
| Utility | – Data sourced from utility billing, customer profile, provisioning and management records for electric, gas, water, sewer, internet, cable, and public/private utility companies in a country or region. Examples of utility could be electric bill statements data, customer records on delivery of electrical or gas services, and utility databases used for customer communication. |
| Proprietary | – Data sources which are typically either unique to a region or country, private in the nature of the data acquisition, and cannot be classified into any other specific data source type. |
| TelephoneCompany | – Data sources from telephone/telco companies and their affiliates which include mobile, landline and telephone registry data. Examples of telco could be whitepages telco registries, HLR/VLR databases, telco customer databases and customer billing and invoicing records. |
| Postal | – Data sources from government and quasi-governmental postal authorities. These data sets may also include delivery data from private couriers, package delivery, and geospatial providers. Examples of postal could range from Change of Address (COA) databases, receipt and delivery verification databases, and postal address registries. |
| OtherDataSource | … |
